AccessPattern

The AccessPattern utility allows you to quickly build QueryCommands on the entity Table :

import { AccessPattern } from 'dynamodb-toolbox/entity/actions/accessPattern'

const highLevelPokemons = PokemonEntity.build(AccessPattern)
  // Define the expected query input schema
  .schema(map({ trainerId: string(), level: number() }))
  // Declare the query pattern
  .pattern(({ trainerId, level }) => ({
    index: 'byLevel',
    partition: trainerId,
    range: { gte: level }
  }))
  // Optional: provide additional options
  .options({ maxPages: 3 })

const { Items } = await highLevelPokemons
  .query({ trainerId, level: 70 })
  .send()

tip

Remember that schemas can be composed or derived from existing ones:

const queryPokemonsByLevel = PokemonEntity
  .build(AccessPattern)
  .schema(pokemonSchema.pick('trainerId', 'level'))

info

For multiple Entities access patterns, see the dedicated AccessPattern Table Action.

Methods

.schema(...)

(required)

Defines the input schema for the pattern parameters (see the Schema Section for more details):

import { string } from 'dynamodb-toolbox/schema/string'

const stringAccessPattern = PokemonEntity
  .build(AccessPattern)
  .schema(string())

.pattern(...)

(required)

Defines how pattern inputs (parsed by the schema) are translated into a query, i.e. an object containing:

• partition: The partition key to query
• index (optional): The name of a secondary index to query
• range (optional): If the table or index has a sort key, an additional Range or Equality Condition
• options (optional): Provide additional context options (merged with default options during query)

const stringAccessPattern = PokemonEntity
  .build(AccessPattern)
  .schema(string())
  .pattern(str => ({
    partition: str,
    options: { reverse: true }
  }))

info

It is advised to provide schema first as it constrains the pattern type.

.options(...)

Provides additional default options to the resulting QueryCommands (see QueryCommands for more details):

const projectedPattern = PokemonEntity
  .build(AccessPattern)
  .options({ attributes: ['name', 'trainerId'] })

You can provide a callback to partially update previous options:

const consistentAccessPattern = accessPattern.options(
  prevOptions => ({ ...prevOptions, consistent: true })
)

To make options dynamic based on the input, provide them via the context options in the pattern method.

.meta(...)

Adds metadata to the AccessPattern.

The meta object can include a title and description, both of which must be strings. Additional fields can be of any type:

const pokemonsByLevelPattern = PokemonEntity.build(AccessPattern)
  .meta({
    title: 'Trainer Pokémons by Level',
    description:
      'Returns the pokemons of a trainer (`trainerId`) above a given level (`minLevel`)',
    other: { field: 'of any type' }
  })

info

Metadata is especially useful when building MCPToolkit Actions.

.query(...)

Produces a QueryCommand from valid pattern inputs:

const queryCommand = highLevelPokemons
  .query({ trainerId, level: 70 })

const { Items } = await queryCommand
  // Optional: Refine queryCommand
  .options({ consistent: true })
  .send()