AccessPattern

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

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

const highLevelPokemons = PokeTable.build(AccessPattern)
  // Optional: limit scope to specific entities
  .entities(TrainerEntity, PokemonEntity, ...)
  // 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 = PokeTable.build(AccessPattern)
  .entities(PokemonEntity)
  .schema(pokemonSchema.pick('trainerId', 'level'))

info

For single Entity access patterns, see the dedicated AccessPattern Entity Action.

Methods

.entities(...)

Provides a list of entities to filter the returned items of the resulting QueryCommand (via the internal entity attribute). Also formats them and types the response (see QueryCommands for more details):

const pokemonAccessPattern = PokeTable.build(AccessPattern)
  .entities(TrainerEntity, PokemonEntity, ...)

.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 =
  PokeTable.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 = PokeTable.build(AccessPattern)
  .schema(string())
  .pattern(str => ({
    partition: str,
    options: { reverse: true }
  }))

info

It is advised to provide entities and schema first as they constrain the pattern type.

.options(...)

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

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

You can provide a callback to partially update previous options:

const limitedPattern = accessPattern.options(
  prevOptions => ({ ...prevOptions, limit: 10 })
)

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

info

It is advised to provide entities first as it constrains the options type.

.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 = PokeTable.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()