Overview Application example Data model Prerequisites Implementation Pattern variations Complete example Additional resources

Multi-attribute keys pattern

Overview

Multi-attribute keys allow you to create Global Secondary Index (GSI) partition and sort keys composed of up to four attributes each. This reduces client-side code and makes it easier to initially model data and add new access patterns later.

Consider a common scenario: to create a GSI that queries items by multiple hierarchical attributes, you would traditionally need to create synthetic keys by concatenating values. For example, in a gaming app, to query tournament matches by tournament, region, and round, you might create a synthetic GSI partition key like TOURNAMENT#WINTER2024#REGION#NA-EAST and a synthetic sort key like ROUND#SEMIFINALS#BRACKET#UPPER. This approach works, but requires string concatenation when writing data, parsing when reading, and backfilling synthetic keys across all existing items if you're adding the GSI to an existing table. This makes code more cluttered and challenging to maintain type safety on individual key components.

Multi-attribute keys solve this problem for GSIs. You define your GSI partition key using multiple existing attributes like tournamentId and region. DynamoDB handles the composite key logic automatically, hashing them together for data distribution. You write items using natural attributes from your domain model, and the GSI automatically indexes them. No concatenation, no parsing, no backfilling. Your code stays clean, your data stays typed, and your queries stay simple. This approach is particularly useful when you have hierarchical data with natural attribute groupings (like tournament → region → round, or organization → department → team).

Application example

This guide walks through building a tournament match tracking system for an esports platform. The platform needs to efficiently query matches across multiple dimensions: by tournament and region for bracket management, by player for match history, and by date for scheduling.

Data model

In this walkthrough, the tournament match tracking system supports three primary access patterns, each requiring a different key structure:

Access pattern 1: Look up a specific match by its unique ID

Solution: Base table with matchId as partition key

Access pattern 2: Query all matches for a specific tournament and region, optionally filtering by round, bracket, or match

Solution: Global Secondary Index with multi-attribute partition key (tournamentId + region) and multi-attribute sort key (round + bracket + matchId)
Example queries: "All WINTER2024 matches in NA-EAST region" or "All SEMIFINALS matches in UPPER bracket for WINTER2024/NA-EAST"

Access pattern 3: Query a player's match history, optionally filtering by date range or tournament round

Solution: Global Secondary Index with single partition key (player1Id) and multi-attribute sort key (matchDate + round)
Example queries: "All matches for player 101" or "Player 101's matches in January 2024"

The key difference between traditional and multi-attribute approaches becomes clear when examining the item structure:

Traditional Global Secondary Index approach (concatenated keys):


// Manual concatenation required for GSI keys
const item = {
    matchId: 'match-001',                                          // Base table PK
    tournamentId: 'WINTER2024',
    region: 'NA-EAST',
    round: 'SEMIFINALS',
    bracket: 'UPPER',
    player1Id: '101',
    // Synthetic keys needed for GSI
    GSI_PK: `TOURNAMENT#${tournamentId}#REGION#${region}`,       // Must concatenate
    GSI_SK: `${round}#${bracket}#${matchId}`,                    // Must concatenate
    // ... other attributes
};

Multi-attribute Global Secondary Index approach (native keys):


// Use existing attributes directly - no concatenation needed
const item = {
    matchId: 'match-001',                                          // Base table PK
    tournamentId: 'WINTER2024',
    region: 'NA-EAST',
    round: 'SEMIFINALS',
    bracket: 'UPPER',
    player1Id: '101',
    matchDate: '2024-01-18',
    // No synthetic keys needed - GSI uses existing attributes directly
    // ... other attributes
};

With multi-attribute keys, you write items once with natural domain attributes. DynamoDB automatically indexes them across multiple GSIs without requiring synthetic concatenated keys.

Base table schema:

Partition key: matchId (1 attribute)

Global Secondary Index Schema (TournamentRegionIndex with multi-attribute keys):

Partition key: tournamentId, region (2 attributes)
Sort key: round, bracket, matchId (3 attributes)

Global Secondary Index Schema (PlayerMatchHistoryIndex with multi-attribute keys):

Partition key: player1Id (1 attribute)
Sort key: matchDate, round (2 attributes)

Base table: TournamentMatches

