DynamoDB Sort Key

The all you need to know about sort keys what ,when, why and how to use.

What Is Sort Key

In DynamoDb the primary key is used to uniquely identify the items in tables. It can be a partition key or combination of partition key and sort key which is also known as composite primary key. It is an optional part of primary key.

The Items in DynamoDB partitions are ordered by sort key in ascending order , sort key is also known as Range Key. Sort key support only scaler data types i.e. string, number and boolean

DynamoDB table structure with composite primary key

Why to Use it

Sort keys in dynamoDb remains a powerful feature that can help you organise and query your data more efficiently.However it is important to carefully consider the data model and query patterns used in order to define more accurate sort key.

A well defined sort key provides the capability to query dynamoDb tables by using the conditions like starts_with, between , <, > etc …

For defining hierarchical relationship in data we can define composite sort key For example in a table defining addresses we can define a composite sort key as below

By defining sort key as above we can query table with more granularity , like if we want to get data for a specific country then we can query with sortkey starts_with country# , similarly if we want to get data for any specific state we can query the table like sortkey starts_with country#region#state# .

Another example , Suppose you have a table that stores customer orders. The partition key is customerId and you want to fetch all orders by a given customer within a given time range. In this case we have sort key as timestamp of the order that will enable us to query the orders table with customerId and sort key with between condition expression to fetch the desired results.

When to Use

In Amazon DynamoDb you should use sort key when you want to add additional sorting and filtering capabilities to your queries.

In general, you should use a sort key when :

1. You need to filter items based on a specific range of values
2. You need to retrieve items in a specific order
3. You need to group related items together

How to Use it: with Code examples

we can query dynamoDB via AWS CLI,AWS Console, PartiQL,DynamoDB Apis and AWS SDK. Below are the some code examples how we can use sort key to query dynamoDB.

AWS CLI :

Below is the example queries table MyTable for fetching the items with given partition key and having sort key in a range of values.

aws dynamodb query --table-name MyTable \
--key-condition-expression "PartitionKey =:pk AND SortKey= BETWEEN :sk1 AND sk2"
--expression-attribute-values '{":pk": {"S": "partition-value"},":sk1": {"S": "sort-value1"}, ":sk2": {"S": "sort-value2"} }'

PartiQL:

DynamoDb support SQL via PartiQL

AWS SDK :

Below is the example to query dynamoDb with sort key using between operator in C#

using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.Model;
using System.Collections.Generic;
using System.Threading.Tasks;

public class DynamoDBExample
{
    private readonly IAmazonDynamoDB _dynamoDbClient;

    public DynamoDBExample(IAmazonDynamoDB dynamoDbClient)
    {
        _dynamoDbClient = dynamoDbClient;
    }

    public async Task QueryTableWithSortKeyAsync()
    {
        var partitionKey = "partition-value";
        var sortKeyCondition = new Condition
        {
            ComparisonOperator = ComparisonOperator.Between,
            AttributeValueList = new List<AttributeValue>
            {
                new AttributeValue { S = "sort-value1" },
                new AttributeValue { S = "sort-value2" }
            }
        };

        var queryRequest = new QueryRequest
        {
            TableName = "MyTable",
            KeyConditionExpression = "PartitionKey = :pk AND SortKey BETWEEN :sk1 AND :sk2",
            ExpressionAttributeValues = new Dictionary<string, AttributeValue>
            {
                { ":pk", new AttributeValue { S = partitionKey } },
                { ":sk1", sortKeyCondition.AttributeValueList[0] },
                { ":sk2", sortKeyCondition.AttributeValueList[1] }
            },
            ScanIndexForward = false // set this to false to sort the results in descending order by the sort key
        };

        var queryResponse = await _dynamoDbClient.QueryAsync(queryRequest);

        // handle the results
    }
}

Partition Key

DynamoDb use partition key (aka Hash key ) to identify/locate the right partition for the given data Item , it calculates the hash of partition key and place data accordingly in partitions.

Whereas the sort key is used to sort(order) the data within the partition , so that that it can be queried efficiently. The table with composite primary key can have multiple items with same partition key but these items should have different sort key.

Points to consider for sort key

1. The sort key attribute must be a scaler type.
2. Sort key must be unique within a partition i.e. there should be no other item having same partition key and same sort key
3. The attribute name cannot be same as of partition key attribute name.
4. Sort key name cannot be a reserved word name , list of reserved words for dynamoDb can be found here.
5. Sort key attribute name length must be less than 255 chars
6. Sort key attribute name must follow the attribute naming conventions for dynamoDb
7. Define a meaningful and descriptive name for sort key attribute that reflects the type of data it represents, this will help you to make query more understandable and efficient.

Conclusion

In conclusion , the sort key is a powerful feature of DynamoDb that enables us to query and sort the data efficiently. It provides way to sort data based on second attribute other than partition key and this can be helpful when you want to access data within a range.

When working with sort key , it’s important to keep in mind the naming rules for sort key and limitation of sort key queries. Additionally depending on use case you may want to use composite sort key or global secondary index to further optimise your queries.

Overall, the sort key is an essential part of DynamoDB’s flexibility and scalability and it’s worth taking time to understand how it works and how you can use it.