QueryCommand

Performs a Query Operation on a Table:

import { QueryCommand } from 'dynamodb-toolbox/table/actions/query'

const queryCommand = PokeTable.build(QueryCommand)

const params = queryCommand.params()
const { Items } = await queryCommand.send()

Request

.query(...)

(required)

The partition to query, with optional index and range condition:

• 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

// Get 'ashKetchum' pokemons
await PokeTable.build(QueryCommand)
  .query({ partition: 'ashKetchum' })
  .send()

You can use the Query type to explicitly type an object as a QueryCommand query object:

import type { Query } from 'dynamodb-toolbox/table/actions/query'

// Get 'ashKetchum1' pokemons with a level ≥ 50
const query: Query<typeof PokeTable> = {
  index: 'byTrainerId',
  partition: 'ashKetchum1',
  range: { gte: 50 }
}

const { Items } = await PokeTable.build(QueryCommand)
  .query(query)
  .send()

.entities(...)

Provides a list of entities to filter the returned items (via the internal entity attribute). Also formats them and types the response:

// 👇 Typed as (Pokemon | Trainer)[]
const { Items } = await PokeTable.build(QueryCommand)
  .query(query)
  .entities(PokemonEntity, TrainerEntity)
  .send()

Returned items are also tagged with their respective entity names through the $entity symbol:

import { $entity } from 'dynamodb-toolbox/table/actions/query'

const { Items = [] } = await queryCommand.send()

for (const item of Items) {
  switch (item[$entity]) {
    case "pokemon":
      // 🙌 Typed as Pokemon
      ...
    case "trainer":
      // 🙌 Typed as Trainer
      ...
  }
}

.options(...)

Provides additional options:

const { Items } = await PokeTable.build(QueryCommand)
  .options({
    consistent: true,
    limit: 10
    ...
  })
  .send()

You can use the QueryOptions type to explicitly type an object as a QueryCommand options object:

import type { QueryOptions } from 'dynamodb-toolbox/table/actions/query'

const queryOptions: QueryOptions<
  typeof PokeTable,
  // 👇 Optional entities
  [typeof PokemonEntity, typeof TrainerEntity]
> = {
  consistent: true,
  limit: 10,
  ...
}

const { Items } = await PokeTable.build(QueryCommand)
  .query(query)
  .entities(PokemonEntity, TrainerEntity)
  .options(queryOptions)
  .send()

info

It is advised to provide entities and query first as they constrain the options type.

Available options (see the DynamoDB documentation for more details):

Cat.	Option	Type	Default	Description
General	consistent	boolean	false	By default, read operations are eventually consistent (which improves performances and reduces costs). Set to true to use strongly consistent reads (unavailable on secondary indexes).
	reverse	boolean	false	Specifies the order for index traversal. By default, the traversal is performed in ascending order. If set to true, the traversal is performed in descending order.
	capacity	CapacityOption	"NONE"	Determines the level of detail about provisioned or on-demand throughput consumption that is returned in the response. Possible values are "NONE", "TOTAL" and "INDEXES".
	tableName	string	-	Overrides the Table name. Mostly useful for multitenancy.
Pagination	limit	integer ≥ 1	-	The maximum number of items to evaluate Note that DynamoDB may return a lower number of items if it reaches the limit of 1MB, or if filters are applied. Applies for each page if maxPages is used.
	exclusiveStartKey	Key	-	The primary key of the first item that this operation evaluates. Use the LastEvaluatedKey from the previous operation.
	maxPages	integer ≥ 1	1	A "meta" option provided by DynamoDB-Toolbox to send multiple requests in a single promise. Note that Infinity is a valid (albeit dangerous) option. If two pages or more have been fetched, the responses Count and ScannedCount are summed, but the ConsumedCapacity is omitted for the moment.