matchId (PK)	tournamentId	region	round	bracket	player1Id	player2Id	matchDate	winner	score
match-001	WINTER2024	NA-EAST	FINALS	CHAMPIONSHIP	101	103	2024-01-20	101	3-1
match-002	WINTER2024	NA-EAST	SEMIFINALS	UPPER	101	105	2024-01-18	101	3-2
match-003	WINTER2024	NA-EAST	SEMIFINALS	UPPER	103	107	2024-01-18	103	3-0
match-004	WINTER2024	NA-EAST	QUARTERFINALS	UPPER	101	109	2024-01-15	101	3-1
match-005	WINTER2024	NA-WEST	FINALS	CHAMPIONSHIP	102	104	2024-01-20	102	3-2
match-006	WINTER2024	NA-WEST	SEMIFINALS	UPPER	102	106	2024-01-18	102	3-1
match-007	SPRING2024	NA-EAST	QUARTERFINALS	UPPER	101	108	2024-03-15	101	3-0
match-008	SPRING2024	NA-EAST	QUARTERFINALS	LOWER	103	110	2024-03-15	103	3-2

GSI: TournamentRegionIndex (multi-attribute keys)

tournamentId (PK)	region (PK)	round (SK)	bracket (SK)	matchId (SK)	player1Id	player2Id	matchDate	winner	score
WINTER2024	NA-EAST	FINALS	CHAMPIONSHIP	match-001	101	103	2024-01-20	101	3-1
WINTER2024	NA-EAST	QUARTERFINALS	UPPER	match-004	101	109	2024-01-15	101	3-1
WINTER2024	NA-EAST	SEMIFINALS	UPPER	match-002	101	105	2024-01-18	101	3-2
WINTER2024	NA-EAST	SEMIFINALS	UPPER	match-003	103	107	2024-01-18	103	3-0
WINTER2024	NA-WEST	FINALS	CHAMPIONSHIP	match-005	102	104	2024-01-20	102	3-2
WINTER2024	NA-WEST	SEMIFINALS	UPPER	match-006	102	106	2024-01-18	102	3-1
SPRING2024	NA-EAST	QUARTERFINALS	LOWER	match-008	103	110	2024-03-15	103	3-2
SPRING2024	NA-EAST	QUARTERFINALS	UPPER	match-007	101	108	2024-03-15	101	3-0

GSI: PlayerMatchHistoryIndex (multi-attribute keys)

player1Id (PK)	matchDate (SK)	round (SK)	tournamentId	region	bracket	matchId	player2Id	winner	score
101	2024-01-15	QUARTERFINALS	WINTER2024	NA-EAST	UPPER	match-004	109	101	3-1
101	2024-01-18	SEMIFINALS	WINTER2024	NA-EAST	UPPER	match-002	105	101	3-2
101	2024-01-20	FINALS	WINTER2024	NA-EAST	CHAMPIONSHIP	match-001	103	101	3-1
101	2024-03-15	QUARTERFINALS	SPRING2024	NA-EAST	UPPER	match-007	108	101	3-0
102	2024-01-18	SEMIFINALS	WINTER2024	NA-WEST	UPPER	match-006	106	102	3-1
102	2024-01-20	FINALS	WINTER2024	NA-WEST	CHAMPIONSHIP	match-005	104	102	3-2
103	2024-01-18	SEMIFINALS	WINTER2024	NA-EAST	UPPER	match-003	107	103	3-0
103	2024-03-15	QUARTERFINALS	SPRING2024	NA-EAST	LOWER	match-008	110	103	3-2

Prerequisites

Before you begin, make sure you have:

Account and permissions

An active AWS account (create one here if needed)
IAM permissions for DynamoDB operations:
- dynamodb:CreateTable
- dynamodb:DeleteTable
- dynamodb:DescribeTable
- dynamodb:PutItem
- dynamodb:Query
- dynamodb:BatchWriteItem

Note

Security Note: For production use, create a custom IAM policy with only the permissions you need. For this tutorial, you can use the AWS managed policy AmazonDynamoDBFullAccessV2.

Development Environment

Node.js installed on your machine
AWS credentials configured using one of these methods:

Option 1: AWS CLI


aws configure

Option 2: Environment Variables


export AWS_ACCESS_KEY_ID=your_access_key_here
export AWS_SECRET_ACCESS_KEY=your_secret_key_here
export AWS_DEFAULT_REGION=us-east-1

Install Required Packages


npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

Implementation

Step 1: Create table with GSIs using multi-attribute keys

Create a table with a simple base key structure and GSIs that use multi-attribute keys.


