更新时间：2026-01-06 GMT+08:00

查询表

功能介绍

指定仓查询表属性，如容量，规模，配额。

URI

POST /v1/describe-table

表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-zA-Z0-9_-]+

响应参数

状态码：200

表3 响应Body参数
参数	参数类型	描述
table_name	String	表名。长度：[3, 52] 取值字符限制：[a-z0-9_-]+
primary_key_schema	primary_key_schema object	主键模板, 最多1个，必须指定主键schema。
local_secondary_index_schema	Array of local_secondary_index objects	本地二级索引模板，可以多个。
global_secondary_index_schema	Array of global_secondary_index objects	全局二级索引模板。
run_time_info	run_time_info object	运行信息。

表4 primary_key_schema
参数	参数类型	描述
shard_key_fields	Array of field objects	分区键字段名数组，顺序组合。
shard_mode	String	分区模式。
sort_key_fields	Array of field objects	排序键字段名数组，顺序组合。

表5 local_secondary_index
参数	参数类型	描述
index_name	String	二级索引名称，表内唯一。
sort_key_fields	Array of field objects	排序键字段名数组，顺序组合。
abstract_fields	Array of strings	摘要字段名数组。

表6 global_secondary_index
参数	参数类型	描述
index_name	String	二级索引名称，表内唯一。
shard_key_fields	Array of field objects	分区键字段名数组，顺序组合。
shard_mode	String	分区模式。
sort_key_fields	Array of field objects	排序键字段名数组，顺序组合。
abstract_fields	Array of strings	摘要字段名数组。
provisioned_throughput	provisioned_throughput object	预置吞吐读写请求单元数，在bill_mode="provisioned"有效。

表7 field
参数	参数类型	描述
name	String	字段名。
order	Boolean	bool值预留无意义。

表8 provisioned_throughput
参数	参数类型	描述
rcu	Long	预置表级读请求单元数。
wcu	Long	预置表级写请求单元数。

表9 run_time_info
参数	参数类型	描述
table_info	table_info object	表信息。
local_secondary_index_infos	Array of secondary_index_info objects	索引状态。
global_secondary_index_infos	Array of global_secondary_index_info objects	全局二级索引运行态。

**表10** table_info
参数	参数类型	描述
table_status	String	表状态。 creating（表示该表正在创建中） active（表示该表处于正常运行状态） deleting（表示该表处于删除中状态，或者已经被删除）

**表11** secondary_index_info
参数	参数类型	描述
index_name	String	索引状态。长度：[1, 255] 取值字符限制：[a-z0-9_-]+
index_status	String	索引状态。 creating（表示该索引正在创建中） active（表示该索引处于正常运行状态） deleting（表示该索引处于删除中状态，或者已经被删除）

**表12** global_secondary_index_info
参数	参数类型	描述
index_name	String	二级索引名称。
index_status	String	二级索引名称。 creating（表示该全局二级索引正在创建中） active（表示该全局二级索引处于正常运行状态） deleting（表示该全局二级索引处于删除中状态，或者已经被删除）

状态码：400

**表13** 响应Body参数
参数	参数类型	描述
error_code	String	请求返回的错误码。
error_msg	String	请求返回的错误信息。

请求示例

在test-store仓内，查询表名为test-table的表信息

POST https://test-store.{endpoint}/v1/describe-table

{
  "table_name" : "test-table"
}

响应示例

状态码：200

表示查询表请求成功

{
  "table_name" : "test-table-1",
  "primary_key_schema" : {
    "shard_key_fields" : [ {
      "name" : "owner",
      "order" : true
    } ],
    "sort_key_fields" : [ {
      "name" : "filename",
      "order" : true
    } ]
  },
  "runtime_info" : {
    "table_info" : {
      "table_status" : "ACTIVE"
    }
  }
}