使用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都包括如下内容:
|
请求格式
$result = $client->createTable([
'table_meta' => [ //设置数据表结构信息,必须配置。
'table_name' => '<string>',
'primary_key_schema' => [
['<string>', <PrimaryKeyType>],
['<string>', <PrimaryKeyType>],
['<string>', <PrimaryKeyType>, <PrimaryKeyOption>]
]
],
'reserved_throughput' => [ //设置预留读写吞吐量,必须配置。
'capacity_unit' => [
'read' => <integer>,
'write' => <integer>
]
],
'table_options' => [ //设置数据表配置信息,必须配置。
'time_to_live' => <integer>,
'max_versions' => <integer>,
'deviation_cell_version_in_sec' => <integer>
],
'stream_spec' => [
'enable_stream' => true || false,
'expiration_time' => <integer>
]
]);
响应信息
响应参数
返回为空,出错时会抛出异常。
结果格式
[]
示例
创建数据表时不带索引
以下示例用于同时创建数据表不带索引。该表的主键为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);