import { DynamoDBClient, CreateTableCommand } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({ region: 'us-west-2' });

const response = await client.send(new CreateTableCommand({
    TableName: 'TournamentMatches',
    
    // Base table: Simple partition key
    KeySchema: [
        { AttributeName: 'matchId', KeyType: 'HASH' }              // Simple PK
    ],
    
    AttributeDefinitions: [
        { AttributeName: 'matchId', AttributeType: 'S' },
        { AttributeName: 'tournamentId', AttributeType: 'S' },
        { AttributeName: 'region', AttributeType: 'S' },
        { AttributeName: 'round', AttributeType: 'S' },
        { AttributeName: 'bracket', AttributeType: 'S' },
        { AttributeName: 'player1Id', AttributeType: 'S' },
        { AttributeName: 'matchDate', AttributeType: 'S' }
    ],
    
    // GSIs with multi-attribute keys
    GlobalSecondaryIndexes: [
        {
            IndexName: 'TournamentRegionIndex',
            KeySchema: [
                { AttributeName: 'tournamentId', KeyType: 'HASH' },    // GSI PK attribute 1
                { AttributeName: 'region', KeyType: 'HASH' },          // GSI PK attribute 2
                { AttributeName: 'round', KeyType: 'RANGE' },          // GSI SK attribute 1
                { AttributeName: 'bracket', KeyType: 'RANGE' },        // GSI SK attribute 2
                { AttributeName: 'matchId', KeyType: 'RANGE' }         // GSI SK attribute 3
            ],
            Projection: { ProjectionType: 'ALL' }
        },
        {
            IndexName: 'PlayerMatchHistoryIndex',
            KeySchema: [
                { AttributeName: 'player1Id', KeyType: 'HASH' },       // GSI PK
                { AttributeName: 'matchDate', KeyType: 'RANGE' },      // GSI SK attribute 1
                { AttributeName: 'round', KeyType: 'RANGE' }           // GSI SK attribute 2
            ],
            Projection: { ProjectionType: 'ALL' }
        }
    ],
    
    BillingMode: 'PAY_PER_REQUEST'
}));

console.log("Table with multi-attribute GSI keys created successfully");

Key design decisions:

Base table: The base table uses a simple matchId partition key for direct match lookups, keeping the base table structure straightforward while the GSIs provide the complex query patterns.

TournamentRegionIndex Global Secondary Index: The TournamentRegionIndex Global Secondary Index uses tournamentId + region as a multi-attribute partition key, creating tournament-region isolation where data is distributed by the hash of both attributes combined, enabling efficient queries within a specific tournament-region context. The multi-attribute sort key (round + bracket + matchId) provides hierarchical sorting that supports queries at any level of the hierarchy with natural ordering from general (round) to specific (match ID).

PlayerMatchHistoryIndex Global Secondary Index: The PlayerMatchHistoryIndex Global Secondary Index reorganizes data by player using player1Id as the partition key, enabling cross-tournament queries for a specific player. The multi-attribute sort key (matchDate + round) provides chronological ordering with the ability to filter by date ranges or specific tournament rounds.

Step 2: Insert data with native attributes

Add tournament match data using natural attributes. The GSI will automatically index these attributes without requiring synthetic keys.


import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);

