文档首页/ 键值存储服务 KVS/ API参考/ API/ KV接口/ 扫描分区键内kv
更新时间：2024-12-09 GMT+08:00
查看PDF
分享

扫描分区键内kv

功能介绍

指定表及分区键，携带条件查询kv；允许指定过滤条件。

URI

POST /v1/scan-skey-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, 63]

  • 取值字符限制：[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逻辑。
表3 condition_expression

参数

是否必选

参数类型

描述

single_field_expression

否

single_field_expression object

单字段条件。

multi_field_expression

否

multi_field_expression object

多字段条件，多个相同优先级的单字段条件。

composed_expression

否

composed_expression object

组合条件, 逐层同级的子表达式嵌套。
表4 multi_field_expression

参数

是否必选

参数类型

描述

logic

否

String

多字段条件，多个相同优先级的单字段条件。

expressions

是

Array of single_field_expression objects

多个相同逻辑操作的单字段条件。
表5 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"。
表6 composed_expression

参数

是否必选

参数类型

描述

logic

否

String

逻辑关系，取值如"$and", "$or", "$nor"。

expressions

是

Array of expression objects

多个相同优先级且相同逻辑的单字段或多字段条件。
表7 expression

参数

是否必选

参数类型

描述

single_field_expression

否

single_field_expression object

单字段条件。

multi_field_expression

否

single_field_expression object

多字段条件，多个相同优先级的单字段条件。

composed_expression

否

composed_expression object

组合条件, 逐层同级的子表达式嵌套。

响应参数

状态码： 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字段相同。
表9 returned_kv_item

参数

参数类型

描述

kv_doc

Document

对kv_doc有效。

请求示例

扫描分区键值等于user1的所有kv

POST https://{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

错误码

请参见错误码。

父主题： KV接口

相关文档