Query¶

When given a Query, the connection will return a QueryResponse:

>>> connection(Query(table2).key_eq("h", 42))
<LowVoltage.actions.query.QueryResponse ...>

Items are accessed like this:

>>> connection(Query(table2).key_eq("h", 42)).items
[{u'h': 42, u'r1': 0, u'r2': 10}, {u'h': 42, u'r1': 1, u'r2': 9}, {u'h': 42, u'r1': 2, u'r2': 8}, {u'h': 42, u'r1': 3, u'r2': 7}, {u'h': 42, u'r1': 4, u'r2': 6}, {u'h': 42, u'r1': 5, u'r2': 5}, {u'h': 42, u'r1': 6}, {u'h': 42, u'r1': 7}, {u'h': 42, u'r1': 8}, {u'h': 42, u'r1': 9}]

See also the iterate_query() compound. And Actions vs. compounds in the user guide.

class QueryResponse¶

The Query response.

consumed_capacity¶

The capacity consumed by the request. If you used return_consumed_capacity_total() or return_consumed_capacity_indexes().

Type:	`None` or `ConsumedCapacity`

count¶

The number of items matching the query.

Type:	`None` or long

items¶

The items matching the query. Unless you used select_count().

Type:	`None` or list of dict

last_evaluated_key¶

The key of the last item evaluated by the query. If not None, it should be given to exclusive_start_key() is a subsequent Query.

The iterate_query() compound does that for you.

Type:	`None` or dict

scanned_count¶

The number of item scanned during the query. This can be different from count when using filter_expression().

Type:	`None` or long

class Query(table_name=None)¶

The Query request.

Passing table_name to the constructor is like calling table_name() on the new instance.

table_name(table_name)¶

Set TableName. Mandatory, can also be set in the constructor.

>>> connection(
...   Query()
...     .table_name(table2)
...     .key_eq("h", 42)
... )
<LowVoltage.actions.query.QueryResponse ...>

key_eq(name, value)¶

Add a EQ condition to KeyConditions. Usable on both the hash key and the range key. The response will contain items whose key attribute name is equal to value.

>>> connection(
...   Query(table2)
...     .key_eq("h", 42)
... ).items
[{u'h': 42, u'r1': 0, u'r2': 10}, {u'h': 42, u'r1': 1, u'r2': 9}, {u'h': 42, u'r1': 2, u'r2': 8}, ...]

key_le(name, value)¶

Add a LE condition to KeyConditions. Usable only on the range key. The response will contain items whose key attribute name is less than or equal to value.

>>> connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .key_le("r1", 1)
... ).items
[{u'h': 42, u'r1': 0, u'r2': 10}, {u'h': 42, u'r1': 1, u'r2': 9}]

key_lt(name, value)¶

Add a LT condition to KeyConditions. Usable only on the range key. The response will contain items whose key attribute name is strictly less than value.

>>> connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .key_lt("r1", 2)
... ).items
[{u'h': 42, u'r1': 0, u'r2': 10}, {u'h': 42, u'r1': 1, u'r2': 9}]

key_ge(name, value)¶

Add a GE condition to KeyConditions. Usable only on the range key. The response will contain items whose key attribute name is greater than or equal to value.

>>> connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .key_ge("r1", 7)
... ).items
[{u'h': 42, u'r1': 7}, {u'h': 42, u'r1': 8}, {u'h': 42, u'r1': 9}]

key_gt(name, value)¶

Add a GT condition to KeyConditions. Usable only on the range key. The response will contain items whose key attribute name is strictly greater than value.

>>> connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .key_gt("r1", 6)
... ).items
[{u'h': 42, u'r1': 7}, {u'h': 42, u'r1': 8}, {u'h': 42, u'r1': 9}]

key_begins_with(name, value)¶: Add a BEGINS_WITH condition to KeyConditions. Usable only on the range key if it is a string. The response will contain items whose key attribute name begins with value.

key_between(name, lo, hi)¶

Add a BETWEEN condition to KeyConditions. Usable only on the range key. The response will contain items whose key attribute name is greater than or equal to lo and less than or equal to hi.

>>> connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .key_between("r1", 4, 6)
... ).items
[{u'h': 42, u'r1': 4, u'r2': 6}, {u'h': 42, u'r1': 5, u'r2': 5}, {u'h': 42, u'r1': 6}]

exclusive_start_key(key)¶

Set ExclusiveStartKey. The request will only scan items that are after this key. This is typically the last_evaluated_key of a previous response.

The iterate_query() compound does that for you.

>>> r = connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .limit(2)
... )
>>> r.items
[{u'h': 42, u'r1': 0, u'r2': 10}, {u'h': 42, u'r1': 1, u'r2': 9}]
>>> r.last_evaluated_key
{u'h': 42, u'r1': 1}
>>> connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .limit(2)
...     .exclusive_start_key({u'h': 42, u'r1': 1})
... ).items
[{u'h': 42, u'r1': 2, u'r2': 8}, {u'h': 42, u'r1': 3, u'r2': 7}]

limit(limit)¶

Set Limit. The request will scan at most this number of items.

See exclusive_start_key() for an example.

select_count()¶

Set Select to COUNT. The response will contain only the count of matching items.

>>> r = connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .select_count()
... )
>>> r.count
10L
>>> print r.items
None

select_all_attributes()¶

