What is Index Projection in DynamoDB: Explanation and Example

In DynamoDB, index projection defines which attributes from the main table are copied into a secondary index. It controls what data is available in the index to speed up queries without fetching the full table item.

How It Works

Imagine you have a big filing cabinet (your main DynamoDB table) with many folders (items). Sometimes, you want to quickly find certain folders based on a few details without opening every folder. A secondary index is like a smaller cabinet that holds copies of some important details from the big cabinet.

Index projection decides which details (attributes) from the big cabinet get copied into the smaller cabinet. This helps DynamoDB answer queries faster because it can look only in the smaller cabinet instead of searching the whole big one.

There are three types of projections: KEYS_ONLY copies only the primary key attributes, INCLUDE copies specific chosen attributes, and ALL copies all attributes from the main table into the index.

Example

This example shows how to create a global secondary index with an INCLUDE projection to copy only specific attributes.

javascript

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

const params = {
  TableName: 'Products',
  AttributeDefinitions: [
    { AttributeName: 'ProductId', AttributeType: 'S' },
    { AttributeName: 'Category', AttributeType: 'S' },
    { AttributeName: 'ProductName', AttributeType: 'S' },
    { AttributeName: 'Price', AttributeType: 'N' }
  ],
  KeySchema: [
    { AttributeName: 'ProductId', KeyType: 'HASH' }
  ],
  GlobalSecondaryIndexes: [
    {
      IndexName: 'CategoryIndex',
      KeySchema: [
        { AttributeName: 'Category', KeyType: 'HASH' }
      ],
      Projection: {
        ProjectionType: 'INCLUDE',
        NonKeyAttributes: ['ProductName', 'Price']
      },
      ProvisionedThroughput: {
        ReadCapacityUnits: 5,
        WriteCapacityUnits: 5
      }
    }
  ],
  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: 'Products', TableStatus: 'CREATING', ... } }

When to Use

Use index projection when you want your secondary index to include only the attributes needed for your queries. This saves storage and speeds up queries by avoiding copying unnecessary data.

For example, if you have a product catalog and often query by category, but only need the product name and price in results, use an INCLUDE projection with those attributes. If you only need keys to check existence, use KEYS_ONLY. Use ALL projection if you want the entire item in the index for fast access.

Key Points

• Index projection controls which attributes are copied to a secondary index.
• Three types: KEYS_ONLY, INCLUDE (specific attributes), and ALL.
• Choosing the right projection improves query speed and reduces storage.
• INCLUDE projection lets you pick only needed attributes, saving space.

Key Takeaways

Index projection defines which table attributes appear in a secondary index in DynamoDB.

Use KEYS_ONLY to copy only primary keys, INCLUDE to copy specific attributes, or ALL to copy everything.

Proper projection reduces storage costs and improves query performance.

Choose projection based on the attributes your queries need from the index.