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

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

info

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

.options(...)

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

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

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