DynamoDB: Query Global Secondary Index in Nodejs (Guide w/ Code Examples)

Use QueryCommand with IndexName and the GSI partition-key attribute. This example assumes CustomerIndex uses customerId as its partition key.

Install @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb, use an ES module on a supported Node.js runtime, and configure an AWS Region and credentials. The examples use an existing Orders table with String keys pk and sk unless an index or timestamp key is described.

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

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));

let lastKey;
do {
  const page = await ddb.send(new QueryCommand({
    TableName: "Orders",
    IndexName: "CustomerIndex",
    KeyConditionExpression: "#customer = :customer",
    ExpressionAttributeNames: { "#customer": "customerId" },
    ExpressionAttributeValues: { ":customer": "CUSTOMER#123" },
    ExclusiveStartKey: lastKey,
  }));
  for (const item of page.Items ?? []) console.log(item);
  lastKey = page.LastEvaluatedKey;
} while (lastKey && Object.keys(lastKey).length > 0);

GSIs support eventually consistent reads only. Results include only attributes projected into the index; a GetCommand can retrieve the base-table item by its full key.

Reference: AWS Query API. For related access patterns, see DynamoDB query examples.