DynamoDB Query API

查询格式

{
   "AttributesToGet": [ "string" ],
   "ConditionalOperator": "string",
   "ConsistentRead": boolean,
   "ExclusiveStartKey": { 
      "string" : { 
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [ 
            "AttributeValue"
         ],
         "M": { 
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   },
   "ExpressionAttributeNames": { 
      "string" : "string" 
   },
   "ExpressionAttributeValues": { 
      "string" : { 
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [ 
            "AttributeValue"
         ],
         "M": { 
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   },
   "FilterExpression": "string",
   "IndexName": "string",
   "KeyConditionExpression": "string",
   "KeyConditions": { 
      "string" : { 
         "AttributeValueList": [ 
            { 
               "B": blob,
               "BOOL": boolean,
               "BS": [ blob ],
               "L": [ 
                  "AttributeValue"
               ],
               "M": { 
                  "string" : "AttributeValue"
               },
               "N": "string",
               "NS": [ "string" ],
               "NULL": boolean,
               "S": "string",
               "SS": [ "string" ]
            }
         ],
         "ComparisonOperator": "string"
      }
   },
   "Limit": number,
   "ProjectionExpression": "string",
   "QueryFilter": { 
      "string" : { 
         "AttributeValueList": [ 
            { 
               "B": blob,
               "BOOL": boolean,
               "BS": [ blob ],
               "L": [ 
                  "AttributeValue"
               ],
               "M": { 
                  "string" : "AttributeValue"
               },
               "N": "string",
               "NS": [ "string" ],
               "NULL": boolean,
               "S": "string",
               "SS": [ "string" ]
            }
         ],
         "ComparisonOperator": "string"
      }
   },
   "ReturnConsumedCapacity": "string",
   "ScanIndexForward": boolean,
   "Select": "string",
   "TableName": "string"
}

表名 TableName

包含所请求项的表的名称。

类型：字符串

长度约束：最小长度为 3。最大长度为 255。

模式：[a-zA-Z0-9_.-]+

必需：是

属性获取 AttributesToGet

这是一个旧参数。请改用。欲了解更多信息 信息，请参阅 Amazon DynamoDB 开发人员中的 AttributesToGet 指南。ProjectionExpression

类型：字符串数组

数组成员：最少 1 个项目。

长度约束：最大长度为 65535。

必需：否

条件运算符 ConditionalOperator

这是一个旧参数。请改用。欲了解更多信息 信息，请参阅 Amazon DynamoDB 开发人员中的条件运算符 指南。FilterExpression

类型：字符串

有效值：AND | OR

必需：否

一致读取 ConsistentRead

确定读取一致性模型：如果设置为 ，则操作 使用强一致性读取;否则，操作使用最终一致性 读。true

全局二级索引不支持强一致性读取。如果您查询 设置为 的全局二级索引 ，你将收到 .ConsistentReadtrueValidationException

类型：布尔值

必需：否

独占启动键 ExclusiveStartKey

此操作将计算的第一项的主键。使用值 在上一个操作中返回。LastEvaluatedKey

的数据类型必须是字符串、数字或二进制。不 允许设置数据类型。ExclusiveStartKey

类型：字符串到属性值对象映射

密钥长度约束：最大长度为 65535。

必需：否

表达式属性名称 ExpressionAttributeNames

表达式中属性名称的一个或多个替换标记。以下 是使用的一些用例：ExpressionAttributeNames

访问名称与 DynamoDB 保留的属性冲突的属性 词。

创建占位符，用于在 表达。

防止属性名称中的特殊字符被误解 在表达式中。

在表达式中使用 # 字符取消引用 属性名称。例如，请考虑以下属性名称：

Percentile

此属性的名称与保留字冲突，因此无法使用 直接在表达式中。（有关保留字的完整列表，请参阅 Amazon DynamoDB 开发人员中的保留字 指南）。要解决此问题，您可以为 指定以下内容：ExpressionAttributeNames

{“#P”:“Percentile”}

然后，您可以在表达式中使用此替换，如以下示例所示：

#P = :val

注意
以 ： 字符开头的标记是表达式属性值，它们是 运行时的实际值。

有关表达式属性名称的更多信息，请参阅在 Amazon DynamoDB 开发人员中指定项目属性 指南。

类型：字符串到字符串映射

值长度约束：最大长度为 65535。

必需：否

表达式属性值 ExpressionAttributeValues

可在表达式中替换的一个或多个值。

在表达式中使用 ：（冒号）字符来 取消引用属性值。例如，假设您要检查是否 “产品状态”属性的值为下列值之一：

Available | Backordered | Discontinued

您首先需要指定为 遵循：ExpressionAttributeValues

{ “:avail”:{“S”:“Available”}, “:back”:{“S”:“Backordered”}, “:disc”:{“S”:“Discontinued”} }

然后，您可以在表达式中使用这些值，如下所示：

ProductStatus IN (:avail, :back, :disc)

有关表达式属性值的更多信息，请参阅在 Amazon DynamoDB 开发人员中指定条件 指南。

类型：字符串到属性值对象映射

必需：否

过滤器表达式 FilterExpression

一个字符串，包含 DynamoDB 在操作之后但在数据返回给您之前应用的条件。不满足条件的物品不予退还。QueryFilterExpression

A 不允许键属性。**您不能定义 基于分区键或排序键的筛选表达式。**FilterExpression

注意
A 在已读取项目后应用 A; 筛选过程不会消耗任何额外的读取容量单位。FilterExpression

有关更多信息，请参阅 Amazon DynamoDB 开发人员中的筛选表达式 指南。

类型：字符串

必需：否

索引名称 IndexName

要查询的索引的名称。此索引可以是任何本地二级索引或全局索引 表上的二级索引。请注意，如果您使用该参数， 您还必须提供IndexNameTableName.

类型：字符串

长度约束：最小长度为 3。最大长度为 255。

模式：[a-zA-Z0-9_.-]+

必需：否

键条件表达式 KeyConditionExpression

指定要由操作检索的项目的键值的条件。Query

该条件必须对单个分区键值执行相等性测试。

条件可以选择对单个排序执行多个比较测试之一 键值。这允许检索具有给定分区的一个项目 键值和排序键值，或具有相同分区键值的多个项目 但排序键值不同。Query

分区键相等性测试是必需的，必须在以下项中指定 格式：

partitionKeyName = :partitionkeyval

如果还想为排序键提供条件，则必须将其与排序键的条件结合使用。下面是一个示例，使用 排序键的 = 比较运算符：AND

partitionKeyName = :partitionkeyval AND sortKeyName = :sortkeyval

排序键条件的有效比较如下所示：

sortKeyName = :sortkeyval- 如果排序键值等于 ，则为 true。:sortkeyval

sortKeyName < :sortkeyval- 如果排序键值小于 。:sortkeyval

sortKeyName <= :sortkeyval- 如果排序键值小于或等于 ，则为 true。:sortkeyval

sortKeyName > :sortkeyval- 如果排序键值大于 。:sortkeyval

sortKeyName >= :sortkeyval- 如果排序键值大于或等于，则为 true 自。:sortkeyval

sortKeyName BETWEEN :sortkeyval1 AND :sortkeyval2- 如果排序键值大于或等于，则为 true 到 ，且小于或等于 。:sortkeyval1:sortkeyval2

begins_with ( sortKeyName， - 如果排序键值以特定操作数开头，则为 true。 （不能将此函数与 Number 类型的排序键一起使用。请注意， 函数名称区分大小写。:sortkeyval)begins_with

使用该参数将标记（如 和）替换为实际值 运行。ExpressionAttributeValues:partitionval:sortval

您可以选择使用该参数来替换 分区键的名称和带有占位符标记的排序键。此选项可能会 如果属性名称与 DynamoDB 保留字冲突，则为必需。例如 以下参数会导致错误，因为 Size 是保留字：ExpressionAttributeNamesKeyConditionExpression

Size = :myval

要解决此问题，请定义一个占位符（例如 ）来表示 属性名称大小。 然后是作为 遵循：#SKeyConditionExpression

#S = :myval

有关保留字的列表，请参阅 Amazon DynamoDB 开发人员指南 中的保留字。

有关 和 的详细信息，请参阅使用 Amazon DynamoDB 中属性名称和值的占位符 开发人员指南。ExpressionAttributeNamesExpressionAttributeValues

类型：字符串 KeyConditions

必需：否

关键条件
这是一个旧参数。请改用。欲了解更多信息 信息，请参阅 Amazon DynamoDB 开发人员中的密钥条件 指南。KeyConditionExpression

类型：字符串到条件对象映射

密钥长度约束：最大长度为 65535。

必需：否

限制 Limit

要评估的最大项目数（不一定是匹配项数） 项）。如果 DynamoDB 在处理 结果，它停止操作并返回到该点为止的匹配值，并且 键入以在后续操作中应用，以便您可以 从上次中断的地方继续。此外，如果处理的数据集大小在之前超过 1 MB DynamoDB 达到此限制，它将停止操作并返回匹配值 到限制，并在后续应用中应用一个键 操作以继续操作。有关更多信息，请参阅 Amazon DynamoDB 开发人员中的查询和扫描 指南。LastEvaluatedKeyLastEvaluatedKey

类型：整数

有效范围：最小值为 1。

必需：否

投影表达式 ProjectionExpression

一个字符串，标识要从表中检索的一个或多个属性。这些 属性可以包括 JSON 文档的标量、集或元素。中的属性 表达式必须用逗号分隔。

如果未指定属性名称，则将返回所有属性。如果其中任何一项 未找到请求的属性，它们不会出现在结果中。

有关更多信息，请参阅 在 Amazon DynamoDB 开发人员中访问项目属性 指南。

类型：字符串

必需：否

查询筛选器 QueryFilter

这是一个旧参数。请改用。欲了解更多信息 信息，请参阅 Amazon DynamoDB 开发人员中的查询筛选条件 指南。FilterExpression

类型：字符串到条件对象映射

密钥长度约束：最大长度为 65535。

必需：否

返回消耗容量 ReturnConsumedCapacity

确定有关预配吞吐量或按需吞吐量的详细级别 响应中返回的消耗量：

INDEXES- 响应包括操作的聚合，以及每个表和二级索引的聚合 访问。ConsumedCapacityConsumedCapacity

请注意，某些操作（如 和 ）根本不访问任何索引。在这些情况下， 指定将仅返回表的信息。GetItemBatchGetItemINDEXESConsumedCapacity

TOTAL- 响应仅包括操作的聚合。ConsumedCapacity

NONE- 不包含详细信息 响应。ConsumedCapacity

类型：字符串

有效值：INDEXES | TOTAL | NONE

必需：否

扫描索引转发 ScanIndexForward

指定索引遍历的顺序：如果（默认），则遍历 按升序执行;如果 ，则遍历在 降序。truefalse

具有相同分区键值的项目按排序键的排序顺序存储。如果 排序键数据类型为数字，结果按数字顺序存储。对于字符串类型， 结果按 UTF-8 字节的顺序存储。对于二进制类型，DynamoDB 处理每个 二进制数据的字节为无符号。

如果为 ，则 DynamoDB 返回以下结果： 它们的存储顺序（按排序键值）。这是默认行为。如果是，则 DynamoDB 读取 按排序键值反转顺序，然后将结果返回到客户端。ScanIndexForwardtrueScanIndexForwardfalse

类型：布尔值

必需：否

选择 Select

要在结果中返回的属性。您可以检索所有项目属性， 特定项目属性、匹配项目计数，或者在索引的情况下，一些 或投影到索引中的所有属性。

ALL_ATTRIBUTES- 返回来自 指定的表或索引。如果查询本地二级索引，则对于每个 匹配索引中的项目，DynamoDB 从父级获取整个项目 桌子。如果索引配置为投影所有项目属性，则所有 数据可以从本地二级索引获取，无需提取 必填。

ALL_PROJECTED_ATTRIBUTES- 仅在查询索引时允许。 检索已投影到索引中的所有属性。如果索引 配置为投影所有属性，此返回值等效于 指定。ALL_ATTRIBUTES

COUNT- 返回匹配项的数量，而不是 匹配项目本身。请注意，这使用相同数量的读取容量单位 作为获取项目，并受制于相同的项目大小计算。

SPECIFIC_ATTRIBUTES- 仅返回 中列出的属性。此返回值等效于 指定而不指定任何值。ProjectionExpressionProjectionExpressionSelect

如果查询或扫描本地二级索引并仅请求以下属性： 投影到该索引中，操作将仅读取索引，而不读取索引 表。如果任何请求的属性未投影到本地 二级索引，DynamoDB 从父级获取这些属性中的每一个 桌子。这种额外的提取会产生额外的吞吐量成本和延迟。

如果查询或扫描全局二级索引，则只能请求属性 被预测到索引中。全局二级索引查询无法提取 父表中的属性。

如果既未指定也不指定， DynamoDB 默认为访问表和访问索引时。您不能同时使用两者和 请求，除非 的值为 。 （此用法等效于指定没有任何 的值。SelectProjectionExpressionALL_ATTRIBUTESALL_PROJECTED_ATTRIBUTESSelectProjectionExpressionSelectSPECIFIC_ATTRIBUTESProjectionExpressionSelect

注意
如果使用参数，则 的值只能为 。任何其他 的值将返回错误。ProjectionExpressionSelectSPECIFIC_ATTRIBUTESSelect

类型：字符串

有效值：ALL_ATTRIBUTES | ALL_PROJECTED_ATTRIBUTES | SPECIFIC_ATTRIBUTES | COUNT

必需：否