Node.js(AWS SDK v3)에서 DynamoDB GSI 쿼리하기

글로벌 보조 인덱스 쿼리는 일반 Query에 매개변수 하나(IndexName)를 더한 것입니다. 그러면 키 조건은 테이블이 아닌 인덱스의 키를 대상으로 합니다 — 여기서 AlbumTitle-index는 앨범별로 노래를 가져오게 해주는데, 이는 기본 테이블(Artist + SongTitle)이 스캔 없이는 처리할 수 없는 접근 패턴입니다.

Code

import {DynamoDBClient, QueryCommand} from '@aws-sdk/client-dynamodb';

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

const items = [];
let lastEvaluatedKey;

do {
  const response = await client.send(
    new QueryCommand({
      TableName: 'Music',
      IndexName: 'AlbumTitle-index',
      KeyConditionExpression: '#hashKey = :hashKeyValue',
      ExpressionAttributeNames: {
        '#hashKey': 'AlbumTitle'
      },
      ExpressionAttributeValues: {
        ':hashKeyValue': {S: 'Danzon'}
      },
      ExclusiveStartKey: lastEvaluatedKey
    })
  );

  items.push(...(response.Items ?? []));
  lastEvaluatedKey = response.LastEvaluatedKey;
} while (lastEvaluatedKey);

console.log(`Found ${items.length} songs on the album`);

Explanation

• IndexName — 쿼리할 GSI를 지정합니다(TableName은 여전히 필수). KeyConditionExpression은 인덱스의 파티션(그리고 선택적 정렬) 키 — 여기서는 AlbumTitle — 를 테이블 쿼리와 동일한 연산자로 사용합니다.
• 최종적 일관성만 지원 — GSI는 기본 테이블에서 비동기적으로 복제됩니다. GSI 쿼리에서 ConsistentRead: true를 전달해도 승격되지 않으며 ValidationException으로 실패합니다. (로컬 보조 인덱스는 강력한 일관성을 지원합니다.)
• 투영된 속성만 반환 — GSI 쿼리는 인덱스가 투영한 것(ALL, KEYS_ONLY, 또는 INCLUDE로 나열된 속성)을 반환하며, 나머지를 기본 테이블에서 가져올 수 없습니다. 투영되지 않은 속성이 필요한가요? 테이블 키에 대해 GetItem으로 후속 조회하거나 투영을 넓히세요.
• GSI에서는 키가 고유하지 않음 — 여러 항목이 동일한 인덱스 키를 공유할 수 있으며, 인덱스 키 속성이 없는 항목은 단순히 나타나지 않습니다(이것이 희소 인덱스 패턴입니다).
• 페이지네이션 — 테이블 쿼리와 동일합니다: 페이지당 최대 1 MB, undefined가 될 때까지 LastEvaluatedKey → ExclusiveStartKey를 반복하세요.

Do it visually

DynamoDB Expression Builder는 인덱스 쿼리를 위한 키 조건 + 이름/값 맵을 만들고 코드를 복사해 줍니다.

테이블의 인덱스를 탐색하고 폼에서 GSI 쿼리를 실행하려면 — 페이지네이션 그리드, 생성된 SDK v3 코드 복사 — DynoTable을 다운로드하세요.

Related examples

• DynamoDB Query a GSI in Python — boto3를 사용한 동일한 인덱스 쿼리.
• DynamoDB Query a GSI with the AWS CLI — 셸에서 실행하는 동일한 인덱스 쿼리.
• DynamoDB Query in Node.js — 기본 테이블 쿼리하기.
• GSI vs. LSI — 접근 패턴에 어떤 인덱스 유형이 맞는지.
• Why GSIs are eventually consistent — 복제 지연 설명.
• "The table does not have the specified index" — 인덱스 이름이 일치하지 않는 경우(GSI 이름은 대소문자를 구분).
• "Consistent reads are not supported on global secondary indexes" — GSI에서 일관성 읽기 플래그가 실패하는 이유.

References

• Query — Amazon DynamoDB API Reference
• Using Global Secondary Indexes in DynamoDB — Amazon DynamoDB Developer Guide
• Paginating table query results — Amazon DynamoDB Developer Guide

Last verified 2026-07-13 against the official AWS documentation linked above.