DynamoDB GSI does not project the requested attribute

TL;DR — 你查詢了一個 Global Secondary Index 並（透過 ProjectionExpression 或 Select=ALL_ATTRIBUTES）要求了該索引未 project 的屬性。GSI 只回傳它自己的鍵屬性、基礎表格的鍵屬性，以及你在其 projection 中列出的內容 — 別無其他。要嘛將請求縮小到已 project 的屬性、將該屬性加入 GSI 的 projection，要嘛依 primary key 查詢基礎表格。

這是什麼意思

ValidationException: One or more parameter values were invalid: Global secondary
index <index_name> does not project <attribute_name>

# or, with Select=ALL_ATTRIBUTES on a KEYS_ONLY / INCLUDE index:
ValidationException: Select type ALL_ATTRIBUTES is not supported for global
secondary index <index_name> because its projection type is not ALL

# what the engine actually returns, reproduced against DynamoDB Local:
ValidationException: One or more parameter values were invalid: Global secondary index gsi1 does not project [unprojected]

與 Local Secondary Index（它可以額外成本從基礎項目擷取未 project 的屬性）不同，GSI 是一個自足的副本。它實體上只儲存其 projection 中的屬性 — AWS 自己的文件很直白：「global secondary index 查詢無法從基礎表格擷取屬性。」要求 GSI 查詢那個集合之外的任何東西都無法滿足，因此 DynamoDB 拒絕該請求（ValidationException，HTTP 400 — 不可重試），而非默默回傳部分資料。

為什麼會發生

• ProjectionType: KEYS_ONLY 索引被查詢取得非鍵屬性。
• ProjectionType: INCLUDE 索引被查詢取得不在 NonKeyAttributes 列表中的屬性。
• 對非 ProjectionType: ALL 的 GSI 使用 Select: ALL_ATTRIBUTES。
• 假設 LSI 行為 — 期望 GSI 從基礎表格擷取未 project 的屬性（只有 LSI 會這樣）。
• projection 隨存取模式演變而偏離了查詢的需求。

如何修正

1. 只要求已 project 的屬性 — 將 ProjectionExpression 限制在 GSI 的鍵 + 其已 project 集合，或移除 Select: ALL_ATTRIBUTES。
2. 將屬性加入 GSI projection — 對新屬性，以 ProjectionType: INCLUDE（列出它）或 ALL 建立/替換 GSI。既有 GSI 的 projection 無法就地編輯；你新增一個 GSI 或重新建立它。
3. 從基礎表格擷取 — 使用 GSI _確實_回傳的鍵，對基礎表格做 GetItem/BatchGetItem 以取得完整項目。
4. 若你經常需要索引的每個屬性，使用 ProjectionType: ALL（接受額外的儲存/寫入成本）。

想在查詢前看出 GSI 實際攜帶哪些屬性？DynoTable 桌面應用程式顯示每個索引的 projection，讓你只要求那裡有的 — 沒有 does not project 的意外。

相關錯誤

• Index not found — 索引名稱本身錯誤或仍在建立中。
• Query condition missed key schema element — GSI key condition 不完整。
• 程式碼範例：Query a GSI in Node.js — 可對照的可運作 GSI 查詢。
• 學習：Index projections · GSI vs LSI · Index

參考資料

• Using Global Secondary Indexes in DynamoDB — Amazon DynamoDB Developer Guide
• Managing Global Secondary Indexes in DynamoDB — Amazon DynamoDB Developer Guide
• Query — Amazon DynamoDB API Reference
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

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