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

const stringAccessPattern = PokeTable.build(AccessPattern)
  .schema(string())
  .pattern(str => ({ partition: str }))

info

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

.options(...)

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

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

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()