Skip to main content

ScanCommand

Performs a Scan Operation on a Table:

import { ScanCommand } from 'dynamodb-toolbox/table/actions/scan'

const scanCommand = PokeTable.build(ScanCommand)

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

Request

.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(ScanCommand)
.entities(PokemonEntity, TrainerEntity)
.send()

.options(...)

Provides additional options:

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

You can use the ScanOptions type to explicitly type an object as a ScanCommand options object:

import type { ScanOptions } from 'dynamodb-toolbox/table/actions/scan'

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

const { Items } = await PokeTable.build(ScanCommand)
.options(scanOptions)
.send()
info

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

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

Cat.OptionTypeDefaultDescription
GeneralconsistentbooleanfalseBy default, read operations are eventually consistent (which improves performances and reduces costs).

Set to true to use strongly consistent reads (unavailable on secondary indexes).
indexstring-The name of a secondary index to scan.

This index can be any local secondary index or global secondary index.
capacityCapacityOption"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".
tableNamestring-Overrides the Table name. Mostly useful for multitenancy.
Paginationlimitinteger ≥ 1-The maximum number of items to evaluate for 1 page.

Note that DynamoDB may return a lower number of items if it reaches the limit of 1MB, or if filters are applied.
exclusiveStartKeyKey-The primary key of the first item that this operation evaluates. Use the LastEvaluatedKey from the previous operation.
maxPagesinteger ≥ 11A "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.
FiltersselectSelectOption-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)
filtersRecord<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.
attributesstring[]-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.
entityAttrFilterbooleantrueBy 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), for instance in combination with Middleware Stacks.

Note that this can result in types being wrongly inferred, so be extra careful.
Parallelismsegmentinteger ≥ 0-Identifies an individual segment to be scanned by an application worker (zero-based).

totalSegments must be provided.
totalSegmentinteger ≥ 1-Represents the total number of segments into which the Scan operation is divided.

segment must be provided.
Examples
const { Items } = await PokeTable.build(ScanCommand)
.options({
consistent: true
})
.send()
Paginated
let lastEvaluatedKey: Record<string, unknown> | undefined
const command = PokeTable.build(ScanCommand)

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

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

lastEvaluatedKey = page.LastEvaluatedKey
} while (lastEvaluatedKey !== undefined)
Filtered
const { Items } = await PokeTable.build(ScanCommand)
.entities(PokemonEntity, TrainerEntity)
.options({
filters: {
POKEMONS: { attr: 'pokeType', eq: 'fire' },
TRAINERS: { attr: 'age', gt: 18 }
}
})
.send()
Parallel
const { Items } = await PokeTable.build(ScanCommand)
.options({
segment: 1,
totalSegment: 3
})
.send()

Response

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

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

You can use the ScanResponse type to explicitly type an object as a ScanCommand response object:

import type { ScanResponse } from 'dynamodb-toolbox/table/actions/scan'

const scanResponse: ScanResponse<
typeof PokeTable,
// 👇 Optional entities
[typeof PokemonEntity],
// 👇 Optional options
{ attributes: ['name', 'type'] }
> = { Items: ... }