Filters	select	SelectOption	-	The strategy for returned attributes. You can retrieve all attributes, specific attributes, the count of matching items, or in the case of an index, some or all of the projected attributes. Possible values are "ALL_ATTRIBUTES", "ALL_PROJECTED_ATTRIBUTES" (if index is specified), "COUNT" and "SPECIFIC_ATTRIBUTES" (if attributes are specified)
	filters	Record<string, Condition>	-	For each entity name, a condition that must be satisfied in order for evaluated items of this entity to be returned (improves performances but does not reduce costs). Requires entities. See the ConditionParser action for more details on how to write conditions.
	filter	Condition	-	An untyped condition that must be satisfied in order for evaluated items to be returned (improves performances but does not reduce costs). No effect if entities are provided (use filters instead). See the ConditionParser action for more details on how to write conditions.
	attributes	string[]	-	To specify a list of attributes to retrieve (improves performances but does not reduce costs). Requires entities. Paths must be common to all entities. See the PathParser action for more details on how to write attribute paths.
	entityAttrFilter	boolean	true	By default, specifying entities introduces a Filter Expression on the entity internal attribute. Set this option to false to disable this behavior. This option is useful for querying items that miss the entity internal attribute (e.g. when migrating to DynamoDB-Toolbox). You can use Middleware Stacks to introduce it manually. Note that this can result in types being wrongly inferred, so be extra careful.

Examples

Strongly consistent

const { Items } = await PokeTable.build(QueryCommand)
  .query({ partition: 'ashKetchum' })
  .entities(PokemonEntity)
  .options({ consistent: true })
  .send()

On index

const { Items } = await PokeTable.build(QueryCommand)
  .query({
    index: 'byTrainerId',
    partition: 'ashKetchum',
    range: { gte: 50 }
  })
  .entities(PokemonEntity)
  .send()

Reversed

const { Items } = await PokeTable.build(QueryCommand)
  .query({ partition: 'ashKetchum' })
  .entities(PokemonEntity)
  .options({ reverse: true })
  .send()

Multitenant

const { Items } = await PokeTable.build(QueryCommand)
  .query({ partition: 'ashKetchum' })
  .entities(PokemonEntity)
  .options({ tableName: `tenant-${tenantId}-pokemons` })
  .send()

Paginated

Paginated

let lastEvaluatedKey: Record<string, unknown> | undefined
const command = PokeTable.build(QueryCommand).query({
  partition: 'ashKetchum'
})

do {
  const page = await command
    .options({ exclusiveStartKey: lastEvaluatedKey })
    .send()

  // ...do something with page.Items here...

  lastEvaluatedKey = page.LastEvaluatedKey
} while (lastEvaluatedKey !== undefined)

All Partition

const { Items } = await PokeTable.build(QueryCommand)
  .query({ partition: 'ashKetchum' })
  // Retrieve all items from the partition (beware of RAM issues!)
  .options({ maxPages: Infinity })
  .send()

Filtered

Filters

const { Items } = await PokeTable.build(QueryCommand)
  .query({ partition: 'ashKetchum' })
  .entities(PokemonEntity, TrainerEntity)
  .options({
    filters: {
      POKEMONS: { attr: 'pokeType', eq: 'fire' },
      TRAINERS: { attr: 'age', gt: 18 }
    }
  })
  .send()

Filter

const { Items } = await PokeTable.build(QueryCommand)
  .query({ partition: 'ashKetchum' })
  .options({
    filters: { attr: 'pokeType', eq: 'fire' }
  })
  .send()

Attributes

const { Items } = await PokeTable.build(QueryCommand)
  .query({ partition: 'ashKetchum' })
  .entities(PokemonEntity)
  .options({ attributes: ['name', 'type'] })
  .send()

Count

const { Count } = await PokeTable.build(QueryCommand)
  .query({ partition: 'ashKetchum' })
  .options({
    select: 'COUNT'
  })
  .send()

Aborted

const abortController = new AbortController()
const abortSignal = abortController.signal

const { Items } = await PokeTable.build(QueryCommand)
  .query({ partition: 'ashKetchum' })
  .send({ abortSignal })

// 👇 Aborts the command
abortController.abort()

Response

The data is returned using the same response syntax as the DynamoDB Query API.

If entities have been provided, the response Items are formatted by their respective entities.

You can use the QueryResponse type to explicitly type an object as a QueryCommand response object:

import type { QueryResponse } from 'dynamodb-toolbox/table/actions/query'

const queryResponse: QueryResponse<
  typeof PokeTable,
  // 👇 Query
  { partition: 'ashKetchum' },
  // 👇 Optional entities
  [typeof PokemonEntity],
  // 👇 Optional options
  { attributes: ['name', 'type'] }
> = { Items: ... }