Other aspects of working with the Query operation
Limiting the number of items in the result set
With the Query operation, you can limit the number of items that it
reads. To do this, set the Limit parameter to the maximum number of
items that you want.
For example, suppose that you Query a table, with a Limit
value of 6, and without a filter expression. The Query result
contains the first six items from the table that match the key condition expression from
the request.
Now suppose that you add a filter expression to the Query. In this case,
DynamoDB reads up to six items, and then returns only those that match the filter
expression. The final Query result contains six items or fewer, even if
more items would have matched the filter expression if DynamoDB had kept reading more
items.
Counting the items in the results
In addition to the items that match your criteria, the Query response
contains the following elements:
-
ScannedCount— The number of items that matched the key condition expression before a filter expression (if present) was applied. -
Count— The number of items that remain after a filter expression (if present) was applied.
Note
If you don't use a filter expression, ScannedCount and
Count have the same value.
If the size of the Query result set is larger than 1 MB,
ScannedCount and Count represent only a partial count of
the total items. You need to perform multiple Query operations to retrieve
all the results (see Paginating table query results).
Each Query response contains the ScannedCount and
Count for the items that were processed by that particular
Query request. To obtain grand totals for all of the Query
requests, you could keep a running tally of both ScannedCount and
Count.
Capacity units consumed by query
You can Query any table or secondary index, as long as you 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.
Query API operations consume read capacity units, as
follows.
If you Query a... |
DynamoDB consumes read capacity units from... |
|---|---|
| Table | The table's provisioned read capacity. |
| Global secondary index | The index's provisioned read capacity. |
| Local secondary index | The base table's provisioned read capacity. |
By default, a Query operation does not return any data on how much read
capacity it consumes. However, you can specify the ReturnConsumedCapacity
parameter in a Query request to obtain this information. The following are
the valid settings for ReturnConsumedCapacity:
-
NONE— No consumed capacity data is returned. (This is the default.) -
TOTAL— The response includes the aggregate number of read capacity units consumed. -
INDEXES— The response shows the aggregate number of read capacity units consumed, together with the consumed capacity for each table and index that was accessed.
DynamoDB calculates the number of read capacity units consumed based on the number of items and the size of those items, not on the amount of data that is returned to an application. For this reason, the number of capacity units consumed is the same whether you request all of the attributes (the default behavior) or just some of them (using a projection expression). The number is also the same whether or not you use a filter expression. Query consumes a minimum read capacity unit to perform one strongly consistent read per second, or two eventually consistent reads per second for an item up to 4 KB. If you need to read an item that is larger than 4 KB, DynamoDB needs additional read request units. Empty tables and very large tables which have a sparse amount of partition keys might see some additional RCUs charged beyond the amount of data queried. This covers the cost of serving the Query request, even if no data exists.
Read consistency for query
A Query operation performs eventually consistent reads, by default. This
means that the Query results might not reflect changes due to recently
completed PutItem or UpdateItem operations. For more
information, see Read consistency.
If you require strongly consistent reads, set the ConsistentRead
parameter to true in the Query request.
