Skip to main content

Filters and Conditions

DynamoDB supports Filter and Condition expressions. Filter Expressions are used to limit data returned by query and scan operations. Condition Expressions are used for data manipulation operations (put, update, delete and batchWrite), allowing you to specify a condition to determine which items should be modified.

Expression Builder

The DynamoDB Toolbox provides an Expression Builder that allows you to generate complex filters and conditions based on your Entity definitions. Any method that requires filters or conditions accepts an array of conditions, or a single condition. Condition objects support the following properties:

PropertyTypeDescription
attrstringSpecifies the attribute to filter on. If an entity property is provided (or inherited from the calling operation), aliases can be used. Either attr or size must be provided.
sizestringSpecifies which attribute's calculated size to filter on (see Operators and Functions for more information). If an entity property is provided (or inherited from the calling operation), aliases can be used. Either attr or size must be provided.
eq*2Specifies value to equal attribute or size of attribute.
ne*2Specifies value to not equal attribute or size of attribute.
lt*2Specifies value for attribute or size to be less than.
lte*2Specifies value for attribute or size to be less than or equal to.
gt*2Specifies value for attribute or size to be greater than.
gte*2Specifies value for attribute or size to be greater than or equal to.
betweenarraySpecifies values for attribute or size to be between. E.g. [18,49].
beginsWith*1Specifies value for the attribute to begin with
inarraySpecifies and array of values that the attribute or size must match one value.
containsstringSpecifies value that must be contained within a string or Set. (see Operators and Functions for more information)
existsbooleanChecks whether or not the attribute exists for an item. A value of true uses the attribute_exists() function and a value of false uses the attribute_not_exists() function (see Operators and Functions for more information)
typestringA value that compares the attribute's type. Value must be one of S,SS, N, NS, B, BS, BOOL, NULL, L, or M (see Operators and Functions for more information)
orbooleanChanges the logical evaluation to OR (by default it's AND)
negatebooleanAdds NOT to the condition.
entitystringThe entity this attribute applies to. If supplied (or inherited from the calling operation), attr and size properties can use the entity's aliases to reference attributes.

1 Comparison values should equal the type of the attribute you are comparing against. If you are using the size property, the value should be a number.
2 In addition to *1, these also allow an object value with a key 'attr' and its value referencing another attribute of the same entity for comparing against. Example condition containing an attribute reference:

conditions: { attr: 'capacity', gt: { attr: 'reservations' } }

Complex Filters and Conditions

In order to create complex filters and conditions, the DynamoDB Toolbox allows you to nest and combine filters by using nested arrays. Array brackets ([ and ]) act as parentheses when constructing your condition. Using or in the first condition within an array will change the logical evaluation for group of conditions.

Condition where age is between 18 and 54 AND region equals "US":

MyTable.query(
// ...,
{
filters: [
{ attr: 'age', between: [18, 54] },
{ attr: 'region', eq: 'US' }
]
}
)

Condition where age is between 18 and 54 AND region equals "US" OR "EU":

MyTable.query(
// ...,
{
filters: [
{ attr: 'age', between: [18, 54] },
[
{ attr: 'region', eq: 'US' },
{ or: true, attr: 'region', eq: 'EU' }
]
]
}
)

Condition where age is greater than 21 OR ((region equals "US" AND interests size is greater than 10) AND interests contain nodejs, dynamodb, or serverless):

MyTable.query(
// ...,
{
filters: [
{ attr: 'age', gt: 21 },
[
[
{ or: true, attr: 'region', eq: 'US' },
{ size: 'interests', gt: 10 }
],
[
{ attr: 'interests', contains: 'nodejs' },
{
or: true,
attr: 'interests',
contains: 'dynamodb'
},
{
or: true,
attr: 'interests',
contains: 'serverless'
}
]
]
]
}
)