DynamoDB Sort Key - The Ultimate Guide [w/ Code Examples]

Published on March 21st, 2022

Still using AWS console to work with DynamoDB? 🙈

Time to 10x your DynamoDB productivity with Dynobase [learn more]

What is Sort Key in DynamoDB

DynamoDB supports two primary keys: the partition key and the composite primary key. The partition key is a single attribute, whereas the composite primary key is a combination of 2 attributes named hash key and sort key.

The sort key is also known as a range attribute of an item, and it helps to organize related information in a single location where it can be efficiently queried.

DynamoDB Composite Primary Key

Sort Key vs. Other Key Types

Sort Key vs. Partition Key

DynamoDB uses the partition key as an input to the hash function. The hash function's output decides which partition the item will be placed in, and all items with the same partition key value are stored together.

The sort key is used to sort and order items in a partition. Multiple items with the same partition key value are feasible, but they should have different sort key values. This means you can have multiple items with the same partition keys, but the sort key can not be the same.

Sort Key vs. Range Key

An item's sort key is also called its range attribute. The range attribute refers to how DynamoDB stores items with the same partition key physically close together, sorted by sort key value.

Working with Sort Key (Code Examples)

How to Add a Sort Key

First, let's create an object called Book which represents an item in a DynamoDB table. The Book class is accessible via getter and setter methods to correctly persist the data using DynamoDBMapper.

In this example, the primary key for Book is made up of two BookAuthor (partition key) and BookTitle (sort key) attributes. You can query data using the partition key or the composite primary key.

However, you need to add the sort key at the initial table creation state as you can not add a sort key for an already existing table.

// DynamoDBTable : is the Java annotation to map a property to a table attribute.
// DynamoDBHashKey: is the Java annotation for the Partition key 
// DynamoDBRangeKey: is the Java annotation for the Sort key

package com.dynamoDbDemo.entity;
import com.amazonaws.services.dynamodbv2.datamodeling.*;

@DynamoDBTable(tableName = "Book") // Make sure to give the same table name which you provide in AWS Console
public class Book {
    private String bookAuthor;
    private String bookTitle;
    private String bookType;

    @DynamoDBHashKey(attributeName="BookAuthor") // partition key@DynamoDBAutoGeneratedKeypublic String getBookAuthor() {return bookAuthor;
    }

    public void setBookAuthor(String bookAuthor) {
        this.bookAuthor = bookAuthor;
    }

    @DynamoDBRangeKey(attributeName="BookTitle") // sort key
    
    public String getBookTitle() {
      return bookTitle;
    }

    public void setBookTitle(String bookTitle) {
        this.bookTitle = bookTitle;
    }
    @DynamoDBAttribute(attributeName="BookType")
    public String getBookType() {
        return bookType;
    }

    public void setBookType(String bookType) {
        this.bookType = bookType;
    }

    @Overridepublic String toString() {
        return "Book{" +
                "bookAuthor='" + bookAuthor + '\'' +
                ", bookTitle='" + bookTitle + '\'' +
                ", bookType='" + bookType + '\'' +
                '}';
    }
}// DynamoDBTable : is the Java annotation to map a property to a table attribute.
// DynamoDBHashKey: is the Java annotation for the Partition key 
// DynamoDBRangeKey: is the Java annotation for the Sort key

package com.dynamoDbDemo.entity;
import com.amazonaws.services.dynamodbv2.datamodeling.*;

@DynamoDBTable(tableName = "Book") // Make sure to give the same table name which you provide in AWS Console
public class Book {
    private String bookAuthor;
    private String bookTitle;
    private String bookType;

    @DynamoDBHashKey(attributeName="BookAuthor") // partition key@DynamoDBAutoGeneratedKeypublic String getBookAuthor() {return bookAuthor;
    }

    public void setBookAuthor(String bookAuthor) {
        this.bookAuthor = bookAuthor;
    }

    @DynamoDBRangeKey(attributeName="BookTitle") // sort key
    
    public String getBookTitle() {
      return bookTitle;
    }

    public void setBookTitle(String bookTitle) {
        this.bookTitle = bookTitle;
    }
    @DynamoDBAttribute(attributeName="BookType")
    public String getBookType() {
        return bookType;
    }

    public void setBookType(String bookType) {
        this.bookType = bookType;
    }

    @Overridepublic String toString() {
        return "Book{" +
                "bookAuthor='" + bookAuthor + '\'' +
                ", bookTitle='" + bookTitle + '\'' +
                ", bookType='" + bookType + '\'' +
                '}';
    }
}

How to Change a Sort Key

You can not change the Sort key after the table is provisioned. You can create a new table and put the exciting data in the newly created table, and delete the old table.

Query by Sort Key

To query by sort key, you need to use both the sort key and the partition key. The query is quicker and cheaper than the scan, and you can fetch up to 1MB of records. The following code shows how to query by the sort key in Java.

