[ aws . ddb ]

select

Description

select searches a table or index.

Under the hood, this operation will use query if --key-condition is specified, or scan otherwise.

See ‘aws help’ for descriptions of global parameters.

Synopsis

  select
<table-name>
[--index-name <value>]
[--projection <value> [<value>...]]
[--filter <value> [<value>...]]
[--key-condition <value> [<value>...]]
[--attributes <value>]
[--consistent-read | --no-consistent-read]
[--return-consumed-capacity | --no-return-consumed-capacity]
[--starting-token <value>]
[--max-items <value>]
[--page-size <value>]

Options

table_name (string)

The name of your DynamoDB table.

--index-name (string)

The name of a secondary index to scan. This index can be any local secondary index or global secondary index.

--projection (string)

A string that identifies one or more attributes to retrieve from the specified table or index. These attributes can include scalars, sets, or elements of a JSON document. The attributes in the expression must be separated by commas. If any of the requested attributes are not found, they will not appear in the result.

For more information, see Accessing Item Attributes in the Amazon DynamoDB Developer Guide .

For CLI specific syntax see aws help ddb-expressions

--filter (string)

A string that contains conditions that DynamoDB applies after the operation, but before the data is returned to you. Items that do not satisfy the --filter criteria are not returned.

Note

A --filter is applied after the items have already been read; the process of filtering does not consume any additional read capacity units.

For more information, see Filter Expressions in the Amazon DynamoDB Developer Guide .

For CLI specific syntax see aws help ddb-expressions

--key-condition (string)

The condition that specifies the key value(s) for items to be retrieved. Must perform an equality test on a single partition key value.

The condition can optionally perform one of several comparison tests on a single sort key value. This allows select to retrieve one item with a given partition key value and sort key value, or several items that have the same partition key value but different sort key values.

The partition key equality test must be specified in the following format:

partitionKeyName = :partitionkeyval

If you also want to provide a condition for the sort key, it must be combined using AND with the condition for the sort key.

Valid comparisons for the sort key condition are as follows:

• sortKeyName = :sortkeyval - true if the sort key value is equal to :sortkeyval .

• sortKeyName < :sortkeyval - true if the sort key value is less than :sortkeyval .

• sortKeyName <= :sortkeyval - true if the sort key value is less than or equal to :sortkeyval .

• sortKeyName > :sortkeyval - true if the sort key value is greater than :sortkeyval .

• sortKeyName >= :sortkeyval - true if the sort key value is greater than or equal to :sortkeyval .

• sortKeyName BETWEEN :sortkeyval1 AND :sortkeyval2 - true if the sort key value is greater than or equal to :sortkeyval1 , and less than or equal to :sortkeyval2 .

• begins_with(sortKeyName, :sortkeyval) - true if the sort key value begins with a particular operand. (You cannot use this function with a sort key that is of type Number.) Note that the function name begins_with is case-sensitive.

For CLI specific syntax see aws help ddb-expressions

--attributes (string)

The attributes to be returned in the result. You can retrieve all item attributes, specific item attributes, the count of matching items, or in the case of an index, some or all of the attributes projected into the index.

• ALL - Returns all of the item attributes from the specified table or index. If you query a local secondary index, then for each matching item in the index DynamoDB will fetch the entire item from the parent table. If the index is configured to project all item attributes, then all of the data can be obtained from the local secondary index, and no fetching is required.

• ALL_PROJECTED - Allowed only when querying an index. Retrieves all attributes that have been projected into the index. If the index is configured to project all attributes, this return value is equivalent to specifying ALL.

• COUNT - Returns the number of matching items, rather than the matching items themselves.

--consistent-read | --no-consistent-read (boolean)

Determines the read consistency model: If set to --consistent-read , then the operation uses strongly consistent reads; otherwise, the operation uses eventually consistent reads. Strongly consistent reads are not supported on global secondary indexes. If you query a global secondary index with --consistent-read , you will receive a ValidationException .

--return-consumed-capacity | --no-return-consumed-capacity (boolean)

Will include the aggregate ConsumedCapacity for the operation. If --index-name is also specified, then the ConsumedCapacity for each table and secondary index that was accessed will be returned.

--starting-token (string)

A token to specify where to start paginating. This is the NextToken from a previously truncated response.

For usage examples, see Pagination in the AWS Command Line Interface User Guide .

--max-items (integer)

The total number of items to return in the command’s output. If the total number of items available is more than the value specified, a NextToken is provided in the command’s output. To resume pagination, provide the NextToken value in the starting-token argument of a subsequent command. Do not use the NextToken response element directly outside of the AWS CLI.

For usage examples, see Pagination in the AWS Command Line Interface User Guide .

--page-size (integer)

The size of each page to get in the AWS service call. This does not affect the number of items returned in the command’s output. Setting a smaller page size results in more calls to the AWS service, retrieving fewer items in each call. This can help prevent the AWS service calls from timing out.

For usage examples, see Pagination in the AWS Command Line Interface User Guide .

See ‘aws help’ for descriptions of global parameters.

Examples

To scan an entire table

This example scans the entire MusicCollection table, and then narrows the results to songs by the artist “No One You Know”. For each item, only the album title and song title are returned.

Command:

aws ddb select MusicCollection --projection 'SongTitle, AlbumTitle' \
    --filter 'Artist = "No One You Know"'

Output:

Count: 2
Items:
- SongTitle: "Call Me Today"
  AlbumTitle: "Somewhat Famous"
- SongTitle: "Scared of My Shadow"
  AlbumTitle: "Blue Sky Blues"
ScannedCount: 3

To query for specific primary keys

This example queries items in the MusicCollection table. The table has a hash-and-range primary key (Artist and SongTitle), but this query only specifies the hash key value. It returns song titles by the artist named “No One You Know”.

Command:

aws ddb select MusicCollection --projection SongTitle \
    --key-condition-expression 'Artist = "No One You Know"'

Output:

Count: 2
Items:
- SongTitle: "Call Me Today"
- SongTitle: "Scared of My Shadow"
ScannedCount: 2