DynamodbHow-ToBeginner · 4 min read

How to Choose Index Key in DynamoDB: Best Practices

Choose a partition key that evenly distributes your data to avoid hotspots, and a sort key that supports your query patterns by enabling range queries or sorting. Consider your application's access patterns first, then design keys that optimize for those queries.

📐

Syntax

In DynamoDB, an index key consists of a partition key (also called hash key) and optionally a sort key (also called range key). The syntax to define these keys when creating a table or index is:

PartitionKey: AttributeName (Type) - uniquely identifies partitions.
SortKey: AttributeName (Type) - organizes data within partitions.

json

{
  "TableName": "ExampleTable",
  "KeySchema": [
    { "AttributeName": "UserId", "KeyType": "HASH" },  // Partition key
    { "AttributeName": "Timestamp", "KeyType": "RANGE" } // Sort key
  ],
  "AttributeDefinitions": [
    { "AttributeName": "UserId", "AttributeType": "S" },
    { "AttributeName": "Timestamp", "AttributeType": "N" }
  ],
  "ProvisionedThroughput": {
    "ReadCapacityUnits": 5,
    "WriteCapacityUnits": 5
  }
}

💻

Example

This example shows how to choose index keys for a table storing user activity logs. The UserId is the partition key to distribute data by user, and Timestamp is the sort key to order activities by time.

javascript

const AWS = require('aws-sdk');
const dynamodb = new AWS.DynamoDB();

const params = {
  TableName: 'UserActivity',
  KeySchema: [
    { AttributeName: 'UserId', KeyType: 'HASH' },
    { AttributeName: 'Timestamp', KeyType: 'RANGE' }
  ],
  AttributeDefinitions: [
    { AttributeName: 'UserId', AttributeType: 'S' },
    { AttributeName: 'Timestamp', AttributeType: 'N' }
  ],
  ProvisionedThroughput: {
    ReadCapacityUnits: 5,
    WriteCapacityUnits: 5
  }
};

dynamodb.createTable(params, (err, data) => {
  if (err) console.log('Error', err);
  else console.log('Table Created', data);
});

Output

Table Created { TableDescription: { TableName: 'UserActivity', TableStatus: 'CREATING', ... } }

⚠️

Common Pitfalls

Common mistakes when choosing index keys include:

Using a partition key with low cardinality, causing uneven data distribution and throttling.
Not using a sort key when queries need sorting or range filtering.
Choosing keys that don't match your query patterns, leading to inefficient scans.

Always analyze your access patterns before deciding keys.

json

/* Wrong: Partition key with few values causes hotspots */
KeySchema: [
  { AttributeName: 'Status', KeyType: 'HASH' } // e.g., only 'active' or 'inactive'
]

/* Right: Partition key with many unique values */
KeySchema: [
  { AttributeName: 'UserId', KeyType: 'HASH' }
]

📊

Quick Reference

Tips for choosing DynamoDB index keys:

Partition Key: Choose a unique attribute with many distinct values to spread data evenly.
Sort Key: Use when you want to sort or filter items within a partition.
Access Patterns: Design keys based on how your app queries data.
Secondary Indexes: Use Global or Local Secondary Indexes to support additional query patterns.

✅

Key Takeaways

Pick a partition key that evenly distributes data to avoid performance bottlenecks.

Use a sort key to enable efficient sorting and range queries within partitions.

Design keys based on your application's query patterns for best performance.

Avoid low-cardinality keys that cause uneven data distribution and throttling.

Consider secondary indexes to support multiple query types without scanning.