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.
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>]
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 namebegins_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 specifyingALL
.
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 aValidationException
.
--return-consumed-capacity
| --no-return-consumed-capacity
(boolean)
Will include the aggregate
ConsumedCapacity
for the operation. If--index-name
is also specified, then theConsumedCapacity
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 theNextToken
value in thestarting-token
argument of a subsequent command. Do not use theNextToken
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.
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 'Artist = "No One You Know"'
Output:
Count: 2
Items:
- SongTitle: "Call Me Today"
- SongTitle: "Scared of My Shadow"
ScannedCount: 2