void query(){
    Map<String, AttributeValue> eav = new HashMap<String, AttributeValue>();
    eav.put(":v1",new AttributeValue().withS("J. K. Rowling "));
    eav.put(":v2", new AttributeValue().withS("Harry Potter and the Chamber of Secrets"));

    DynamoDBQueryExpression<Book> queryExpression = new DynamoDBQueryExpression<Book>()
            .withKeyConditionExpression("BookAuthor = :v1 and BookTitle= :v2")
            .withExpressionAttributeValues(eav);
    List<Book> books = dynamoDBMapper.query(Book.class,queryExpression);

}void query(){
    Map<String, AttributeValue> eav = new HashMap<String, AttributeValue>();
    eav.put(":v1",new AttributeValue().withS("J. K. Rowling "));
    eav.put(":v2", new AttributeValue().withS("Harry Potter and the Chamber of Secrets"));

    DynamoDBQueryExpression<Book> queryExpression = new DynamoDBQueryExpression<Book>()
            .withKeyConditionExpression("BookAuthor = :v1 and BookTitle= :v2")
            .withExpressionAttributeValues(eav);
    List<Book> books = dynamoDBMapper.query(Book.class,queryExpression);

}

Query by Sort Key Only

You can not query only using a Sort Key. You need to specify a partition key to perform query operations. Else, you need to create a global secondary index or perform a scan operation.

Query with sort key filter

The following Java code example retrieves only "Science Fiction & Fantasy" types of books written by J. K. Rowling, Book titles (sort key) that begin with the letter "H" through the letter "S."

// KeyConditionExpression to retrieve the books from a specific Book Author(partition key) and, within that set of items, Book titles (sort key) that begin with the letter "H" through the letter "S".

// FilterExpression to return only the books from a specific Book type(Science Fiction & Fantasy)

void queryFilter(){
    Map<String, AttributeValue> eav = new HashMap<String, AttributeValue>();
    eav.put(":v1_author",new AttributeValue().withS("J. K. Rowling "));
    eav.put(":letter1", new AttributeValue().withS("H"));
    eav.put(":letter1", new AttributeValue().withS("S"));
    eav.put(":v_book_type", new AttributeValue().withS("Science Fiction & Fantasy"));

    DynamoDBQueryExpression<Book> queryExpression = new DynamoDBQueryExpression<Book>()
            .withKeyConditionExpression("BookAuthor = :v1_author and BookTitle between :letter1 and :letter2")
            .withFilterExpression("BookType= :v_book_type")
            .withExpressionAttributeValues(eav);
    List<Book> books = dynamoDBMapper.query(Book.class,queryExpression);

}// KeyConditionExpression to retrieve the books from a specific Book Author(partition key) and, within that set of items, Book titles (sort key) that begin with the letter "H" through the letter "S".

// FilterExpression to return only the books from a specific Book type(Science Fiction & Fantasy)

void queryFilter(){
    Map<String, AttributeValue> eav = new HashMap<String, AttributeValue>();
    eav.put(":v1_author",new AttributeValue().withS("J. K. Rowling "));
    eav.put(":letter1", new AttributeValue().withS("H"));
    eav.put(":letter1", new AttributeValue().withS("S"));
    eav.put(":v_book_type", new AttributeValue().withS("Science Fiction & Fantasy"));

    DynamoDBQueryExpression<Book> queryExpression = new DynamoDBQueryExpression<Book>()
            .withKeyConditionExpression("BookAuthor = :v1_author and BookTitle between :letter1 and :letter2")
            .withFilterExpression("BookType= :v_book_type")
            .withExpressionAttributeValues(eav);
    List<Book> books = dynamoDBMapper.query(Book.class,queryExpression);

}

Query Sort Key Descending

The sort key value is always used to sort query results. If the sort key is a number, the results will be returned in numerical order. Else, the results will be returned in UTF-8 bytes order. The sort order is set to ascending by default. However, you can set the ScanIndexForward parameter to false if you need the sort order to be Descending.

DynamoDBQueryExpression<Book> queryExpression = new DynamoDBQueryExpression<Book>();
queryExpression.setScanIndexForward(false);
DynamoDBQueryExpression<Book> queryExpression = new DynamoDBQueryExpression<Book>();
queryExpression.setScanIndexForward(false);

Best Practices For Using Sort Keys in DynamoDB

You can not change the Sort key after the table is provisioned. Therefore be mindful when creating a sort key.
If your data contains hierarchical (one-to-many) relationships and you want to query at any hierarchy level, use a composite primary key. E.g., Address that contains zip code, postal code, country, city, etc.
The sort key should be structured as follows.

[country]#[region]#[state]#[county]#[city]#[neighborhood][country]#[region]#[state]#[county]#[city]#[neighborhood]

You can use the sort key along with a prefix to keep a record of item-level revisions such as V0, V1, V2, etc.
If you need to query a subset of items, use a composite primary key. For example, if you only provide the value for the BookAuthor, DynamoDB retrieves all of that author's books. You can provide a value for the BookAuthor and a range of _BookTitle_ values to retrieve only a subset of books by a specific author.
Sort key only supports string, number, or binary data types.
Always try to use a composite primary key as the primary key. If you only use the partition key as the primary key when creating a table, you won't perform query operations or use key condition expressions.

Frequently Asked Questions

1. Can we update the sort key in DynamoDB?

No, you can not update the sort key after the table is provisioned. However, you can create a new table and put the existing data in the newly created table, and delete the old table.