使用 AWS CLI 查詢 DynamoDB GSI

查詢 global secondary index 就是一個平常的 aws dynamodb query 再加一個旗標：--index-name。key condition 接著鎖定的是索引的 key，而非表格的 — 這裡 AlbumTitle-index 讓我們能依專輯抓取歌曲，這是 base table（Artist + SongTitle）不做 scan 就無法服務的存取模式。

Code

aws dynamodb query \
  --table-name 'Music' \
  --index-name 'AlbumTitle-index' \
  --key-condition-expression '#hashKey = :hashKeyValue' \
  --expression-attribute-names '{"#hashKey":"AlbumTitle"}' \
  --expression-attribute-values '{":hashKeyValue":{"S":"Danzon"}}'

輸出是以 DynamoDB JSON 表示的符合項目：

{
    "Items": [
        {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}, ...}
    ],
    "Count": 2,
    "ScannedCount": 2
}

說明

--index-name — 指名要查詢的 GSI（--table-name 仍為必需）。--key-condition-expression 使用索引的 partition（與選用的 sort）key — 這裡是 AlbumTitle — 運算子與表格查詢相同。
僅最終一致 — GSI 從 base table 非同步複製。對 GSI 查詢加上 --consistent-read 並不會升級它；它會以 ValidationException 失敗。（local secondary index 確實支援強一致。）
你只會拿到已投影的屬性 — GSI 查詢回傳索引所投影的內容（ALL、KEYS_ONLY，或 INCLUDE 列出的屬性），且無法從 base table 取回其餘部分。
GSI 中 key 並非唯一 — 許多項目可共用同一個索引 key，而缺少索引 key 屬性的項目就是不會出現（也就是 sparse-index 模式）。
分頁是自動的 — CLI 在幕後追蹤服務的分頁 token 並印出合併後的結果。以 --max-items 限制輸出（會出現一個 NextToken；以 --starting-token 續讀），或以 --no-paginate 進行單一服務呼叫。

改用視覺化操作

DynamoDB Expression Builder 會為索引查詢建立 key condition 與 name/value map，並交給你一個可直接執行的 CLI 指令。

想在表單中瀏覽表格的索引並執行 GSI 查詢 — 分頁格線、複製為 CLI — 下載 DynoTable。

References

最後驗證於 2026-07-13，對照上方連結的 AWS 官方文件。

使用 AWS CLI 查詢 DynamoDB GSI

Code

說明

改用視覺化操作

相關範例

References

以視覺化方式建構此請求