// Tournament match data - no synthetic keys needed for GSIs
const matches = [
    // Winter 2024 Tournament, NA-EAST region
    {
        matchId: 'match-001',
        tournamentId: 'WINTER2024',
        region: 'NA-EAST',
        round: 'FINALS',
        bracket: 'CHAMPIONSHIP',
        player1Id: '101',
        player2Id: '103',
        matchDate: '2024-01-20',
        winner: '101',
        score: '3-1'
    },
    {
        matchId: 'match-002',
        tournamentId: 'WINTER2024',
        region: 'NA-EAST',
        round: 'SEMIFINALS',
        bracket: 'UPPER',
        player1Id: '101',
        player2Id: '105',
        matchDate: '2024-01-18',
        winner: '101',
        score: '3-2'
    },
    {
        matchId: 'match-003',
        tournamentId: 'WINTER2024',
        region: 'NA-EAST',
        round: 'SEMIFINALS',
        bracket: 'UPPER',
        player1Id: '103',
        player2Id: '107',
        matchDate: '2024-01-18',
        winner: '103',
        score: '3-0'
    },
    {
        matchId: 'match-004',
        tournamentId: 'WINTER2024',
        region: 'NA-EAST',
        round: 'QUARTERFINALS',
        bracket: 'UPPER',
        player1Id: '101',
        player2Id: '109',
        matchDate: '2024-01-15',
        winner: '101',
        score: '3-1'
    },
    
    // Winter 2024 Tournament, NA-WEST region
    {
        matchId: 'match-005',
        tournamentId: 'WINTER2024',
        region: 'NA-WEST',
        round: 'FINALS',
        bracket: 'CHAMPIONSHIP',
        player1Id: '102',
        player2Id: '104',
        matchDate: '2024-01-20',
        winner: '102',
        score: '3-2'
    },
    {
        matchId: 'match-006',
        tournamentId: 'WINTER2024',
        region: 'NA-WEST',
        round: 'SEMIFINALS',
        bracket: 'UPPER',
        player1Id: '102',
        player2Id: '106',
        matchDate: '2024-01-18',
        winner: '102',
        score: '3-1'
    },
    
    // Spring 2024 Tournament, NA-EAST region
    {
        matchId: 'match-007',
        tournamentId: 'SPRING2024',
        region: 'NA-EAST',
        round: 'QUARTERFINALS',
        bracket: 'UPPER',
        player1Id: '101',
        player2Id: '108',
        matchDate: '2024-03-15',
        winner: '101',
        score: '3-0'
    },
    {
        matchId: 'match-008',
        tournamentId: 'SPRING2024',
        region: 'NA-EAST',
        round: 'QUARTERFINALS',
        bracket: 'LOWER',
        player1Id: '103',
        player2Id: '110',
        matchDate: '2024-03-15',
        winner: '103',
        score: '3-2'
    }
];

// Insert all matches
for (const match of matches) {
    await docClient.send(new PutCommand({
        TableName: 'TournamentMatches',
        Item: match
    }));
    
    console.log(`Added: ${match.matchId} - ${match.tournamentId}/${match.region} - ${match.round} ${match.bracket}`);
}

console.log(`\nInserted ${matches.length} tournament matches`);
console.log("No synthetic keys created - GSIs use native attributes automatically");

Data structure explained:

Natural attribute usage: Each attribute represents a real tournament concept with no string concatenation or parsing required, providing direct mapping to the domain model.

Automatic Global Secondary Index indexing: The GSIs automatically index items using the existing attributes (tournamentId, region, round, bracket, matchId for TournamentRegionIndex and player1Id, matchDate, round for PlayerMatchHistoryIndex) without requiring synthetic concatenated keys.

No backfilling needed: When you add a new Global Secondary Index with multi-attribute keys to an existing table, DynamoDB automatically indexes all existing items using their natural attributes—no need to update items with synthetic keys.

Step 3: Query TournamentRegionIndex Global Secondary Index with all partition key attributes

This example queries the TournamentRegionIndex Global Secondary Index which has a multi-attribute partition key (tournamentId + region). All partition key attributes must be specified with equality conditions in queries—you cannot query with just tournamentId alone or use inequality operators on partition key attributes.


import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);

// Query GSI: All matches for WINTER2024 tournament in NA-EAST region
const response = await docClient.send(new QueryCommand({
    TableName: 'TournamentMatches',
    IndexName: 'TournamentRegionIndex',
    KeyConditionExpression: 'tournamentId = :tournament AND #region = :region',
    ExpressionAttributeNames: {
        '#region': 'region',  // 'region' is a reserved keyword
        '#tournament': 'tournament'
    },
    ExpressionAttributeValues: {
        ':tournament': 'WINTER2024',
        ':region': 'NA-EAST'
    }
}));

console.log(`Found ${response.Items.length} matches for WINTER2024/NA-EAST:\n`);
response.Items.forEach(match => {
    console.log(`  ${match.round} | ${match.bracket} | ${match.matchId}`);
    console.log(`    Players: ${match.player1Id} vs ${match.player2Id}`);
    console.log(`    Winner: ${match.winner}, Score: ${match.score}\n`);
});

Expected output:

Found 4 matches for WINTER2024/NA-EAST:

  FINALS | CHAMPIONSHIP | match-001
    Players: 101 vs 103
    Winner: 101, Score: 3-1

  QUARTERFINALS | UPPER | match-004
    Players: 101 vs 109
    Winner: 101, Score: 3-1

  SEMIFINALS | UPPER | match-002
    Players: 101 vs 105
    Winner: 101, Score: 3-2

  SEMIFINALS | UPPER | match-003
    Players: 103 vs 107
    Winner: 103, Score: 3-0

