'A Query operation directly accesses items from a table using
the table primary key, or from an index using the index key.
You must provide a specific hash key value. You can narrow the
scope of the query by using comparison operators on the range
key value, or on the index key. You can use the
ScanIndexForward parameter to get results in forward or
reverse order, by range key or by index key.
Queries that do not return results consume the minimum number
of read capacity units for that type of read operation.
If the total number of items meeting the query criteria
exceeds the result set size limit of 1 MB, the query stops and
results are returned to the user with LastEvaluatedKey to
continue the query in a subsequent operation. Unlike a Scan
operation, a Query operation never returns both an empty
result set and a LastEvaluatedKey . The LastEvaluatedKey is
only provided if the results exceed 1 MB, or if you have used
Limit .
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 ConsistentRead 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.
:type table_name: string
:param table_name: The name of the table containing the requested
items.
:type index_name: string
:param index_name: The name of an index to query. This index can be any
local secondary index or global secondary index on the table.
:type select: string
:param select: 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_ATTRIBUTES` - 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_ATTRIBUTES` - 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_ATTRIBUTES`.
+ `COUNT` - Returns the number of matching items, rather than the
matching items themselves.
+ `SPECIFIC_ATTRIBUTES` - Returns only the attributes listed in
AttributesToGet . This return value is equivalent to specifying
AttributesToGet without specifying any value for Select . If you
query a local secondary index and request only attributes that are
projected into that index, the operation will read only the index
and not the table. If any of the requested attributes are not
projected into the local secondary index, DynamoDB will fetch each
of these attributes from the parent table. This extra fetching
incurs additional throughput cost and latency. If you query a
global secondary index, you can only request attributes that are
projected into the index. Global secondary index queries cannot
fetch attributes from the parent table.
If neither Select nor AttributesToGet are specified, DynamoDB defaults
to `ALL_ATTRIBUTES` when accessing a table, and
`ALL_PROJECTED_ATTRIBUTES` when accessing an index. You cannot use
both Select and AttributesToGet together in a single request,
unless the value for Select is `SPECIFIC_ATTRIBUTES`. (This usage
is equivalent to specifying AttributesToGet without any value for
Select .)
:type attributes_to_get: list
:param attributes_to_get:
There is a newer parameter available. Use ProjectionExpression instead.
Note that if you use AttributesToGet and ProjectionExpression at
the same time, DynamoDB will return a ValidationException
exception.
This parameter allows you to retrieve lists or maps; however, it cannot
retrieve individual list or map elements.
The names of one or more attributes to retrieve. 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.
Note that AttributesToGet has no effect on provisioned throughput
consumption. DynamoDB determines capacity units consumed based on
item size, not on the amount of data that is returned to an
application.
You cannot use both AttributesToGet and Select together in a Query
request, unless the value for Select is `SPECIFIC_ATTRIBUTES`.
(This usage is equivalent to specifying AttributesToGet without any
value for Select .)
If you query a local secondary index and request only attributes that
are projected into that index, the operation will read only the
index and not the table. If any of the requested attributes are not
projected into the local secondary index, DynamoDB will fetch each
of these attributes from the parent table. This extra fetching
incurs additional throughput cost and latency.
If you query a global secondary index, you can only request attributes
that are projected into the index. Global secondary index queries
cannot fetch attributes from the parent table.
:type limit: integer
:param limit: 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 LastEvaluatedKey to apply in a subsequent operation, so that
you can pick up where you left off. Also, if the processed data set
size exceeds 1 MB before DynamoDB reaches this limit, it stops the
operation and returns the matching values up to the limit, and a
key in LastEvaluatedKey to apply in a subsequent operation to
continue the operation. For more information, see `Query and Scan`_
in the Amazon DynamoDB Developer Guide .
:type consistent_read: boolean
:param consistent_read: A value that if set to `True`, then the
operation uses strongly consistent reads; otherwise, eventually
consistent reads are used.
Strongly consistent reads are not supported on global secondary
indexes. If you query a global secondary index with ConsistentRead
set to `True`, you will receive an error message.
:type key_conditions: map
:param key_conditions: The selection criteria for the query. For a
query on a table, you can have conditions only on the table primary
key attributes. You must specify the hash key attribute name and
value as an `EQ` condition. You can optionally specify a second
condition, referring to the range key attribute. If you do not
specify a range key condition, all items under the hash key will be
fetched and processed. Any filters will applied after this.
For a query on an index, you can have conditions only on the index key
attributes. You must specify the index hash attribute name and
value as an EQ condition. You can optionally specify a second
condition, referring to the index key range attribute.
Each KeyConditions element consists of an attribute name to compare,
along with the following:
+ AttributeValueList - One or more values to evaluate against the
supplied attribute. The number of values in the list depends on the
ComparisonOperator being used. For type Number, value comparisons
are numeric. String value comparisons for greater than, equals, or
less than are based on ASCII character code values. For example,
`a` is greater than `A`, and `a` is greater than `B`. For a list of
code values, see
`http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters`_.
For Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values, for example when
evaluating query expressions.
+ ComparisonOperator - A comparator for evaluating attributes, for
example, equals, greater than, less than, and so on. For
KeyConditions , only the following comparison operators are
supported: `EQ | LE | LT | GE | GT | BEGINS_WITH | BETWEEN` The
following are descriptions of these comparison operators.
+ `EQ` : Equal. AttributeValueList can contain only one AttributeValue
of type String, Number, or Binary (not a set type). If an item
contains an AttributeValue element of a different type than the one
specified in the request, the value does not match. For example,
`{"S":"6"}` does not equal `{"N":"6"}`. Also, `{"N":"6"}` does not
equal `{"NS":["6", "2", "1"]}`.
+ `LE` : Less than or equal. AttributeValueList can contain only one
AttributeValue element of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a different
type than the one specified in the request, the value does not
match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also,
`{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li>
+ `LT` : Less than. AttributeValueList can contain only one
AttributeValue of type String, Number, or Binary (not a set type).
If an item contains an AttributeValue element of a different type
than the one specified in the request, the value does not match.
For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also,
`{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li>
+ `GE` : Greater than or equal. AttributeValueList can contain only one
AttributeValue element of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a different
type than the one specified in the request, the value does not
match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also,
`{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li>
+ `GT` : Greater than. AttributeValueList can contain only one
AttributeValue element of type String, Number, or Binary (not a set
type). If an item contains an AttributeValue element of a different
type than the one specified in the request, the value does not
match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also,
`{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li>
+ `BEGINS_WITH` : Checks for a prefix. AttributeValueList can contain
only one AttributeValue of type String or Binary (not a Number or a
set type). The target attribute of the comparison must be of type
String or Binary (not a Number or a set type). > <li>
+ `BETWEEN` : Greater than or equal to the first value, and less than
or equal to the second value. AttributeValueList must contain two
AttributeValue elements of the same type, either String, Number, or
Binary (not a set type). A target attribute matches if the target
value is greater than, or equal to, the first element and less
than, or equal to, the second element. If an item contains an
AttributeValue element of a different type than the one specified
in the request, the value does not match. For example, `{"S":"6"}`
does not compare to `{"N":"6"}`. Also, `{"N":"6"}` does not compare
to `{"NS":["6", "2", "1"]}`
For usage examples of AttributeValueList and ComparisonOperator , see
`Legacy Conditional Parameters`_ in the Amazon DynamoDB Developer
Guide .
:type query_filter: map
:param query_filter:
There is a newer parameter available. Use FilterExpression instead.
Note that if you use QueryFilter and FilterExpression at the same
time, DynamoDB will return a ValidationException exception.
This parameter does not support lists or maps.
A condition that evaluates the query results after the items are read
and returns only the desired values.
Query filters are applied after the items are read, so they do not
limit the capacity used.
If you specify more than one condition in the QueryFilter map, then by
default all of the conditions must evaluate to true. In other
words, the conditions are ANDed together. (You can use the
ConditionalOperator parameter to OR the conditions instead. If you
do this, then at least one of the conditions must evaluate to true,
rather than all of them.)
QueryFilter does not allow key attributes. You cannot define a filter
condition on a hash key or range key.
Each QueryFilter element consists of an attribute name to compare,
along with the following:
+ AttributeValueList - One or more values to evaluate against the
supplied attribute. The number of values in the list depends on the
operator specified in ComparisonOperator . For type Number, value
comparisons are numeric. String value comparisons for greater than,
equals, or less than are based on ASCII character code values. For
example, `a` is greater than `A`, and `a` is greater than `B`. For
a list of code values, see
`http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters`_.
For type Binary, DynamoDB treats each byte of the binary data as
unsigned when it compares binary values, for example when
evaluating query expressions. For information on specifying data
types in JSON, see `JSON Data Format`_ in the Amazon DynamoDB
Developer Guide .
+ ComparisonOperator - A comparator for evaluating attributes. For
example, equals, greater than, less than, etc. The following
comparison operators are available: `EQ | NE | LE | LT | GE | GT |
NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN |
BETWEEN` For complete descriptions of all comparison operators, see
`API_Condition.html`_.
:type conditional_operator: string
:param conditional_operator:
This parameter does not support lists or maps.
A logical operator to apply to the conditions in the QueryFilter map:
+ `AND` - If all of the conditions evaluate to true, then the entire
map evaluates to true.
+ `OR` - If at least one of the conditions evaluate to true, then the
entire map evaluates to true.
If you omit ConditionalOperator , then `AND` is the default.
The operation will succeed only if the entire map evaluates to true.
:type scan_index_forward: boolean
:param scan_index_forward: A value that specifies ascending (true) or
descending (false) traversal of the index. DynamoDB returns results
reflecting the requested order determined by the range key. If the
data type is Number, the results are returned in numeric order. For
type String, the results are returned in order of ASCII character
code values. For type Binary, DynamoDB treats each byte of the
binary data as unsigned when it compares binary values.
If ScanIndexForward is not specified, the results are returned in
ascending order.
:type exclusive_start_key: map
:param exclusive_start_key: The primary key of the first item that this
operation will evaluate. Use the value that was returned for
LastEvaluatedKey in the previous operation.
The data type for ExclusiveStartKey must be String, Number or Binary.
No set data types are allowed.
:type return_consumed_capacity: string
:param return_consumed_capacity: A value that if set to `TOTAL`, the
response includes ConsumedCapacity data for tables and indexes. If
set to `INDEXES`, the response includes ConsumedCapacity for
indexes. If set to `NONE` (the default), ConsumedCapacity is not
included in the response.
:type projection_expression: string
:param projection_expression: 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 on projection expressions, go to `Accessing Item
Attributes`_ in the Amazon DynamoDB Developer Guide .
:type filter_expression: string
:param filter_expression: A condition that evaluates the query results
after the items are read and returns only the desired values.
The condition you specify is applied to the items queried; any items
that do not match the expression are not returned.
Filter expressions are applied after the items are read, so they do not
limit the capacity used.
A FilterExpression has the same syntax as a ConditionExpression . For
more information on expression syntax, go to `Specifying
Conditions`_ in the Amazon DynamoDB Developer Guide .
:type expression_attribute_names: map
:param expression_attribute_names: One or more substitution tokens for
simplifying complex expressions. The following are some use cases
for using ExpressionAttributeNames :
+ To shorten an attribute name that is very long or unwieldy in an
expression.
+ To create a placeholder for repeating occurrences of an attribute
name in an expression.
+ To prevent special characters in an attribute name from being
misinterpreted in an expression.
Use the **#** character in an expression to dereference an attribute
name. For example, consider the following expression:
+ `order.customerInfo.LastName = "Smith" OR order.customerInfo.LastName
= "Jones"`
Now suppose that you specified the following for
ExpressionAttributeNames :
+ `{"#name":"order.customerInfo.LastName"}`
The expression can now be simplified as follows:
+ `#name = "Smith" OR #name = "Jones"`
For more information on expression attribute names, go to `Accessing
Item Attributes`_ in the Amazon DynamoDB Developer Guide .
:type expression_attribute_values: map
:param expression_attribute_values: 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:
`Available | Backordered | Discontinued`
You would first need to specify ExpressionAttributeValues as follows:
`{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"},
":disc":{"S":"Discontinued"} }`
You could then use these values in an expression, such as this:
`ProductStatus IN (:avail, :back, :disc)`
For more information on expression attribute values, go to `Specifying
Conditions`_ in the Amazon DynamoDB Developer Guide .'

def query(self, table_name, key_conditions, index_name=None, select=None, attributes_to_get=None, limit=None, consistent_read=None, query_filter=None, conditional_operator=None, scan_index_forward=None, exclusive_start_key=None, return_consumed_capacity=None, projection_expression=None, filter_expression=None, expression_attribute_names=None, expression_attribute_values=None):

    params = {'TableName': table_name, 'KeyConditions': key_conditions}
    if (index_name is not None):
        params['IndexName'] = index_name
    if (select is not None):
        params['Select'] = select
    if (attributes_to_get is not None):
        params['AttributesToGet'] = attributes_to_get
    if (limit is not None):
        params['Limit'] = limit
    if (consistent_read is not None):
        params['ConsistentRead'] = consistent_read
    if (query_filter is not None):
        params['QueryFilter'] = query_filter
    if (conditional_operator is not None):
        params['ConditionalOperator'] = conditional_operator
    if (scan_index_forward is not None):
        params['ScanIndexForward'] = scan_index_forward
    if (exclusive_start_key is not None):
        params['ExclusiveStartKey'] = exclusive_start_key
    if (return_consumed_capacity is not None):
        params['ReturnConsumedCapacity'] = return_consumed_capacity
    if (projection_expression is not None):
        params['ProjectionExpression'] = projection_expression
    if (filter_expression is not None):
        params['FilterExpression'] = filter_expression
    if (expression_attribute_names is not None):
        params['ExpressionAttributeNames'] = expression_attribute_names
    if (expression_attribute_values is not None):
        params['ExpressionAttributeValues'] = expression_attribute_values
    return self.make_request(action='Query', body=json.dumps(params))
