使用 CreateTable 接口创建数据表时,需要指定数据表的结构信息和配置信息,高性能型实例中的数据表还可以根据需要设置预留读/写吞吐量。创建数据表时支持创建一个或者多个索引。
注意事项
创建数据表后需要几秒钟进行加载,在此期间对该数据表的读写数据操作均会失败。请等待数据表加载完毕后再进行数据操作。
创建数据表时必须指定数据表的主键。主键包含 1~4 个主键列,每一个主键列都包括名称和类型。
如果系统设计中存在为特定目标生成唯一标识的场景,例如电商网站的商品 ID、大型网站的用户 ID、论坛帖子的 ID、聊天工具的消息 ID 等,您可以通过在创建数据表时配置主键列自增实现。具体操作,请参见主键列自增。
前提条件
已通过控制台创建实例。具体操作,请参见创建实例。
已初始化 Client。具体操作,请参见初始化 OTSClient。
接口
/**
* 创建数据表,并设置主键的个数、名称、顺序和类型,以及预留读写吞吐量、TTL和stream选项。
* @api
* @param [] $request 请求参数。
* @return [] 返回为空。CreateTable成功时不返回任何信息,此处返回一个空的array,与其他API保持一致。
* @throws OTSClientException 当参数检查出错或服务端返回校验出错时抛出异常。
* @throws OTSServerException 当OTS服务端返回错误时抛出异常。
*/
public function createTable(array $request);
请求参数
参数 | 是否必选 | 说明 |
table_meta | 是 | 数据表的结构信息,包括如下内容: 说明 属性列不需要定义。表格存储每行的数据列都可以不同,属性列的列名在写入时指定。
|
table_options | 否 | 数据表的配置信息。更多信息,请参见数据版本和生命周期。 配置信息包括如下内容:
|
reserved_throughput | 否 | 为数据表配置预留读吞吐量或预留写吞吐量,可选配置。 重要 仅高性能型实例中的数据表支持此功能;其他规格实例中的数据表的预留读/写吞吐量只能设置为 0,不允许预留。 默认值为 0,即完全按量计费。 单位为 CU。
|
stream_spec | 否 | Stream相关设置(可选配置)。
|
index_metas | 否 | 索引表的结构信息,每个 index_meta 都包括如下内容:
|
响应参数
返回为空,出错时会抛出异常。
示例
创建数据表时不带索引
以下示例用于同时创建数据表不带索引。该表的主键为 PK0(Integer 类型)、PK1(String 类型)和 PK2(Binary 类型),属性列值最多保留 2 个版本数据以及数据永不过期。
$result = $client->createTable([
'table_meta' => [
//设置数据表名称。
'table_name' => 'SampleTable',
//为数据表添加主键列。
'primary_key_schema' => [
['PK0', PrimaryKeyTypeConst::CONST_INTEGER],
['PK1', PrimaryKeyTypeConst::CONST_STRING],
['PK2', PrimaryKeyTypeConst::CONST_BINARY]
]
],
'reserved_throughput' => [
//设置预留读写吞吐量,容量型实例中的数据表只能设置为0,高性能型实例中的数据表可以设置为非零值。
'capacity_unit' => [
'read' => 0,
'write' => 0
]
],
'table_options' => [
//数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
'time_to_live' => -1,
//保存的最大版本数,1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
'max_versions' => 2,
//有效版本偏差,写入数据的时间戳与系统当前时间的偏差允许最大值。
'deviation_cell_version_in_sec' => 86400
],
'stream_spec' => [
//打开Stream。
'enable_stream' => true,
//Stream数据的过期时间。
'expiration_time' => 24
]
]);
创建数据表时配置全局二级索引
以下示例用于同时创建数据表和全局二级索引。该表的主键为 PK0(Integer 类型)和 PK1(String 类型)且包括 col1(String 类型)和 col2(Integer 类型)两个预定义列,属性列值只保留最新版本数据以及数据永不过期。该全局二级索引 indexName1 的主键列为 col1、PK0 和 PK1,属性列为 col2。全局二级索引 indexName2 的主键列为 PK1、PK0,属性列为 col1、col2。
$request = array (
'table_meta' => array (
//设置数据表名称。
'table_name' => 'SampleTable',
//为数据表添加主键列。
'primary_key_schema' => array (
array('PK0', PrimaryKeyTypeConst::CONST_INTEGER),
array('PK1', PrimaryKeyTypeConst::CONST_STRING)
),
//为数据表添加非主键列。
'defined_column' => array(
array('col1', DefinedColumnTypeConst::DCT_STRING),
array('col2', DefinedColumnTypeConst::DCT_INTEGER)
)
),
'reserved_throughput' => array (
//设置预留读写吞吐量,容量型实例中的数据表只能设置为0,高性能型实例中的数据表可以设置为非零值。
'capacity_unit' => array (
'read' => 0,
'write' => 0
)
),
'table_options' => [
//数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
'time_to_live' => -1,
//保存的最大版本数,1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
'max_versions' => 1,
//有效版本偏差,写入数据的时间戳与系统当前时间的偏差允许最大值。
'deviation_cell_version_in_sec' => 86400
],
'index_metas' => array(
array(
//设置索引表名称。
'name' => 'indexName1',
//设置索引表的索引列,索引列为数据表主键和预定义列的任意组合。
'primary_key' => array('col1'),
//索引表的属性列,索引表属性列为数据表的预定义列的组合。
'defined_column' => array('col2'),
//设置索引类型为全局二级索引。
'index_type' => IndexTypeConst::GLOBAL_INDEX,
//设置索引更新模式为异步更新。
'index_update_mode' => IndexUpdateModeConst::ASYNC_INDEX
),
array(
'name' => 'indexName2',
'primary_key' => array('PK1'),
'defined_column' => array('col1', 'col2')
)
)
);
//调用创建表方法。
$result = $client->createTable($request);
创建数据表时配置本地二级索引
以下示例用于同时创建数据表和本地二级索引。该表的主键为 PK0(Integer 类型)和 PK1(String 类型)且包括 col1(String 类型)和 col2(Integer 类型)两个预定义列,属性列值只保留最新版本数据以及数据永不过期。该本地二级索引 indexName3 的主键列为 PK0、col1 和 PK2,属性列为 col2。本地二级索引 indexName4 的主键为 PK0、col2 和 PK1,属性列为 col1。
$request = array (
'table_meta' => array (
//设置数据表名称。
'table_name' => 'SampleTable',
//为数据表添加主键列。
'primary_key_schema' => array (
array('PK0', PrimaryKeyTypeConst::CONST_INTEGER),
array('PK1', PrimaryKeyTypeConst::CONST_STRING)
),
//为数据表添加非主键列。
'defined_column' => array(
array('col1', DefinedColumnTypeConst::DCT_STRING),
array('col2', DefinedColumnTypeConst::DCT_INTEGER)
)
),
//设置预留读写吞吐量,容量型实例中的数据表只能设置为0,高性能型实例中的数据表可以设置为非零值。
'reserved_throughput' => array (
'capacity_unit' => array (
'read' => 0,
'write' => 0
)
),
'table_options' => array(
//数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
'time_to_live' => -1,
//保存的最大版本数,1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
'max_versions' => 1,
//写入数据的时间戳与系统当前时间的偏差允许最大值。
'deviation_cell_version_in_sec' => 86400
),
'index_metas' => array(
array(
//设置索引表名称。
'name' => 'indexName3',
//设置索引表的索引列,索引列为数据表主键和预定义列的任意组合。
'primary_key' => array('PK0', 'col1'),
//索引表的属性列,索引表属性列为数据表的预定义列的组合。
'defined_column' => array('col2'),
//设置索引类型为本地二级索引。
'index_type' => IndexTypeConst::LOCAL_INDEX,
//设置索引更新模式为异步更新。
'index_update_mode' => IndexUpdateModeConst::SYNC_INDEX
),
array(
'name' => 'indexName4',
'primary_key' => array('PK0', 'col2'),
'defined_column' => array('col1'),
'index_type' => IndexTypeConst::LOCAL_INDEX,
'index_update_mode' => IndexUpdateModeConst::SYNC_INDEX
)
)
);
//调用创建表方法。
$result = $client->createTable($request);
相关文档
关于 API 说明的更多信息,请参见 CreateTable。
如果要读写表中数据,您可以通过调用读写数据接口实现。具体操作,请参见基础数据操作。
如果要修改表的数据生命周期、最大版本数等信息,您可以通过更新表实现。具体操作,请参见更新表配置。
为数据表开启局部事务后,您可以创建局部事务用于读写局部事务范围内的数据。具体操作,请参见局部事务。
如果要查看实例中已存在的所有表,您可以通过列出表名称来实现。具体操作,请参见列出表名称。
如果要查看表的最大版本数、数据生命周期等配置信息,您可以通过查看表描述信息实现。具体操作,请参见查询表描述信息。
如果不再使用数据表,您可以删除数据表。具体操作,请参见删除数据表。