How to Use ScanIndexForward for Sorting in DynamoDB

In DynamoDB, use the ScanIndexForward parameter in a Query operation to control the sort order of the results. Setting ScanIndexForward to true returns results in ascending order by the sort key, while false returns them in descending order.

Syntax

The ScanIndexForward parameter is used in a DynamoDB Query operation to specify the order of the sort key values in the results.

• ScanIndexForward: true - Results are sorted in ascending order (default).
• ScanIndexForward: false - Results are sorted in descending order.

This parameter only affects the order of items returned by the Query operation on tables or indexes that have a sort key.

javascript

const params = {
  TableName: 'YourTableName',
  KeyConditionExpression: '#pk = :pkValue',
  ExpressionAttributeNames: {
    '#pk': 'PartitionKey'
  },
  ExpressionAttributeValues: {
    ':pkValue': 'someKey'
  },
  ScanIndexForward: true // or false
};

Example

This example demonstrates how to query a DynamoDB table named Orders to get all orders for a customer with ID 123, sorted by order date in descending order.

javascript

const { DynamoDBClient, QueryCommand } = require('@aws-sdk/client-dynamodb');

const client = new DynamoDBClient({ region: 'us-east-1' });

async function queryOrdersDescending() {
  const params = {
    TableName: 'Orders',
    KeyConditionExpression: 'CustomerId = :cid',
    ExpressionAttributeValues: {
      ':cid': { S: '123' }
    },
    ScanIndexForward: false // descending order
  };

  try {
    const data = await client.send(new QueryCommand(params));
    console.log('Orders sorted descending by OrderDate:');
    data.Items.forEach(item => {
      console.log(item);
    });
  } catch (err) {
    console.error(err);
  }
}

queryOrdersDescending();

Output

Orders sorted descending by OrderDate:
{ CustomerId: { S: '123' }, OrderDate: { S: '2023-06-15' }, OrderId: { S: 'A100' } }
{ CustomerId: { S: '123' }, OrderDate: { S: '2023-05-10' }, OrderId: { S: 'A99' } }
{ CustomerId: { S: '123' }, OrderDate: { S: '2023-04-01' }, OrderId: { S: 'A98' } }

Common Pitfalls

• Using ScanIndexForward with Scan operation: The ScanIndexForward parameter only works with Query operations, not Scan. Using it with Scan has no effect.
• Ignoring sort key presence: ScanIndexForward only applies if your table or index has a sort key. Without a sort key, sorting is not possible.
• Confusing ascending/descending: Remember, true means ascending order, false means descending order.

javascript

/* Wrong: Using ScanIndexForward with Scan */
const paramsWrong = {
  TableName: 'Orders',
  ScanIndexForward: false
};

/* Right: Use Query with KeyConditionExpression and ScanIndexForward */
const paramsRight = {
  TableName: 'Orders',
  KeyConditionExpression: 'CustomerId = :cid',
  ExpressionAttributeValues: { ':cid': { S: '123' } },
  ScanIndexForward: false
};

Quick Reference

Parameter	Description	Default Value
ScanIndexForward	Boolean to set sort order of query results by sort key	true (ascending order)
true	Sort results in ascending order	N/A
false	Sort results in descending order	N/A

Key Takeaways

Use ScanIndexForward in Query operations to control sorting by the sort key.

Set ScanIndexForward to true for ascending order and false for descending order.

ScanIndexForward does not work with Scan operations or tables without a sort key.

Always include a KeyConditionExpression when using ScanIndexForward in a Query.

Remember the default sort order is ascending if ScanIndexForward is not specified.