更新时间：2025-05-20 GMT+08:00

扫描所有kv

功能介绍

指定表，扫描表下所有kv；允许指定过滤条件。

URI

POST /v1/scan-kv

表1 Query参数
参数	是否必选	参数类型	描述
store_name	否	String	仓名，全域唯一，不同租户的仓名不能相同。格式：${prefix}-${region-code}-${account-id}，其中prefix为自定义前缀，region-code为kvs集群所在的区域代码，account-id为用户的账户id 取值字符限制：[a-z0-9-]+ 长度：[16,52] 说明： "-"不能出现在名字头部或尾部

请求参数

表2 请求Body参数
参数	是否必选	参数类型	描述
table_name	是	String	表名，仓内唯一。长度：[3, 52] 取值字符限制：[a-z0-9_-]+
hint_index_name	否	String	create_table时指定的索引名，默认空表示主索引。长度：[3, 63] 取值字符限制：[a-z0-9_-]+
limit	否	Integer	返回的文档个数，最大100个。说明：默认100个文档。
start_key	否	Document	起始主键或索引键值。默认空，表示从头遍历，左闭。说明：分页返回时，该值使用上次响应返回的cursor_key。
end_key	否	Document	终止主键或索引键值。默认空，表示直到最后，右开。
filter_expression	否	condition_expression object	过滤表达式。说明：允许键字段作为条件。在满足start_key和endkey的范围内，执行filter逻辑。长度：[8,4096]
sample_segments_count	否	Integer	对表进行采样，尽最大努力保证返回的段列表均分整张表。举例：sample_segments_count=4，返回的段列表[MinKey, KV1)、[KV1,KV2)、[KV2,KV3)和[KV3,MaxKey)。用户可以使用scan-kv对这四个分区执行并发扫描，提高遍历效率。范围: [1, 10000]。默认值：不执行采样。 sample_segments_count仅能和table_name、start_key和end_key字段配合使用。Range分区模式下支持全表采样和范围采样；Hash分区模式仅支持全表扫描。仅支持对Primary key进行采样，不支持本地/全局二级索引。返回的段列表仅包含主键，不包含键值；且段列表是编码后的数据，不可修改。
return_count_only	否	Boolean	是否只返回满足条件的KV个数； true:响应rsp只返回"returned_count"、"filtered_count"和"cursor_key"（如果有"cursor_key"）。 false:scan-kv的标准响应体定义返回消息。
returned_segment_items	否	Array of returned_segment_item objects	采样段区间列表。

表3 condition_expression
参数	是否必选	参数类型	描述
single_field_expression	否	single_field_expression object	单字段条件。
multi_field_expression	否	multi_field_expression object	多字段条件，多个相同优先级的单字段条件。
composed_expression	否	composed_expression object	组合条件, 逐层同级的子表达式嵌套。

表4 composed_expression
参数	是否必选	参数类型	描述
logic	否	String	逻辑关系，取值如"$and", "$or", "$nor"。
expressions	是	Array of expression objects	多个相同优先级且相同逻辑的单字段或多字段条件。

表5 expression
参数	是否必选	参数类型	描述
single_field_expression	否	single_field_expression object	单字段条件。
multi_field_expression	否	multi_field_expression object	多字段条件，多个相同优先级的单字段条件。
composed_expression	否	composed_expression object	组合条件, 逐层同级的子表达式嵌套。

表6 single_field_expression
参数	是否必选	参数类型	描述
field	是	String	条件字段。
func	是	String	条件函数，取值如"$gt", $lt","$gte", $lte" "$eq", "$ne", "$prefix", "$exists"。
value	否	Document	value和value_array二选一。 value条件值，适用于除"$in", "$nin"外的func。字段名无意义，可以传空，也可以传字段名。 $exists值为true/false。说明： $prefix操作只适用于string和binary类型。
value_array	否	Array of strings	"value"和"value_array"二选一。 "value_array" 条件值列表, 值用于"$in", "$nin"。

表7 multi_field_expression
参数	是否必选	参数类型	描述
logic	否	String	多字段条件，多个相同优先级的单字段条件。
expressions	是	Array of single_field_expression objects	多个相同逻辑操作的单字段条件。

表8 returned_segment_item
参数	是否必选	参数类型	描述
segment_min_key	否	Document	采样段区间起始值。
segment_max_key	否	Document	采样段区间终止值。

响应参数

状态码：200

表9 响应Body参数
参数	参数类型	描述
returned_count	Long	返回的文档数量，为0不表示结束。说明：如果filtered_count超过500仍无匹配，则返回0。
filtered_count	Integer	被过滤掉的文档数量。
cursor_key	Document	下次请求时的start_key，该值为空时，表示指定范围或者指定filter条件所有kv已经返回。
returned_kv_items	Array of returned_kv_item objects	返回的kv列表。
returned_segment_items	Array of returned_segment_item objects	采样段区间列表。

**表10** returned_kv_item
参数	参数类型	描述
kv_doc	Document	对kv_doc有效。

**表11** returned_segment_item
参数	参数类型	描述
segment_min_key	Document	采样段区间起始值。
segment_max_key	Document	采样段区间终止值。

状态码：400

Bad Request

请求示例

扫描所有kv，扫描条件为分区键的值为user2，表名为test-table-1，仓名为test-store。

POST https://test-store.{endpoint}/v1/scan-kv

{
  "table_name" : "test-table-1",
  "filter_expression" : {
    "single_field_expr" : {
      "field" : "owner",
      "func" : "$eq",
      "value" : {
        "value" : "user-2"
      }
    }
  }
}

响应示例

状态码：200

表示扫描所有kv请求成功

{
  "returned_count" : 1,
  "filtered_count" : 0,
  "returned_kv_items" : [ {
    "kv_doc" : {
      "owner" : "user-2",
      "filename" : "test-file-2",
      "otherKey" : "otherValue"
    }
  } ]
}