Invalid queries:


// Missing region attribute
KeyConditionExpression: 'tournamentId = :tournament'

// Using inequality on partition key attribute
KeyConditionExpression: 'tournamentId = :tournament AND #region > :region'

Performance: Multi-attribute partition keys are hashed together, providing the same O(1) lookup performance as single-attribute keys.

Step 4: Query Global Secondary Index sort keys left-to-right

Sort key attributes must be queried left-to-right in the order they're defined in the Global Secondary Index. This example demonstrates querying the TournamentRegionIndex at different hierarchy levels: filtering by just round, by round + bracket, or by all three sort key attributes. You cannot skip attributes in the middle—for example, you cannot query by round and matchId while skipping bracket.


import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);

// Query 1: Filter by first sort key attribute (round)
console.log("Query 1: All SEMIFINALS matches");
const query1 = await docClient.send(new QueryCommand({
    TableName: 'TournamentMatches',
    IndexName: 'TournamentRegionIndex',
    KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round',
    ExpressionAttributeNames: {
        '#region': 'region'  // 'region' is a reserved keyword
    },
    ExpressionAttributeValues: {
        ':tournament': 'WINTER2024',
        ':region': 'NA-EAST',
        ':round': 'SEMIFINALS'
    }
}));
console.log(`  Found ${query1.Items.length} matches\n`);

// Query 2: Filter by first two sort key attributes (round + bracket)
console.log("Query 2: SEMIFINALS UPPER bracket matches");
const query2 = await docClient.send(new QueryCommand({
    TableName: 'TournamentMatches',
    IndexName: 'TournamentRegionIndex',
    KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND bracket = :bracket',
    ExpressionAttributeNames: {
        '#region': 'region'  // 'region' is a reserved keyword
    },
    ExpressionAttributeValues: {
        ':tournament': 'WINTER2024',
        ':region': 'NA-EAST',
        ':round': 'SEMIFINALS',
        ':bracket': 'UPPER'
    }
}));
console.log(`  Found ${query2.Items.length} matches\n`);

// Query 3: Filter by all three sort key attributes (round + bracket + matchId)
console.log("Query 3: Specific match in SEMIFINALS UPPER bracket");
const query3 = await docClient.send(new QueryCommand({
    TableName: 'TournamentMatches',
    IndexName: 'TournamentRegionIndex',
    KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND bracket = :bracket AND matchId = :matchId',
    ExpressionAttributeNames: {
        '#region': 'region'  // 'region' is a reserved keyword
    },
    ExpressionAttributeValues: {
        ':tournament': 'WINTER2024',
        ':region': 'NA-EAST',
        ':round': 'SEMIFINALS',
        ':bracket': 'UPPER',
        ':matchId': 'match-002'
    }
}));
console.log(`  Found ${query3.Items.length} matches\n`);

// Query 4: INVALID - skipping round
console.log("Query 4: Attempting to skip first sort key attribute (WILL FAIL)");
try {
    const query4 = await docClient.send(new QueryCommand({
        TableName: 'TournamentMatches',
        IndexName: 'TournamentRegionIndex',
        KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND bracket = :bracket',
        ExpressionAttributeNames: {
            '#region': 'region'  // 'region' is a reserved keyword
        },
        ExpressionAttributeValues: {
            ':tournament': 'WINTER2024',
            ':region': 'NA-EAST',
            ':bracket': 'UPPER'
        }
    }));
} catch (error) {
    console.log(`  Error: ${error.message}`);
    console.log(`  Cannot skip sort key attributes - must query left-to-right\n`);
}

Expected output:

Query 1: All SEMIFINALS matches
  Found 2 matches

Query 2: SEMIFINALS UPPER bracket matches
  Found 2 matches

Query 3: Specific match in SEMIFINALS UPPER bracket
  Found 1 matches

Query 4: Attempting to skip first sort key attribute (WILL FAIL)
  Error: Query key condition not supported
  Cannot skip sort key attributes - must query left-to-right

Left-to-right query rules: You must query attributes in order from left to right, without skipping any.

Valid patterns:

First attribute only: round = 'SEMIFINALS'
First two attributes: round = 'SEMIFINALS' AND bracket = 'UPPER'
All three attributes: round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId = 'match-002'

Invalid patterns: