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.	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).
	index	string	-	The name of a secondary index to scan. This index can be any local secondary index or global secondary index.
	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 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.
	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), for instance in combination with Middleware Stacks. Note that this can result in types being wrongly inferred, so be extra careful.
Parallelism	segment	integer ≥ 0	-	Identifies an individual segment to be scanned by an application worker (zero-based). totalSegments must be provided.
	totalSegment	integer ≥ 1	-	Represents the total number of segments into which the Scan operation is divided. segment must be provided.

Examples

Strongly consistent

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

On index

const { Items } = await PokeTable.build(ScanCommand)
  .options({
    index: 'my-index'
  })
  .send()

Multitenant

const { Items } = await PokeTable.build(ScanCommand)
  .options({
    tableName: `tenant-${tenantId}-pokemons`
  })
  .send()

Aborted

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

const { Items } = await PokeTable.build(ScanCommand).send({
  abortSignal
})

// 👇 Aborts the command
abortController.abort()

Paginated

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)

All DB

const { Items } = await PokeTable.build(ScanCommand)
  // Retrieve all items from the table (beware of RAM issues!)
  .options({
    maxPages: Infinity
  })
  .send()

All Pokemons

const { Items } = await PokeTable.build(ScanCommand)
  .entities(PokemonEntity)
  // Retrieve all pokemons from the table (beware of RAM issues!)
  .options({
    maxPages: Infinity
  })
  .send()

Filtered

Filters

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

Filter

const { Items } = await PokeTable.build(ScanCommand)
  .options({
    filter: { attr: 'pokeType', eq: 'fire' }
  })
  .send()

Attributes

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

Count

const { Count } = await PokeTable.build(ScanCommand)
  .options({
    select: 'COUNT'
  })
  .send()

Parallel

Segment

const { Items } = await PokeTable.build(ScanCommand)
  .options({
    segment: 1,
    totalSegment: 3
  })
  .send()

All DB (3 threads)

const opts = { totalSegment: 3, maxPages: Infinity }

const [
  { Items: segment1 = [] },
  { Items: segment2 = [] },
  { Items: segment3 = [] }
] = await Promise.all([
  PokeTable.build(ScanCommand)
    .options({ segment: 0, ...opts })
    .send(),
  PokeTable.build(ScanCommand)
    .options({ segment: 1, ...opts })
    .send(),
  PokeTable.build(ScanCommand)
    .options({ segment: 2, ...opts })
    .send()
])

const allItems = [...segment1, ...segment2, ...segment3]

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: ... }