更新时间:2024-09-26 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, 63]

  • 取值字符限制:[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逻辑。

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进行采样,不支持本地/全局二级索引。

  • 返回的段列表仅包含主键,不包含键值;且段列表是编码后的数据 ,不可修改。

表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

Integer

返回的文档数量,为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列表。

表9 returned_kv_item

参数

参数类型

描述

kv_doc

Document

对kv_doc有效。

请求示例

扫描所有kv,扫描条件为分区键的值为user2

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

错误码

请参见错误码

相关文档