# 扫描分区键内kv
#### 功能介绍
指定表及分区键，携带条件查询kv；允许指定过滤条件。
#### URI
POST /v1/scan-skey-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时指定的索引名。                                                                               |
| limit             | 否    | Long                                                                     | 返回的文档个数，最大100个。 说明： 默认100个文档。                                                                      |
| shard_key         | 是    | Document                                                                 | 要遍历的指定分区键下的kv。                                                                                     |
| start_sort_key    | 否    | Document                                                                 | 起始排序键值，默认空表示从头遍历，左闭。 说明： 分页返回时，该值使用上次响应返回的cursor_sort_key                                          |
| end_sort_key      | 否    | Document                                                                 | 终止主键或索引键值，默认空表示直到最后，右开。                                                                            |
| filter_expression | 否    | [condition_expression] object | 过滤表达式。 说明： - 允许主键字段作为条件。 - 在满足shard_key和start_sort_key和end_sortkey的范围内，执行filter逻辑。 - 长度：\[8,4096\] |
   
 表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 | 多个相同逻辑操作的单字段条件。      |
   
#### 响应参数
**状态码：200**
表8响应Body参数 
| 参数                | 参数类型                                                                        | 描述                                                        |
|:---|:---|:---|
| returned_count    | Long                                                                        | 返回的文档数量，为0不表示结束。 - 如果filtered_count超过500仍无匹配，则返回0。 - 长度：4 |
| filtered_count    | Integer                                                                     | 被过滤掉的文档数量。 - 长度：4                                         |
| cursor_sort_key   | Document                                                                    | 下次请求时的start_key。 说明： 该值为空时，表示指定范围或者指定filter条件所有kv已经返回。    |
| returned_kv_items | Array of [returned_kv_item] objects | 返回的kv列表，与scan-kv接口的returned_kv_item字段相同。                  |
   
 表9returned_kv_item 
| 参数     | 参数类型     | 描述         |
|:---|:---|:---|
| kv_doc | Document | 对kv_doc有效。 |
   
**状态码：400**
Bad Request
#### 请求示例
扫描分区键值等于user1的所有kv，表名为test-table-1，仓名为test-store。
```
POST https://test-store.{endpoint}/v1/scan-skey-kv
{
  "table_name" : "test-table-1",
  "shard_key" : {
    "owner" : "user-1"
  }
}
```
#### 响应示例
**状态码：200**
表示扫描分区键内kv请求成功
```
{
  "returned_count" : 1,
  "filtered_count" : 0,
  "kv_array" : [ {
    "returned_kv_items" : {
      "kv_doc" : {
        "owner" : "user-1",
        "filename" : "test-file-1",
        "otherkey" : "otherValue"
      }
    }
  } ]
}
```
#### 状态码
| 状态码 | 描述             |
|:---|:---|
| 200 | 表示扫描分区键内kv请求成功 |
| 400 | Bad Request    |
   
#### 错误码
请参见[错误码](https://support.huaweicloud.com/api-kvs/ErrorCode.html)。