# Legacy DynamoDB conditional parameters
This document provides an overview of legacy conditional parameters in DynamoDB and recommends using the new expression parameters instead. It covers details on parameters like AttributesToGet, AttributeUpdates, ConditionalOperator, Expected, KeyConditions, QueryFilter, and ScanFilter, and provides examples of how to use the new expression parameters as replacements.
**Important**
We recommend that you use the new expression parameters instead of these legacy parameters whenever possible. For more information, see [Using expressions in DynamoDB](Expressions.md).
Additionally, DynamoDB does not allow mixing legacy conditional parameters and expression parameters in a single call. For example, calling the `Query` operation with `AttributesToGet` and `ConditionExpression` will result in an error.
The following table shows the DynamoDB API operations that still support these legacy parameters, and which expression parameter to use instead. This table can be helpful if you are considering updating your applications so that they use expression parameters instead.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.html)
The following sections provide more information about legacy conditional parameters.
**Topics**
+ [
# AttributesToGet (legacy)
](LegacyConditionalParameters.AttributesToGet.md)
+ [
# AttributeUpdates (legacy)
](LegacyConditionalParameters.AttributeUpdates.md)
+ [
# ConditionalOperator (legacy)
](LegacyConditionalParameters.ConditionalOperator.md)
+ [
# Expected (legacy)
](LegacyConditionalParameters.Expected.md)
+ [
# KeyConditions (legacy)
](LegacyConditionalParameters.KeyConditions.md)
+ [
# QueryFilter (legacy)
](LegacyConditionalParameters.QueryFilter.md)
+ [
# ScanFilter (legacy)
](LegacyConditionalParameters.ScanFilter.md)
+ [
# Writing conditions with legacy parameters
](LegacyConditionalParameters.Conditions.md)
# AttributesToGet (legacy)
**Note**
We recommend that you use the new expression parameters instead of these legacy parameters whenever possible. For more information, see [Using expressions in DynamoDB](Expressions.md). For specific information on the new parameter replacing this one, [Use *ProjectionExpression* instead](#ProjectionExpression.instead).
The legacy conditional parameter `AttributesToGet` is an array of one or more attributes to retrieve from DynamoDB. If no attribute names are provided, then all attributes will be returned. If any of the requested attributes are not found, they will not appear in the result.
`AttributesToGet` allows you to retrieve attributes of type List or Map; however, it cannot retrieve individual elements within a List or a Map.
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.
## Use *ProjectionExpression* instead – Example
Suppose you wanted to retrieve an item from the *Music* table, but that you only wanted to return some of the attributes. You could use a `GetItem` request with an `AttributesToGet` parameter, as in this AWS CLI example:
```
aws dynamodb get-item \
--table-name Music \
--attributes-to-get '["Artist", "Genre"]' \
--key '{
"Artist": {"S":"No One You Know"},
"SongTitle": {"S":"Call Me Today"}
}'
```
You can use a `ProjectionExpression` instead:
```
aws dynamodb get-item \
--table-name Music \
--projection-expression "Artist, Genre" \
--key '{
"Artist": {"S":"No One You Know"},
"SongTitle": {"S":"Call Me Today"}
}'
```
# AttributeUpdates (legacy)
**Note**
We recommend that you use the new expression parameters instead of these legacy parameters whenever possible. For more information, see [Using expressions in DynamoDB](Expressions.md). For specific information on the new parameter replacing this one, [use *UpdateExpression* instead.](#UpdateExpression.instead).
In an `UpdateItem` operation, the legacy conditional parameter `AttributeUpdates` contains the names of attributes to be modified, the action to perform on each, and the new value for each. If you are updating an attribute that is an index key attribute for any indexes on that table, the attribute type must match the index key type defined in the `AttributesDefinition` of the table description. You can use `UpdateItem` to update any non-key attributes.
Attribute values cannot be null. String and Binary type attributes must have lengths greater than zero. Set type attributes must not be empty. Requests with empty values will be rejected with a `ValidationException` exception.
Each `AttributeUpdates` element consists of an attribute name to modify, along with the following:
+ `Value` - The new value, if applicable, for this attribute.
+ `Action` - A value that specifies how to perform the update. This action is only valid for an existing attribute whose data type is Number or is a set; do not use `ADD` for other data types.
If an item with the specified primary key is found in the table, the following values perform the following actions:
+ `PUT` - Adds the specified attribute to the item. If the attribute already exists, it is replaced by the new value.
+ `DELETE` - Removes the attribute and its value, if no value is specified for `DELETE`. The data type of the specified value must match the existing value's data type.
If a set of values is specified, then those values are subtracted from the old set. For example, if the attribute value was the set `[a,b,c]` and the `DELETE` action specifies `[a,c]`, then the final attribute value is `[b]`. Specifying an empty set is an error.
+ `ADD` - Adds the specified value to the item, if the attribute does not already exist. If the attribute does exist, then the behavior of `ADD` depends on the data type of the attribute:
+ If the existing attribute is a number, and if `Value` is also a number, then `Value` is mathematically added to the existing attribute. If `Value` is a negative number, then it is subtracted from the existing attribute.
**Note**
If you use `ADD` to increment or decrement a number value for an item that doesn't exist before the update, DynamoDB uses 0 as the initial value.
Similarly, if you use `ADD` for an existing item to increment or decrement an attribute value that doesn't exist before the update, DynamoDB uses `0` as the initial value. For example, suppose that the item you want to update doesn't have an attribute named *itemcount*, but you decide to `ADD` the number `3` to this attribute anyway. DynamoDB will create the *itemcount* attribute, set its initial value to `0`, and finally add `3` to it. The result will be a new *itemcount* attribute, with a value of `3`.
+ If the existing data type is a set, and if `Value` is also a set, then `Value` is appended to the existing set. For example, if the attribute value is the set `[1,2]`, and the `ADD` action specified `[3]`, then the final attribute value is `[1,2,3]`. An error occurs if an `ADD` action is specified for a set attribute and the attribute type specified does not match the existing set type.
Both sets must have the same primitive data type. For example, if the existing data type is a set of strings, `Value` must also be a set of strings.
If no item with the specified key is found in the table, the following values perform the following actions:
+ `PUT` - Causes DynamoDB to create a new item with the specified primary key, and then adds the attribute.
+ `DELETE` - Nothing happens, because attributes cannot be deleted from a nonexistent item. The operation succeeds, but DynamoDB does not create a new item.
+ `ADD` - Causes DynamoDB to create an item with the supplied primary key and number (or set of numbers) for the attribute value. The only data types allowed are Number and Number Set.
If you provide any attributes that are part of an index key, then the data types for those attributes must match those of the schema in the table's attribute definition.
## Use *UpdateExpression* instead – Example
Suppose you wanted to modify an item in the *Music* table. You could use an `UpdateItem` request with an `AttributeUpdates` parameter, as in this AWS CLI example:
```
aws dynamodb update-item \
--table-name Music \
--key '{
"SongTitle": {"S":"Call Me Today"},
"Artist": {"S":"No One You Know"}
}' \
--attribute-updates '{
"Genre": {
"Action": "PUT",
"Value": {"S":"Rock"}
}
}'
```
You can use a `UpdateExpression` instead:
```
aws dynamodb update-item \
--table-name Music \
--key '{
"SongTitle": {"S":"Call Me Today"},
"Artist": {"S":"No One You Know"}
}' \
--update-expression 'SET Genre = :g' \
--expression-attribute-values '{
":g": {"S":"Rock"}
}'
```
# ConditionalOperator (legacy)
**Note**
We recommend that you use the new expression parameters instead of these legacy parameters whenever possible. For more information, see [Using expressions in DynamoDB](Expressions.md).
The legacy conditional parameter `ConditionalOperator` is a logical operator used to apply to the conditions in a `Expected`, `QueryFilter` or `ScanFilter` 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 evaluates 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.
**Note**
This parameter does not support attributes of type List or Map.
# Expected (legacy)
**Note**
We recommend that you use the new expression parameters instead of these legacy parameters whenever possible. For more information, see [Using expressions in DynamoDB](Expressions.md). For specific information on the new parameter replacing this one, [use *ConditionExpression* instead.](#Expected.instead).
The legacy conditional parameter `Expected` is a conditional block for an `UpdateItem` operation. `Expected` is a map of attribute/condition pairs. Each element of the map consists of an attribute name, a comparison operator, and one or more values. DynamoDB compares the attribute with the value(s) you supplied, using the comparison operator. For each `Expected` element, the result of the evaluation is either true or false.
If you specify more than one element in the `Expected` map, then by default all of the conditions must evaluate to true. In other words, the conditions are combined using `AND` operator. (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.)
If the `Expected` map evaluates to true, then the conditional operation succeeds; otherwise, it fails.
`Expected` contains 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 Unicode with UTF-8 binary encoding. For example, `a` is greater than `A`, and `a` is greater than `B`.
For type Binary, DynamoDB treats each byte of the binary data as unsigned when it compares binary values.
+ `ComparisonOperator` - A comparator for evaluating attributes in the `AttributeValueList`. When performing the comparison, DynamoDB uses strongly consistent reads.
The following comparison operators are available:
`EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN`
The following are descriptions of each comparison operator.
+ `EQ` : Equal. `EQ` is supported for all data types, including lists and maps.
`AttributeValueList` can contain only one `AttributeValue` element of type String, Number, Binary, String Set, Number Set, or Binary Set. If an item contains an `AttributeValue` element of a different type than the one provided 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"]}`.
+ `NE` : Not equal. `NE` is supported for all data types, including lists and maps.
`AttributeValueList` can contain only one `AttributeValue` of type String, Number, Binary, String Set, Number Set, or Binary Set. If an item contains an `AttributeValue` of a different type than the one provided 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 provided 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"]}`.
+ `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 provided 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"]}`.
+ `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 provided 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"]}`.
+ `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 provided 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"]}`.
+ `NOT_NULL` : The attribute exists. `NOT_NULL` is supported for all data types, including lists and maps.
**Note**
This operator tests for the existence of an attribute, not its data type. If the data type of attribute "`a`" is null, and you evaluate it using `NOT_NULL`, the result is a Boolean `true`. This result is because the attribute "`a`" exists; its data type is not relevant to the `NOT_NULL` comparison operator.
+ `NULL` : The attribute does not exist. `NULL` is supported for all data types, including lists and maps.
**Note**
This operator tests for the nonexistence of an attribute, not its data type. If the data type of attribute "`a`" is null, and you evaluate it using `NULL`, the result is a Boolean `false`. This is because the attribute "`a`" exists; its data type is not relevant to the `NULL` comparison operator.
+ `CONTAINS` : Checks for a subsequence, or value in a set.
`AttributeValueList` can contain only one `AttributeValue` element of type String, Number, or Binary (not a set type). If the target attribute of the comparison is of type String, then the operator checks for a substring match. If the target attribute of the comparison is of type Binary, then the operator looks for a subsequence of the target that matches the input. If the target attribute of the comparison is a set ("`SS`", "`NS`", or "`BS`"), then the operator evaluates to true if it finds an exact match with any member of the set.
CONTAINS is supported for lists: When evaluating "`a CONTAINS b`", " `a`" can be a list; however, "`b`" cannot be a set, a map, or a list.
+ `NOT_CONTAINS` : Checks for absence of a subsequence, or absence of a value in a set.
`AttributeValueList` can contain only one `AttributeValue` element of type String, Number, or Binary (not a set type). If the target attribute of the comparison is a String, then the operator checks for the absence of a substring match. If the target attribute of the comparison is Binary, then the operator checks for the absence of a subsequence of the target that matches the input. If the target attribute of the comparison is a set ("`SS`", "`NS`", or "`BS`"), then the operator evaluates to true if it `does not` find an exact match with any member of the set.
NOT\$1CONTAINS is supported for lists: When evaluating "`a NOT CONTAINS b`", " `a`" can be a list; however, "`b`" cannot be a set, a map, or a list.
+ `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).
+ `IN` : Checks for matching elements within two sets.
`AttributeValueList` can contain one or more `AttributeValue` elements of type String, Number, or Binary (not a set type). These attributes are compared against an existing set type attribute of an item. If any elements of the input set are present in the item attribute, the expression evaluates to true.
+ `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 provided 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"]}`
The following parameters can be used instead of `AttributeValueList` and `ComparisonOperator`:
+ `Value` - A value for DynamoDB to compare with an attribute.
+ `Exists` - A Boolean value that causes DynamoDB to evaluate the value before attempting the conditional operation:
+ If `Exists` is `true`, DynamoDB will check to see if that attribute value already exists in the table. If it is found, then the condition evaluates to true; otherwise the condition evaluates to false.
+ If `Exists` is `false`, DynamoDB assumes that the attribute value does `not` exist in the table. If in fact the value does not exist, then the assumption is valid and the condition evaluates to true. If the value is found, despite the assumption that it does not exist, the condition evaluates to false.
Note that the default value for `Exists` is `true`.
The `Value` and `Exists` parameters are incompatible with `AttributeValueList` and `ComparisonOperator`. Note that if you use both sets of parameters at once, DynamoDB will return a `ValidationException` exception.
**Note**
This parameter does not support attributes of type List or Map.
## Use *ConditionExpression* instead – Example
Suppose you wanted to modify an item in the *Music* table, but only if a certain condition was true. You could use an `UpdateItem` request with an `Expected` parameter, as in this AWS CLI example:
```
aws dynamodb update-item \
--table-name Music \
--key '{
"Artist": {"S":"No One You Know"},
"SongTitle": {"S":"Call Me Today"}
}' \
--attribute-updates '{
"Price": {
"Action": "PUT",
"Value": {"N":"1.98"}
}
}' \
--expected '{
"Price": {
"ComparisonOperator": "LE",
"AttributeValueList": [ {"N":"2.00"} ]
}
}'
```
You can use a `ConditionExpression` instead:
```
aws dynamodb update-item \
--table-name Music \
--key '{
"Artist": {"S":"No One You Know"},
"SongTitle": {"S":"Call Me Today"}
}' \
--update-expression 'SET Price = :p1' \
--condition-expression 'Price <= :p2' \
--expression-attribute-values '{
":p1": {"N":"1.98"},
":p2": {"N":"2.00"}
}'
```
# KeyConditions (legacy)
**Note**
We recommend that you use the new expression parameters instead of these legacy parameters whenever possible. For more information, see [Using expressions in DynamoDB](Expressions.md). For specific information on the new parameter replacing this one, [use *KeyConditionExpression* instead.](#KeyConditionExpression.instead).
The legacy conditional parameter `KeyConditions` contains selection criteria for a `Query` operation. For a query on a table, you can have conditions only on the table primary key attributes. You must provide the partition key name and value as an `EQ` condition. You can optionally provide a second condition, referring to the sort key.
**Note**
If you don't provide a sort key condition, all of the items that match the partition key will be retrieved. If a `FilterExpression` or `QueryFilter` is present, it will be applied after the items are retrieved.
For a query on an index, you can have conditions only on the index key attributes. You must provide the index partition key name and value as an `EQ` condition. You can optionally provide a second condition, referring to the index sort key.
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 Unicode with UTF-8 binary encoding. For example, `a` is greater than `A`, and `a` is greater than `B`.
For Binary, DynamoDB treats each byte of the binary data as unsigned when it compares binary values.
+ `ComparisonOperator` - A comparator for evaluating attributes. For example: equals, greater than, and less than.
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 provided 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"]}`.
+ `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 provided 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"]}`.
+ `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 provided 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"]}`.
+ `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 provided 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"]}`.
+ `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).
+ `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 provided 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"]}`.
## Use *KeyConditionExpression* instead – Example
Suppose you wanted to retrieve several items with the same partition key from the *Music* table. You could use a `Query` request with a `KeyConditions` parameter, as in this AWS CLI example:
```
aws dynamodb query \
--table-name Music \
--key-conditions '{
"Artist":{
"ComparisonOperator":"EQ",
"AttributeValueList": [ {"S": "No One You Know"} ]
},
"SongTitle":{
"ComparisonOperator":"BETWEEN",
"AttributeValueList": [ {"S": "A"}, {"S": "M"} ]
}
}'
```
You can use a `KeyConditionExpression` instead:
```
aws dynamodb query \
--table-name Music \
--key-condition-expression 'Artist = :a AND SongTitle BETWEEN :t1 AND :t2' \
--expression-attribute-values '{
":a": {"S": "No One You Know"},
":t1": {"S": "A"},
":t2": {"S": "M"}
}'
```
# QueryFilter (legacy)
**Note**
We recommend that you use the new expression parameters instead of these legacy parameters whenever possible. For more information, see [Using expressions in DynamoDB](Expressions.md). For specific information on the new parameter replacing this one, [use *FilterExpression* instead.](#FilterExpression.instead).
In a `Query` operation, the legacy conditional parameter `QueryFilter` is a condition that evaluates the query results after the items are read and returns only the desired values.
This parameter does not support attributes of type List or Map.
**Note**
A `QueryFilter` is applied after the items have already been read; the process of filtering does not consume any additional read capacity units.
If you provide 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 combined using the `AND` operator. (You can use the [ConditionalOperator (legacy)](LegacyConditionalParameters.ConditionalOperator.md) 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.)
Note that `QueryFilter` does not allow key attributes. You cannot define a filter condition on a partition key or a sort 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 UTF-8 binary encoding. For example, `a` is greater than `A`, and `a` is greater than `B`.
For type Binary, DynamoDB treats each byte of the binary data as unsigned when it compares binary values.
For information on specifying data types in JSON, see [DynamoDB low-level API](Programming.LowLevelAPI.md).
+ `ComparisonOperator` - A comparator for evaluating attributes. For example: equals, greater than, and less than.
The following comparison operators are available:
`EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN`
## Use *FilterExpression* instead – Example
Suppose you wanted to query the *Music* table and apply a condition to the matching items. You could use a `Query` request with a `QueryFilter` parameter, as in this AWS CLI example:
```
aws dynamodb query \
--table-name Music \
--key-conditions '{
"Artist": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"S": "No One You Know"} ]
}
}' \
--query-filter '{
"Price": {
"ComparisonOperator": "GT",
"AttributeValueList": [ {"N": "1.00"} ]
}
}'
```
You can use a `FilterExpression` instead:
```
aws dynamodb query \
--table-name Music \
--key-condition-expression 'Artist = :a' \
--filter-expression 'Price > :p' \
--expression-attribute-values '{
":p": {"N":"1.00"},
":a": {"S":"No One You Know"}
}'
```
# ScanFilter (legacy)
**Note**
We recommend that you use the new expression parameters instead of these legacy parameters whenever possible. For more information, see [Using expressions in DynamoDB](Expressions.md). For specific information on the new parameter replacing this one, [use *FilterExpression* instead.](#FilterExpression2.instead).
In a `Scan` operation, the legacy conditional parameter `ScanFilter` is a condition that evaluates the scan results and returns only the desired values.
**Note**
This parameter does not support attributes of type List or Map.
If you specify more than one condition in the `ScanFilter` 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 (legacy)](LegacyConditionalParameters.ConditionalOperator.md) 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.)
Each `ScanFilter` 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 UTF-8 binary encoding. For example, `a` is greater than `A`, and `a` is greater than `B`.
For Binary, DynamoDB treats each byte of the binary data as unsigned when it compares binary values.
For information on specifying data types in JSON, see [DynamoDB low-level API](Programming.LowLevelAPI.md).
+ `ComparisonOperator` - A comparator for evaluating attributes. For example: equals, greater than, and less than.
The following comparison operators are available:
`EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN`
## Use *FilterExpression* instead – Example
Suppose you wanted to scan the *Music* table and apply a condition to the matching items. You could use a `Scan` request with a `ScanFilter` parameter, as in this AWS CLI example:
```
aws dynamodb scan \
--table-name Music \
--scan-filter '{
"Genre":{
"AttributeValueList":[ {"S":"Rock"} ],
"ComparisonOperator": "EQ"
}
}'
```
You can use a `FilterExpression` instead:
```
aws dynamodb scan \
--table-name Music \
--filter-expression 'Genre = :g' \
--expression-attribute-values '{
":g": {"S":"Rock"}
}'
```
# Writing conditions with legacy parameters
**Note**
We recommend that you use the new expression parameters instead of these legacy parameters whenever possible. For more information, see [Using expressions in DynamoDB](Expressions.md).
The following section describes how to write conditions for use with legacy parameters, such as `Expected`, `QueryFilter`, and `ScanFilter`.
**Note**
New applications should use expression parameters instead. For more information, see [Using expressions in DynamoDB](Expressions.md).
## Simple conditions
With attribute values, you can write conditions for comparisons against table attributes. A condition always evaluates to true or false, and consists of:
+ `ComparisonOperator` — greater than, less than, equal to, and so on.
+ `AttributeValueList` (optional) — attribute value(s) to compare against. Depending on the `ComparisonOperator` being used, the `AttributeValueList` might contain one, two, or more values; or it might not be present at all.
The following sections describe the various comparison operators, along with examples of how to use them in conditions.
### Comparison operators with no attribute values
+ `NOT_NULL` - true if an attribute exists.
+ `NULL` - true if an attribute does not exist.
Use these operators to check whether an attribute exists, or doesn't exist. Because there is no value to compare against, do not specify `AttributeValueList`.
**Example**
The following expression evaluates to true if the *Dimensions* attribute exists.
```
...
"Dimensions": {
ComparisonOperator: "NOT_NULL"
}
...
```
### Comparison operators with one attribute value
+ `EQ` - true if an attribute is equal to a value.
`AttributeValueList` can contain only one value of type String, Number, Binary, String Set, Number Set, or Binary Set. If an item contains a value of a different type than the one specified in the request, the value does not match. For example, the string `"3"` is not equal to the number `3`. Also, the number `3` is not equal to the number set `[3, 2, 1]`.
+ `NE` - true if an attribute is not equal to a value.
`AttributeValueList` can contain only one value of type String, Number, Binary, String Set, Number Set, or Binary Set. If an item contains a value of a different type than the one specified in the request, the value does not match.
+ `LE` - true if an attribute is less than or equal to a value.
`AttributeValueList` can contain only one value of type String, Number, or Binary (not a set). If an item contains an `AttributeValue` of a different type than the one specified in the request, the value does not match.
+ `LT` - true if an attribute is less than a value.
`AttributeValueList` can contain only one value of type String, Number, or Binary (not a set). If an item contains a value of a different type than the one specified in the request, the value does not match.
+ `GE` - true if an attribute is greater than or equal to a value.
`AttributeValueList` can contain only one value of type String, Number, or Binary (not a set). If an item contains a value of a different type than the one specified in the request, the value does not match.
+ `GT` - true if an attribute is greater than a value.
`AttributeValueList` can contain only one value of type String, Number, or Binary (not a set). If an item contains a value of a different type than the one specified in the request, the value does not match.
+ `CONTAINS` - true if a value is present within a set, or if one value contains another.
`AttributeValueList` can contain only one value of type String, Number, or Binary (not a set). If the target attribute of the comparison is a String, then the operator checks for a substring match. If the target attribute of the comparison is Binary, then the operator looks for a subsequence of the target that matches the input. If the target attribute of the comparison is a set, then the operator evaluates to true if it finds an exact match with any member of the set.
+ `NOT_CONTAINS` - true if a value is *not* present within a set, or if one value does not contain another value.
`AttributeValueList` can contain only one value of type String, Number, or Binary (not a set). If the target attribute of the comparison is a String, then the operator checks for the absence of a substring match. If the target attribute of the comparison is Binary, then the operator checks for the absence of a subsequence of the target that matches the input. If the target attribute of the comparison is a set, then the operator evaluates to true if it *does not* find an exact match with any member of the set.
+ `BEGINS_WITH` - true if the first few characters of an attribute match the provided value. Do not use this operator for comparing numbers.
`AttributeValueList` can contain only one value of type String or Binary (not a Number or a set). The target attribute of the comparison must be a String or Binary (not a Number or a set).
Use these operators to compare an attribute with a value. You must specify an `AttributeValueList` consisting of a single value. For most of the operators, this value must be a scalar; however, the `EQ` and `NE` operators also support sets.
**Examples**
The following expressions evaluate to true if:
+ A product's price is greater than 100.
```
...
"Price": {
ComparisonOperator: "GT",
AttributeValueList: [ {"N":"100"} ]
}
...
```
+ A product category begins with "Bo".
```
...
"ProductCategory": {
ComparisonOperator: "BEGINS_WITH",
AttributeValueList: [ {"S":"Bo"} ]
}
...
```
+ A product is available in either red, green, or black:
```
...
"Color": {
ComparisonOperator: "EQ",
AttributeValueList: [
[ {"S":"Black"}, {"S":"Red"}, {"S":"Green"} ]
]
}
...
```
**Note**
When comparing set data types, the order of the elements does not matter. DynamoDB will return only the items with the same set of values, regardless of the order in which you specify them in your request.
### Comparison operators with two attribute values
+ `BETWEEN` - true if a value is between a lower bound and an upper bound, endpoints inclusive.
`AttributeValueList` must contain two elements of the same type, either String, Number, or Binary (not a set). 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 a value of a different type than the one specified in the request, the value does not match.
Use this operator to determine if an attribute value is within a range. The `AttributeValueList` must contain two scalar elements of the same type - String, Number, or Binary.
**Example**
The following expression evaluates to true if a product's price is between 100 and 200.
```
...
"Price": {
ComparisonOperator: "BETWEEN",
AttributeValueList: [ {"N":"100"}, {"N":"200"} ]
}
...
```
### Comparison operators with *n* attribute values
+ `IN` - true if a value is equal to any of the values in an enumerated list. Only scalar values are supported in the list, not sets. The target attribute must be of the same type and exact value in order to match.
`AttributeValueList` can contain one or more elements of type String, Number, or Binary (not a set). These attributes are compared against an existing non-set type attribute of an item. If *any* elements of the input set are present in the item attribute, the expression evaluates to true.
`AttributeValueList` can contain one or more values of type String, Number, or Binary (not a set). The target attribute of the comparison must be of the same type and exact value to match. A String never matches a String set.
Use this operator to determine whether the supplied value is within an enumerated list. You can specify any number of scalar values in `AttributeValueList`, but they all must be of the same data type.
**Example**
The following expression evaluates to true if the value for *Id* is 201, 203, or 205.
```
...
"Id": {
ComparisonOperator: "IN",
AttributeValueList: [ {"N":"201"}, {"N":"203"}, {"N":"205"} ]
}
...
```
## Using multiple conditions
DynamoDB lets you combine multiple conditions to form complex expressions. You do this by providing at least two expressions, with an optional [ConditionalOperator (legacy)](LegacyConditionalParameters.ConditionalOperator.md).
By default, when you specify more than one condition, *all* of the conditions must evaluate to true in order for the entire expression to evaluate to true. In other words, an implicit *AND* operation takes place.
**Example**
The following expression evaluates to true if a product is a book that has at least 600 pages. Both of the conditions must evaluate to true, since they are implicitly *AND*ed together.
```
...
"ProductCategory": {
ComparisonOperator: "EQ",
AttributeValueList: [ {"S":"Book"} ]
},
"PageCount": {
ComparisonOperator: "GE",
AttributeValueList: [ {"N":600"} ]
}
...
```
You can use [ConditionalOperator (legacy)](LegacyConditionalParameters.ConditionalOperator.md) to clarify that an *AND* operation will take place. The following example behaves in the same manner as the previous one.
```
...
"ConditionalOperator" : "AND",
"ProductCategory": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"N":"Book"} ]
},
"PageCount": {
"ComparisonOperator": "GE",
"AttributeValueList": [ {"N":600"} ]
}
...
```
You can also set `ConditionalOperator` to *OR*, which means that *at least one* of the conditions must evaluate to true.
**Example**
The following expression evaluates to true if a product is a mountain bike, if it is a particular brand name, or if its price is greater than 100.
```
...
ConditionalOperator : "OR",
"BicycleType": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"S":"Mountain" ]
},
"Brand": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"S":"Brand-Company A" ]
},
"Price": {
"ComparisonOperator": "GT",
"AttributeValueList": [ {"N":"100"} ]
}
...
```
**Note**
In a complex expression, the conditions are processed in order, from the first condition to the last.
You cannot use both AND and OR in a single expression.
## Other conditional operators
In previous releases of DynamoDB, the `Expected` parameter behaved differently for conditional writes. Each item in the `Expected` map represented an attribute name for DynamoDB to check, along with the following:
+ `Value` — a value to compare against the attribute.
+ `Exists` — determine whether the value exists prior to attempting the operation.
The `Value` and `Exists` options continue to be supported in DynamoDB; however, they only let you test for an equality condition, or whether an attribute exists. We recommend that you use `ComparisonOperator` and `AttributeValueList` instead, because these options let you construct a much wider range of conditions.
**Example**
A `DeleteItem` can check to see whether a book is no longer in publication, and only delete it if this condition is true. Here is an AWS CLI example using a legacy condition:
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{
"Id": {"N":"600"}
}' \
--expected '{
"InPublication": {
"Exists": true,
"Value": {"BOOL":false}
}
}'
```
The following example does the same thing, but does not use a legacy condition:
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{
"Id": {"N":"600"}
}' \
--expected '{
"InPublication": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"BOOL":false} ]
}
}'
```
**Example**
A `PutItem` operation can protect against overwriting an existing item with the same primary key attributes. Here is an example using a legacy condition:
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item '{
"Id": {"N":"500"},
"Title": {"S":"Book 500 Title"}
}' \
--expected '{
"Id": { "Exists": false }
}'
```
The following example does the same thing, but does not use a legacy condition:
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item '{
"Id": {"N":"500"},
"Title": {"S":"Book 500 Title"}
}' \
--expected '{
"Id": { "ComparisonOperator": "NULL" }
}'
```
**Note**
For conditions in the `Expected` map, do not use the legacy `Value` and `Exists` options together with `ComparisonOperator` and `AttributeValueList`. If you do this, your conditional write will fail.