6.1: Key Condition Expressions

It is used on every Query operation to describe which items you want to fetch. Remember that the Query API call must include a partition key in the request. It may also include conditions on the sort key in the request.

A key condition can be used only on elements of the primary key, not on other attributes on the items.

Lets start with a simple Query request using just the partition key. Remember the customers we added in the starting of this chapter, lets now retrieve all the customers.


          import { QueryCommand } from "@aws-sdk/lib-dynamodb";
          import ddbDocClient from "@/lib/clients/dynamoDBClient";
          import { dbName } from "@/lib/constants";

          const dbCommand = new QueryCommand({
            TableName: dbName,
            KeyConditionExpression: "#pk_key = :pk_value",
            ExpressionAttributeNames: {
                "#pk_key": "pk",
            },
            ExpressionAttributeValues: {
                ":pk_value": "CUSTOMERS",
            },
          });

          const dbResponse = await ddbDocClient.send(dbCommand);

Primary Key		Attributes
Partition key: pk	Sort key: sk	firstName	lastName	phone	email	zipcode	shippingAddresses

You can also use conditions on the sort key in your key condition expression. This is useful for finding a specific subset of your data. All elements with a given partition key are sorted according to the sort key (hence the name).

In our example, we could use it to find a customer using their phone number.


          import { QueryCommand } from "@aws-sdk/lib-dynamodb";
          import ddbDocClient from "@/lib/clients/dynamoDBClient";
          import { dbName } from "@/lib/constants";

          const dbCommand = new QueryCommand({
                TableName: dbName,
                KeyConditionExpression: "#pk_key = :pk_value AND #sk_key = :sk_value",
                ExpressionAttributeNames: {
                    "#pk_key": "pk",
                    "#sk_key": "sk",
                },
                ExpressionAttributeValues: {
                    ":pk_value": "CUSTOMERS",
                    ":sk_value": "CUSTOMER#{parsedPhone.output}",
                },
            });

          const dbResponse = await ddbDocClient.send(dbCommand);

Primary Key		Attributes
Partition key: pk	Sort key: sk	firstName	lastName	phone	email	zipcode	shippingAddresses

The sort key condition must use one of the following comparison operators:

1: a = b — true if the attribute a is equal to the value b

2: a < b — true if a is less than b

3: a <= b — true if a is less than or equal to b

4: a > b — true if a is greater than b

5: a >= b — true if a is greater than or equal to b

6: a BETWEEN b AND c — true if a is greater than or equal to b, and less than or equal to c.

7: begins_with (a, substr)— true if the value of attribute a begins with a particular substring.

A typical example of using the key condition on the sort key is when your sort key is a timestamp. You can use the sort key condition to select all items that occurred before, after, or during a specific time range.

While you can use greater than, less than, equal to, or begins_with, one little secret is that every condition on the sort key can be expressed with the BETWEEN operator. Because of that, I almost always use it in my expressions.