Set Select to ALL_ATTRIBUTES. The response will contain all attributes of the matching items.

>>> connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .index_name("lsi")
...     .select_all_attributes()
...     .limit(2)
... ).items
[{u'h': 42, u'r1': 5, u'r2': 5}, {u'h': 42, u'r1': 4, u'r2': 6}]

select_all_projected_attributes()¶

Set Select to ALL_PROJECTED_ATTRIBUTES. Usable only when querying an index. The response will contain the attributes of the matching items that are projected on the index.

>>> connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .index_name("lsi")
...     .select_all_projected_attributes()
...     .limit(2)
... ).items
[{u'h': 42, u'r1': 5, u'r2': 5}, {u'h': 42, u'r1': 4, u'r2': 6}]

index_name(index_name)¶

Set IndexName. The request will use this index instead of the table key.

>>> connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .index_name("lsi")
... ).items
[{u'h': 42, u'r1': 5, u'r2': 5}, {u'h': 42, u'r1': 4, u'r2': 6}, {u'h': 42, u'r1': 3, u'r2': 7}, {u'h': 42, u'r1': 2, u'r2': 8}, {u'h': 42, u'r1': 1, u'r2': 9}, {u'h': 42, u'r1': 0, u'r2': 10}]

scan_index_forward_true()¶

Set ScanIndexForward to true. Items in the response will be sorted with ascending range keys.

>>> connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .project("r1")
...     .scan_index_forward_true()
... ).items
[{u'r1': 0}, {u'r1': 1}, {u'r1': 2}, {u'r1': 3}, {u'r1': 4}, {u'r1': 5}, {u'r1': 6}, {u'r1': 7}, {u'r1': 8}, {u'r1': 9}]

scan_index_forward_false()¶

Set ScanIndexForward to false. Items in the response will be sorted with descending range keys.

>>> connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .project("r1")
...     .scan_index_forward_false()
... ).items
[{u'r1': 9}, {u'r1': 8}, {u'r1': 7}, {u'r1': 6}, {u'r1': 5}, {u'r1': 4}, {u'r1': 3}, {u'r1': 2}, {u'r1': 1}, {u'r1': 0}]

project(*names)¶

Note that this function is variadic. See Variadic functions.

Add name(s) to ProjectionExpression. The request will return only projected attributes.

>>> connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .project("r2")
... ).items
[{u'r2': 10}, {u'r2': 9}, {u'r2': 8}, {u'r2': 7}, {u'r2': 6}, {u'r2': 5}, {}, {}, {}, {}]

filter_expression(expression)¶

Set the FilterExpression. The response will contain only items that match.

>>> connection(
...   Query(table2)
...     .key_eq("h", 42)
...     .key_ge("r1", 2)
...     .filter_expression("#syn IN (:val1, :val2)")
...     .expression_attribute_name("syn", "r2")
...     .expression_attribute_value("val1", 5)
...     .expression_attribute_value("val2", 7)
... ).items
[{u'h': 42, u'r1': 3, u'r2': 7}, {u'h': 42, u'r1': 5, u'r2': 5}]

expression_attribute_name(synonym, name)¶

Add a synonym for an attribute name to ExpressionAttributeNames. Useful for attributes whose names don’t play well with ProjectionExpression, ConditionExpression or UpdateExpression because they contain a dot or brackets.

See filter_expression() for an example.

expression_attribute_value(name, value)¶

Add a named value to ExpressionAttributeValues.

See filter_expression() for an example.

consistent_read_true()¶

Set ConsistentRead to True. The request will use strong consistent reads.

>>> connection(
...   Query(table)
...     .key_eq("h", 0)
...     .consistent_read_true()
...     .return_consumed_capacity_total()
... ).consumed_capacity.capacity_units
1.0

consistent_read_false()¶

Set ConsistentRead to False. The request will use eventually consistent reads.

>>> connection(
...   Query(table)
...     .key_eq("h", 0)
...     .consistent_read_false()
...     .return_consumed_capacity_total()
... ).consumed_capacity.capacity_units
0.5

return_consumed_capacity_total()¶

Set ReturnConsumedCapacity to TOTAL. The response will contain the total capacity consumed by this request.

>>> connection(
...   Query(table)
...     .key_eq("h", 0)
...     .return_consumed_capacity_total()
... ).consumed_capacity.capacity_units
0.5

return_consumed_capacity_indexes()¶

Set ReturnConsumedCapacity to INDEXES. The response will contain the capacity consumed by this request detailled on the table and the indexes.

>>> c1 = connection(
...   Query(table)
...     .key_eq("h", 0)
...     .return_consumed_capacity_indexes()
... ).consumed_capacity
>>> c1.capacity_units
0.5
>>> c1.table.capacity_units
0.5
>>> print c1.global_secondary_indexes
None

>>> c2 = connection(
...   Query(table)
...     .index_name("gsi")
...     .key_eq("gh", 0)
...     .return_consumed_capacity_indexes()
... ).consumed_capacity
>>> c2.capacity_units
0.5
>>> c2.table.capacity_units
0.0
>>> c2.global_secondary_indexes["gsi"].capacity_units
0.5

return_consumed_capacity_none()¶

Set ReturnConsumedCapacity to NONE. The response will not contain the capacity consumed by this request.

>>> print connection(
...   Query(table)
...     .key_eq("h", 0)
...     .return_consumed_capacity_none()
... ).consumed_capacity
None