# 扫描所有kv #### 功能介绍 指定表，扫描表下所有kv；允许指定过滤条件。 #### URI POST /v1/scan-kv 表1Query参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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 | 采样段区间列表。 | 表3condition_expression | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | single_field_expression | 否 | [single_field_expression] object | 单字段条件。 | | multi_field_expression | 否 | [multi_field_expression] object | 多字段条件，多个相同优先级的单字段条件。 | | composed_expression | 否 | [composed_expression] object | 组合条件, 逐层同级的子表达式嵌套。 | 表4composed_expression | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | logic | 否 | String | 逻辑关系，取值如"$and", "$or", "$nor"。 | | expressions | 是 | Array of [expression] objects | 多个相同优先级且相同逻辑的单字段或多字段条件。 | 表5expression | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | single_field_expression | 否 | [single_field_expression] object | 单字段条件。 | | multi_field_expression | 否 | [multi_field_expression] object | 多字段条件，多个相同优先级的单字段条件。 | | composed_expression | 否 | [composed_expression] object | 组合条件, 逐层同级的子表达式嵌套。 | 表6single_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"。 | 表7multi_field_expression | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | logic | 否 | String | 多字段条件，多个相同优先级的单字段条件。 | | expressions | 是 | Array of [single_field_expression] objects | 多个相同逻辑操作的单字段条件。 | 表8returned_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 | 采样段区间列表。 | 表10returned_kv_item | 参数 | 参数类型 | 描述 | |:---|:---|:---| | kv_doc | Document | 对kv_doc有效。 | 表11returned_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" } } ] } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 表示扫描所有kv请求成功 | | 400 | Bad Request | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-kvs/ErrorCode.html)。