更新时间：2025-05-20 GMT+08:00

创建表

功能介绍

在指定仓内创建表，表名在仓内唯一；创建表时，指定主键模板及本地二级索引模板及全局二级索引模板。创建表时，如果仓不存在，将会自动创建仓。

URI

POST /v1/create-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	表名，仓内唯一。
bill_mode	否	String	表计费模式，可为"provisioned"或"on_demand" 预置模式：provisioned 按需模式：on_demand
provisioned_throughput	否	provisioned_throughput object	预置吞吐读写请求单元数，在bill_mode="provisioned"有效。
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	全局二级索引模板。
pre_split_key_options	否	pre_split_key_options object	按照设定的分裂键值或者键值前缀进行预分裂。说明： range分区时该参数有效，且只作用于主表，其他场景无效。

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

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

表5 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"有效。

表6 field
参数	是否必选	参数类型	描述
name	是	String	字段名。
order	否	Boolean	bool值预留无意义。

表7 provisioned_throughput
参数	是否必选	参数类型	描述
rcu	是	Long	预置表级读请求单元数。
wcu	是	Long	预置表级写请求单元数。

表8 pre_split_key_options
参数	是否必选	参数类型	描述
range_split_points	否	Array of strings	在range分区模式有效，最大10个。

响应参数

状态码：200

表9 响应Body参数
参数	参数类型	描述
table_name	String	表名，仓内唯一。
bill_mode	String	计费模式，可为"provisioned"或"on_demand"。
provisioned_throughput	provisioned_throughput object	预置吞吐读写请求单元数，在bill_mode="provisioned"有效。
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	全局二级索引模板。
pre_split_key_options	pre_split_key_options object	按照设定的分裂键值或者键值前缀进行预分裂。说明： range分区时该参数有效，且只作用于主表，其他场景无效。

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

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

**表12** 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"有效。

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

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

**表15** pre_split_key_options
参数	参数类型	描述
range_split_points	Array of strings	在range分区模式有效，最大10个。

状态码：400

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

状态码：409

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

请求示例

在test-store仓内，创建表，表名为test-table，分区键字段名为owner，排序键字段名称为filename

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

{
  "table_name" : "test-table",
  "primary_key_schema" : {
    "shard_key_fields" : [ {
      "name" : "owner",
      "order" : true
    } ],
    "sort_key_fields" : [ {
      "name" : "filename",
      "order" : true
    } ]
  }
}

响应示例

状态码：200

表示创建表成功。

{
  "table_name" : "test-table",
  "primary_key_schema" : {
    "shard_key_fields" : [ {
      "name" : "owner",
      "order" : true
    } ],
    "sort_key_fields" : [ {
      "name" : "filename",
      "order" : true
    } ]
  }
}