- Navigation GuideYou are on a Command (operation) page with structural examples. Use the navigation breadcrumb if you would like to return to the Client landing page.
QueryCommand
You must provide the name of the partition key attribute and a single value for that attribute. Query
returns all items with that partition key value. Optionally, you can provide a sort key attribute and use a comparison operator to refine the search results.
Use the KeyConditionExpression
parameter to provide a specific value for the partition key. The Query
operation will return all of the items from the table or index with that partition key value. You can optionally narrow the scope of the Query
operation by specifying a sort key value and a comparison operator in KeyConditionExpression
. To further refine the Query
results, you can optionally provide a FilterExpression
. A FilterExpression
determines which items within the results should be returned to you. All of the other results are discarded.
A Query
operation always returns a result set. If no matching items are found, the result set will be empty. Queries that do not return results consume the minimum number of read capacity units for that type of read operation.
DynamoDB calculates the number of read capacity units consumed based on item size, not on the amount of data that is returned to an application. The number of capacity units consumed will be the same whether you request all of the attributes (the default behavior) or just some of them (using a projection expression). The number will also be the same whether or not you use a FilterExpression
.
Query
results are always sorted by the sort key value. If the data type of the sort key is Number, the results are returned in numeric order; otherwise, the results are returned in order of UTF-8 bytes. By default, the sort order is ascending. To reverse the order, set the ScanIndexForward
parameter to false.
A single Query
operation will read up to the maximum number of items set (if using the Limit
parameter) or a maximum of 1 MB of data and then apply any filtering to the results using FilterExpression
. If LastEvaluatedKey
is present in the response, you will need to paginate the result set. For more information, see Paginating the Results in the Amazon DynamoDB Developer Guide.
FilterExpression
is applied after a Query
finishes, but before the results are returned. A FilterExpression
cannot contain partition key or sort key attributes. You need to specify those attributes in the KeyConditionExpression
.
A Query
operation can return an empty result set and a LastEvaluatedKey
if all the items read for the page of results are filtered out.
You can query a table, a local secondary index, or a global secondary index. For a query on a table or on a local secondary index, you can set the ConsistentRead
parameter to true
and obtain a strongly consistent result. Global secondary indexes support eventually consistent reads only, so do not specify ConsistentRead
when querying a global secondary index.
Example Syntax
Use a bare-bones client and the command you need to make an API call.
import { DynamoDBClient, QueryCommand } from "@aws-sdk/client-dynamodb"; // ES Modules import
// const { DynamoDBClient, QueryCommand } = require("@aws-sdk/client-dynamodb"); // CommonJS import
const client = new DynamoDBClient(config);
const input = { // QueryInput
TableName: "STRING_VALUE", // required
IndexName: "STRING_VALUE",
Select: "ALL_ATTRIBUTES" || "ALL_PROJECTED_ATTRIBUTES" || "SPECIFIC_ATTRIBUTES" || "COUNT",
AttributesToGet: [ // AttributeNameList
"STRING_VALUE",
],
Limit: Number("int"),
ConsistentRead: true || false,
KeyConditions: { // KeyConditions
"<keys>": { // Condition
AttributeValueList: [ // AttributeValueList
{ // AttributeValue Union: only one key present
S: "STRING_VALUE",
N: "STRING_VALUE",
B: new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")
SS: [ // StringSetAttributeValue
"STRING_VALUE",
],
NS: [ // NumberSetAttributeValue
"STRING_VALUE",
],
BS: [ // BinarySetAttributeValue
new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")
],
M: { // MapAttributeValue
"<keys>": {// Union: only one key present
S: "STRING_VALUE",
N: "STRING_VALUE",
B: new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")
SS: [
"STRING_VALUE",
],
NS: [
"STRING_VALUE",
],
BS: [
new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")
],
M: {
"<keys>": "<AttributeValue>",
},
L: [ // ListAttributeValue
"<AttributeValue>",
],
NULL: true || false,
BOOL: true || false,
},
},
L: [
"<AttributeValue>",
],
NULL: true || false,
BOOL: true || false,
},
],
ComparisonOperator: "EQ" || "NE" || "IN" || "LE" || "LT" || "GE" || "GT" || "BETWEEN" || "NOT_NULL" || "NULL" || "CONTAINS" || "NOT_CONTAINS" || "BEGINS_WITH", // required
},
},
QueryFilter: { // FilterConditionMap
"<keys>": {
AttributeValueList: [
"<AttributeValue>",
],
ComparisonOperator: "EQ" || "NE" || "IN" || "LE" || "LT" || "GE" || "GT" || "BETWEEN" || "NOT_NULL" || "NULL" || "CONTAINS" || "NOT_CONTAINS" || "BEGINS_WITH", // required
},
},
ConditionalOperator: "AND" || "OR",
ScanIndexForward: true || false,
ExclusiveStartKey: { // Key
"<keys>": "<AttributeValue>",
},
ReturnConsumedCapacity: "INDEXES" || "TOTAL" || "NONE",
ProjectionExpression: "STRING_VALUE",
FilterExpression: "STRING_VALUE",
KeyConditionExpression: "STRING_VALUE",
ExpressionAttributeNames: { // ExpressionAttributeNameMap
"<keys>": "STRING_VALUE",
},
ExpressionAttributeValues: { // ExpressionAttributeValueMap
"<keys>": "<AttributeValue>",
},
};
const command = new QueryCommand(input);
const response = await client.send(command);
// { // QueryOutput
// Items: [ // ItemList
// { // AttributeMap
// "<keys>": { // AttributeValue Union: only one key present
// S: "STRING_VALUE",
// N: "STRING_VALUE",
// B: new Uint8Array(),
// SS: [ // StringSetAttributeValue
// "STRING_VALUE",
// ],
// NS: [ // NumberSetAttributeValue
// "STRING_VALUE",
// ],
// BS: [ // BinarySetAttributeValue
// new Uint8Array(),
// ],
// M: { // MapAttributeValue
// "<keys>": {// Union: only one key present
// S: "STRING_VALUE",
// N: "STRING_VALUE",
// B: new Uint8Array(),
// SS: [
// "STRING_VALUE",
// ],
// NS: [
// "STRING_VALUE",
// ],
// BS: [
// new Uint8Array(),
// ],
// M: {
// "<keys>": "<AttributeValue>",
// },
// L: [ // ListAttributeValue
// "<AttributeValue>",
// ],
// NULL: true || false,
// BOOL: true || false,
// },
// },
// L: [
// "<AttributeValue>",
// ],
// NULL: true || false,
// BOOL: true || false,
// },
// },
// ],
// Count: Number("int"),
// ScannedCount: Number("int"),
// LastEvaluatedKey: { // Key
// "<keys>": "<AttributeValue>",
// },
// ConsumedCapacity: { // ConsumedCapacity
// TableName: "STRING_VALUE",
// CapacityUnits: Number("double"),
// ReadCapacityUnits: Number("double"),
// WriteCapacityUnits: Number("double"),
// Table: { // Capacity
// ReadCapacityUnits: Number("double"),
// WriteCapacityUnits: Number("double"),
// CapacityUnits: Number("double"),
// },
// LocalSecondaryIndexes: { // SecondaryIndexesCapacityMap
// "<keys>": {
// ReadCapacityUnits: Number("double"),
// WriteCapacityUnits: Number("double"),
// CapacityUnits: Number("double"),
// },
// },
// GlobalSecondaryIndexes: {
// "<keys>": {
// ReadCapacityUnits: Number("double"),
// WriteCapacityUnits: Number("double"),
// CapacityUnits: Number("double"),
// },
// },
// },
// };
Example Usage
QueryCommand Input
Parameter | Type | Description |
---|
Parameter | Type | Description |
---|---|---|
TableName Required | string | undefined | The name of the table containing the requested items. You can also provide the Amazon Resource Name (ARN) of the table in this parameter. |
AttributesToGet | string[] | undefined | This is a legacy parameter. Use |
ConditionalOperator | ConditionalOperator | undefined | This is a legacy parameter. Use |
ConsistentRead | boolean | undefined | Determines the read consistency model: If set to Strongly consistent reads are not supported on global secondary indexes. If you query a global secondary index with |
ExclusiveStartKey | Record<string, AttributeValue> | undefined | The primary key of the first item that this operation will evaluate. Use the value that was returned for The data type for |
ExpressionAttributeNames | Record<string, string> | undefined | One or more substitution tokens for attribute names in an expression. The following are some use cases for using
Use the # character in an expression to dereference an attribute name. For example, consider the following attribute name:
The name of this attribute conflicts with a reserved word, so it cannot be used directly in an expression. (For the complete list of reserved words, see Reserved Words in the Amazon DynamoDB Developer Guide). To work around this, you could specify the following for
You could then use this substitution in an expression, as in this example:
Tokens that begin with the : character are expression attribute values, which are placeholders for the actual value at runtime. For more information on expression attribute names, see Specifying Item Attributes in the Amazon DynamoDB Developer Guide. |
ExpressionAttributeValues | Record<string, AttributeValue> | undefined | One or more values that can be substituted in an expression. Use the : (colon) character in an expression to dereference an attribute value. For example, suppose that you wanted to check whether the value of the ProductStatus attribute was one of the following: You would first need to specify You could then use these values in an expression, such as this: For more information on expression attribute values, see Specifying Conditions in the Amazon DynamoDB Developer Guide. |
FilterExpression | string | undefined | A string that contains conditions that DynamoDB applies after the A A For more information, see Filter Expressions in the Amazon DynamoDB Developer Guide. |
IndexName | string | undefined | The name of an index to query. This index can be any local secondary index or global secondary index on the table. Note that if you use the |
KeyConditionExpression | string | undefined | The condition that specifies the key values for items to be retrieved by the The condition 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 The partition key equality test is required, and must be specified in the following format: If you also want to provide a condition for the sort key, it must be combined using Valid comparisons for the sort key condition are as follows:
Use the You can optionally use the
To work around this, define a placeholder (such a
For a list of reserved words, see Reserved Words in the Amazon DynamoDB Developer Guide. For more information on |
KeyConditions | Record<string, Condition> | undefined | This is a legacy parameter. Use |
Limit | number | undefined | The maximum number of items to evaluate (not necessarily the number of matching items). If DynamoDB processes the number of items up to the limit while processing the results, it stops the operation and returns the matching values up to that point, and a key in |
ProjectionExpression | string | undefined | A string that identifies one or more attributes to retrieve from the table. These attributes can include scalars, sets, or elements of a JSON document. The attributes in the expression must be separated by commas. If no attribute names are specified, then all attributes will be returned. 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. |
QueryFilter | Record<string, Condition> | undefined | This is a legacy parameter. Use |
ReturnConsumedCapacity | ReturnConsumedCapacity | undefined | Determines the level of detail about either provisioned or on-demand throughput consumption that is returned in the response:
|
ScanIndexForward | boolean | undefined | Specifies the order for index traversal: If Items with the same partition key value are stored in sorted order by sort key. If the sort key data type is Number, the results are stored in numeric order. For type String, the results are stored in order of UTF-8 bytes. For type Binary, DynamoDB treats each byte of the binary data as unsigned. If |
Select | Select | undefined | 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.
If neither If you use the |
QueryCommand Output
Parameter | Type | Description |
---|
Parameter | Type | Description |
---|---|---|
$metadata Required | ResponseMetadata | Metadata pertaining to this request. |
ConsumedCapacity | ConsumedCapacity | undefined | The capacity units consumed by the |
Count | number | undefined | The number of items in the response. If you used a If you did not use a filter in the request, then |
Items | Record<string, AttributeValue>[] | undefined | An array of item attributes that match the query criteria. Each element in this array consists of an attribute name and the value for that attribute. |
LastEvaluatedKey | Record<string, AttributeValue> | undefined | The primary key of the item where the operation stopped, inclusive of the previous result set. Use this value to start a new operation, excluding this value in the new request. If If |
ScannedCount | number | undefined | The number of items evaluated, before any If you did not use a filter in the request, then |
Throws
Name | Fault | Details |
---|
Name | Fault | Details |
---|---|---|
InternalServerError | server | An error occurred on the server side. |
InvalidEndpointException | client | |
ProvisionedThroughputExceededException | client | Your request rate is too high. The Amazon Web Services SDKs for DynamoDB automatically retry requests that receive this exception. Your request is eventually successful, unless your retry queue is too large to finish. Reduce the frequency of requests and use exponential backoff. For more information, go to Error Retries and Exponential Backoff in the Amazon DynamoDB Developer Guide. |
RequestLimitExceeded | client | Throughput exceeds the current throughput quota for your account. Please contact Amazon Web Services Support to request a quota increase. |
ResourceNotFoundException | client | The operation tried to access a nonexistent table or index. The resource might not be specified correctly, or its status might not be |
DynamoDBServiceException | Base exception class for all service exceptions from DynamoDB service. |