数据表主要用于数据的存储与查询。创建数据表后,您可以根据实际管理数据表,例如获取实例中的所有表名称、查询数据表的配置信息、更新数据表的配置信息等。
注意事项
主键自增列功能和局部事务功能不能同时使用。如果创建数据表时配置了主键自增列,则开启局部事务的配置会不生效。
创建成功的数据表不能立刻提供读写服务。通常在建表成功后一分钟左右,即可对新创建的表进行读写操作。
单个实例最多可以创建64张数据表。
功能概述
表格存储提供了CreateTable、ListTable、UpdateTable、DescribeTable和DeleteTable的表操作接口。
使用表格存储存储数据前,您需要通过调用CreateTable接口创建一个数据表。
创建数据表时,您需要指定数据表的结构信息以及根据实际使用所需功能。其中数据表的结构信息包括数据表名称、主键定义以及预定义列配置。
为数据表配置最大版本数和数据生命周期。更多信息,请参见数据版本和生命周期。
对于CU模式(原按量模式)下的高性能实例,为数据表配置预留读/写吞吐量。更多信息,请参见预留读/写吞吐量。
同时创建一个或者多个索引表。更多信息,请参见二级索引。
使用二级索引时,需要在创建数据表时预先定义一些非主键列以及其类型,作为索引表的索引列或者属性列。您也可以在创建数据表后新增或者删除预定义列。
为数据表开启数据加密。更多信息,请参见数据加密。
系统默认允许通过UpdateRow更新写入数据到数据表。如果后续要使用多元索引生命周期,则必须禁止通过UpdateRow更新写入数据。您也可以在创建数据表后修改表的是否允许更新状态。
为数据表开启局部事务。更多信息,请参见局部事务。
如果创建数据表时未开启局部事务功能,创建数据表后需要使用该功能,请提交工单进行申请。
重要仅Java SDK 5.11.0及以上版本支持为数据表开启局部事务。
为数据表配置主键列自增。更多信息,请参见主键列自增。
创建数据表后,您可以根据实际需要执行相应操作。
操作 | 说明 |
操作 | 说明 |
列出表名称 | 调用ListTable接口获取当前实例下已创建的所有表名称。 |
更新表信息 | 调用UpdateTable接口修改配置信息(TableOptions)、预留读吞吐量、预留写吞吐量(ReservedThroughput)或者是否允许更新状态。 |
查询表描述信息 | 调用DescribeTable接口查询指定表的结构、预留读/写吞吐量详情等信息。 |
删除数据表 | 调用DeleteTable接口删除当前实例下指定数据表。 重要
|
管理预定义列 | 预定义列用于作为索引表的索引列或者属性列。 使用二级索引时,如果未设置预定义列或者预定义列不满足需求,您可以为数据表增加预定义列。 添加预定义列后,如果不再需要某些预定义列,您可以删除预定义列。 |
使用方式
使用控制台
通过表格存储控制台执行如下操作创建数据表。
进入实例管理页面。
登录表格存储控制台。
在页面上方,选择资源组和地域。
在概览页面,单击实例名称或在实例操作列单击实例管理。
在实例详情页签,单击创建数据表。
在创建数据表对话框,按照下表说明配置相关参数。
参数
描述
数据表名称
数据表名称,用于在实例中唯一标识一张数据表。
数据表的命名规则为由大小写字母、数字或下划线(_)组成,且只能以字母或下划线(_)开头,长度在1到255个字节之间。
表主键
表中的一列或多列,用于唯一标识表中的一条记录。
输入表主键名称并选择数据类型,单击添加表主键,可加入新的主键。
单表最多可设置4个主键,第一个主键默认为分区键。主键的配置及顺序设置后不能修改。
重要表格存储支持将主键列设置为自增列,每张表只能设置一个主键列为自增列,且分区键不能设置为自增列。
主键列设置为自增列后,在写入一行数据时,该主键列无需填值,表格存储会自动生成该主键列的值。自动生成的主键列的值在分区键内严格递增且唯一。
表主键名称的命名规则为由大小写字母、数字或下划线(_)组成,且只能以字母或下划线(_)开头,长度在1个~255个字节之间。
主键的数据类型可选为字符串、整型或二进制。
是否允许更新
是否允许通过UpdateRow更新写入数据。默认值为是,表示允许通过UpdateRow更新写入数据。
当要使用多元索引生命周期功能时,您必须将此参数设置为否,即不允许通过UpdateRow更新写入数据。关于多元索引生命周期的更多信息,请参见生命周期管理。
是否加密
是否开启数据落盘加密。系统默认未开启数据落盘加密功能。打开是否加密开关,即可开启数据落盘加密功能。
重要数据落盘加密功能开启后不支持关闭,请谨慎操作。
加密类型
数据的加密类型。只有打开是否加密开关时,需要配置该选项。取值范围如下:
kms服务主密钥:表格存储会自动创建KMS服务主密钥用于数据落盘加解密。
BYOK自定义密钥:表格存储会基于您自定义的密钥进行数据落盘加解密。
重要使用BYOK自定义密钥的加密类型前,您需要通过KMS控制台创建软件密钥,然后创建自定义角色并配置权限。具体操作,请参见基于BYOK自定义密钥加密。
密钥ID
密钥的ID。只有当加密类型选择BYOK自定义密钥时,需要配置该选项。
ARN
角色ARN。只有当加密类型选择BYOK自定义密钥时,需要配置该选项。
(可选)在创建数据表对话框,进行高级配置或者创建二级索引。
当需要对数据表设置数据生命周期等高级配置或者创建二级索引时,请执行此步骤。
配置高级参数配置二级索引如果需要管理表中数据的保存时长,您可以指定数据生命周期;如果需要相同主键的多个版本数据,您可以指定最大版本数。更多信息,请参见数据版本和生命周期。
对于按量模式下的高性能实例,如果要通过预留吞吐量节省成本,您可以指定数据表的预留读吞吐量或写吞吐量。更多信息,请参见预留读/写吞吐量。
打开高级设置开关。
根据下表说明配置高级参数。
参数
描述
数据生命周期
数据表中数据的保存时间。当数据的保存时间超过设置的数据生命周期时,系统会自动清理超过数据生命周期的数据。单位为秒。
取值:大于等于86400秒(一天)或-1(数据永不过期)。
最大版本数
数据表中的属性列能够保留数据的最大版本个数。当属性列数据的版本个数超过设置的最大版本数时,系统会自动删除较早版本的数据。
取值必须为非0整数。
数据有效版本偏差
指定的数据版本号与系统当前时间偏差的允许最大值,单位为秒。有效版本偏差为正整数,可以大于1970-01-01 00:00:00 UTC时间到当前时间的秒数。
只有当写入数据所有列的版本号与写入时时间的差值在数据有效版本偏差范围内,数据才能成功写入。
属性列的有效版本范围为[max{数据写入时间-有效版本偏差,数据写入时间-数据生命周期},数据写入时间+有效版本偏差)。
预留读吞吐量
容量型实例不支持该参数。
为数据表预留读吞吐量或写吞吐量。取值范围为0~100000,且取值必须为整数。单位为CU。
当预留读吞吐量或预留写吞吐量大于0时,表格存储会根据配置为数据表分配和预留相应资源,且数据表创建成功后,将会立即按照预留吞吐量开始计费。
当预留读吞吐量或预留写吞吐量为0时,表格存储不会为数据表分配和预留相应资源。
预留写吞吐量
当某些应用需要使用不同属性作为查询条件来执行数据查询时,您可以通过将这些属性作为二级索引的主键列实现按照属性快速查询数据的需求。更多信息,请参见二级索引。
打开创建二级索引开关。
单击添加预定义列,输入预定义列名称和选择数据类型。
预定义列名称命名规则为由大小写字母、数字或下划线(_)组成,且只能以字母或下划线(_)开头,长度在1个~255个字节。
预定义列的数据类型可选为字符串、整型、二进制、浮点数或布尔值。
单击添加二级索引,输入索引名称,选择索引主键,根据需要选择索引预定义列及索引类型。
重要索引名不能与数据表名称相同,索引名和数据表名称均必须在实例中唯一。
索引名称必须由大小写字母、数字或下划线(_)组成,且只能以字母或下划线(_)开头,长度在1个~255个字节之间。
索引主键可以是数据表主键和预定义列,支持多选;索引预定义列只能从数据表的预定义列中选择,支持多选。但是选择的索引预定义列不能与主键列重复。
索引类型支持选择为全局或者本地。
重要全局二级索引的第一列主键可根据需要选择任意主键列或者预定义列,本地二级索引的第一列主键必须和数据表的第一列主键相同。
全局二级索引以异步方式将数据表中被索引的列和主键列的数据自动同步到索引表中,正常情况下同步延迟达到毫秒级别;本地二级索引以同步方式将数据表中被索引的列和主键列的数据自动同步到索引表中,当数据写入数据表后,即可从索引表中查询到数据。
单击确定。
创建数据表后,请根据实际需要执行相应操作管理数据表。
操作 | 说明 |
列出表名称 | 在数据表列表页签,查看实例内的所有表名称。 |
更新表信息 |
|
查询表描述信息 |
|
管理预定义列 |
添加预定义列后,在基本详情页签的高级功能区域,单击预定义列对应的 |
删除数据表 |
|
使用命令行工具
通过命令行工具执行create
命令创建数据表。更多信息,请参见创建表。
以下示例用于创建名称为mytable的数据表,该数据表有uid(string类型)和pid(integer类型)两个主键列,表中数据永不过期。
create -t mytable --pk '[{"c":"uid", "t":"string"}, {"c":"pid", "t":"integer"}]'
执行表操作前,您需要执行use
命令选择要使用的表。更多信息,请参见使用表。
以下示例用于使用mytable数据表。
use --wc -t mytable
创建并使用数据表后,请根据实际需要执行相应操作管理数据表。
操作 | 说明 |
列出表名称 | 执行 以下示例用于列出所有数据表名称。
|
更新表信息 | 执行 以下示例用于修改mytable数据表的数据生命周期为86400秒(即1天),最大版本数为1,且预留读CU和预留写CU均为0。
|
查询表描述信息 | 执行 以下示例用于查看当前表的描述信息。
|
删除数据表 | 执行drop命令删除不需要的表。更多信息,请参见删除表。 以下示例用于删除mytable表。
|
使用SDK
您可以使用Java SDK、Go SDK、Python SDK、Node.js SDK、.NET SDK和PHP SDK创建数据表以及管理数据表。此处以Java SDK为例介绍数据表的创建和管理。
不同SDK支持的功能可能存在不同,请以实际为准。
请根据实际场景选择合适示例进行数据表创建。
以下示例用于创建数据表。
private static void createTable(SyncClient client) {
//设置数据表名称。
TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
//为数据表添加主键列。主键为pk1(String类型)和pk2(Integer类型),其中pk1主键列为分区键,pk2主键列为自增列。
tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER, PrimaryKeyOption.AUTO_INCREMENT));
//数据的过期时间,-1表示永不过期。
int timeToLive = -1;
//最大版本数,属性列值最多保留1个版本,即保存最新的版本。
int maxVersions = 1;
//有效版本偏差,即写入数据的时间戳与系统当前时间的偏差允许最大值为86400秒(1天)。
long maxTimeDeviation = 86400L;
TableOptions tableOptions = new TableOptions(timeToLive, maxVersions, maxTimeDeviation);
//设置预留读写吞吐量,容量型实例下的数据表只能设置为0,高性能型实例下的数据表可以设置为非零值。
ReservedThroughput reservedThroughput = new ReservedThroughput(new CapacityUnit(0, 0));
CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, reservedThroughput);
client.createTable(request);
}
以下示例用于同时创建数据表和全局二级索引。
private static void createTable(SyncClient client) {
//设置数据表名称。
TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
//为数据表添加主键列。主键为pk1(String类型)和pk2(Integer类型)。
tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER));
//为数据表添加预定义列。预定义列为defcol1(String类型)和defcol2(Integer类型)。
tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol1", DefinedColumnType.STRING));
tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol2", DefinedColumnType.INTEGER));
//数据永不过期,-1表示永不过期。
int timeToLive = -1;
//最大版本数,属性列值最多保留1个版本,即保存最新的版本。
int maxVersions = 1;
TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
//全局二级索引
ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
//设置索引名称。
IndexMeta indexMeta = new IndexMeta("<INDEX_NAME>");
//为索引添加主键列。主键列为defcol1、pk1和pk2
indexMeta.addPrimaryKeyColumn("defcol1");
indexMeta.addPrimaryKeyColumn("pk1");
indexMeta.addPrimaryKeyColumn("pk2");
//为索引添加预定义列。预定义列为defcol2。
indexMeta.addDefinedColumn("defcol2");
indexMetas.add(indexMeta);
//创建数据表的同时创建索引。
CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas);
client.createTable(request);
}
以下示例用于同时创建数据表和本地二级索引。
private static void createTable(SyncClient client) {
//设置数据表名称。
TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
//为数据表添加主键列。主键为pk1(String类型)和pk2(Integer类型)。
tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER));
//为数据表添加预定义列。预定义列为defcol1(String类型)和defcol2(Integer类型)。
tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol1", DefinedColumnType.STRING));
tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol2", DefinedColumnType.INTEGER));
//数据的过期时间,-1表示永不过期。1。
int timeToLive = -1;
//最大版本数,属性列值最多保留1个版本,即保存最新的版本。
int maxVersions = 1;
TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
//本地二级索引
ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
//设置索引名称。
IndexMeta indexMeta = new IndexMeta("<INDEX_NAME>");
//设置索引类型为本地二级索引(IT_LOCAL_INDEX)。
indexMeta.setIndexType(IT_LOCAL_INDEX);
//设置索引更新模式为同步更新(IUM_SYNC_INDEX)。当索引类型为本地二级索引时,索引更新模式必须为同步更新。
indexMeta.setIndexUpdateMode(IUM_SYNC_INDEX);
//为索引添加主键列。主键列为pk1、defcol1和pk2。
indexMeta.addPrimaryKeyColumn("pk1");
indexMeta.addPrimaryKeyColumn("defcol1");
indexMeta.addPrimaryKeyColumn("pk2");
//为索引添加预定义列。预定义列为defcol2。
indexMeta.addDefinedColumn("defcol2");
indexMetas.add(indexMeta);
//创建数据表的同时创建索引。
CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas);
client.createTable(request);
}
以下示例用于创建数据表时开启局部事务功能。
private static void createTable(SyncClient client) {
//设置数据表名称。
TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
//为数据表添加主键列。主键为pk1(String类型)和pk2(Integer类型)。
tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER));
//数据的过期时间,-1表示永不过期。
int timeToLive = -1;
//最大版本数,属性列值最多保留1个版本,即保存最新的版本。
int maxVersions = 1;
TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
//开启局部事务。如果数据表配置了主键自增列,则开启局部事务配置不会生效。
request.setLocalTxnEnabled(true);
client.createTable(request);
}
以下示例用于创建数据表时使用基于KMS服务密钥加密表中数据。该表的主键为pk(String类型),属性列值只保留最新版本数据以及数据永不过期。
private static void createTable(SyncClient client) {
//设置数据表名称。
TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
//如果要配置表加密,需要对建表请求配置加密相关参数,支持KMS服务密钥或BYOK自定义密钥两种类型。此处为使用KMS服务密钥。
SSESpecification sseKms = new SSESpecification(true, SSEKeyType.SSE_KMS_SERVICE);
//为数据表添加主键列。
tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk", PrimaryKeyType.STRING));
//数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
int timeToLive = -1;
//保存的最大版本数,1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
int maxVersions = 1;
TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
//设置预留读写吞吐量,容量型实例中的数据表只能设置为0,高性能实例中的数据表可以设置为非零值。
request.setReservedThroughput(new ReservedThroughput(new CapacityUnit(0, 0)));
request.setSseSpecification(sseKms);
client.createTable(request);
}
以下示例用于创建数据表时配置主键自增列。该表的主键为pk1(String类型)和pk2(Integer类型),其中pk1主键列为分区键,pk2主键列为自增列。
private static void createTable(SyncClient client) {
//设置数据表名称。
TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
//为数据表添加主键列。第一列为分区键。
tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
//为数据表添加主键列。第二列为自增列,类型为INTEGER,属性为AUTO_INCREMENT。
tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER, PrimaryKeyOption.AUTO_INCREMENT));
//数据的过期时间,单位为秒,-1表示数据永不过期。
int timeToLive = -1;
//保存的最大版本数,1表示每列上最多保存一个版本即保存最新的版本。
int maxVersions = 1;
TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
client.createTable(request);
}
创建数据表后,请根据实际需要执行相应操作管理数据表。
以下示例用于列出实例内所有表名称。
private static void listTable(SyncClient client) {
ListTableResponse response = client.listTable();
System.out.println("表的列表如下:");
for (String tableName : response.getTableNames()) {
System.out.println(tableName);
}
}
以下示例用于修改数据表的配置信息。
private static void updateTable(SyncClient client) {
//数据的过期时间,-1表示永不过期。
int timeToLive = -1;
//最大版本数,属性列值最多保留5个版本。
int maxVersions = 5;
//有效版本偏差,即写入数据的时间戳与系统当前时间的偏差允许最大值为86400秒(1天)。
long maxTimeDeviation = 86400L;
TableOptions tableOptions = new TableOptions(timeToLive, maxVersions, maxTimeDeviation);
//允许UpdateRow相关更新写入操作。
tableOptions.setAllowUpdate(true);
//开启Stream功能,设置stream过期时间为24小时。
//StreamSpecification streamSpecification = new StreamSpecification(true, 24);
//设置数据表名称。
UpdateTableRequest request = new UpdateTableRequest("<TABLE_NAME>");
request.setTableOptionsForUpdate(tableOptions);
client.updateTable(request);
}
以下示例用于修改 CU 模式下高性能型实例中数据表的预留吞吐量 。
private static void updateTable(SyncClient client) {
//设置新的预留读吞吐量为1,写吞吐量为1。容量型实例下的数据表只能设置为0。
ReservedThroughput reservedThroughput = new ReservedThroughput(new CapacityUnit(1, 1));
//设置数据表名称。
UpdateTableRequest request = new UpdateTableRequest("<TABLE_NAME>");
request.setReservedThroughputForUpdate(reservedThroughput);
client.updateTable(request);
}
以下示例用于查询数据表的表结构信息、可选配置信息和预留吞吐量信息。
private static void describeTable(SyncClient client) {
//设置数据表名称。
DescribeTableRequest request = new DescribeTableRequest("<TABLE_NAME>");
DescribeTableResponse response = client.describeTable(request);
TableMeta tableMeta = response.getTableMeta();
System.out.println("表的名称:" + tableMeta.getTableName());
System.out.println("表的主键:");
for (PrimaryKeySchema primaryKeySchema : tableMeta.getPrimaryKeyList()) {
System.out.println(primaryKeySchema);
}
TableOptions tableOptions = response.getTableOptions();
System.out.println("表的TTL:" + tableOptions.getTimeToLive());
System.out.println("表的MaxVersions:" + tableOptions.getMaxVersions());
//只能查看加密表的加密配置信息。非加密表无此配置项。
//System.out.println("表的加密配置:" + response.getSseDetails());
ReservedThroughputDetails reservedThroughputDetails = response.getReservedThroughputDetails();
System.out.println("表的预留读吞吐量:"
+ reservedThroughputDetails.getCapacityUnit().getReadCapacityUnit());
System.out.println("表的预留写吞吐量:"
+ reservedThroughputDetails.getCapacityUnit().getWriteCapacityUnit());
}
以下示例用于为数据表增加预定义列,预定义列分别为definedColumnName01(String类型)、definedColumnName02(Integer类型)和definedColumnName03(String类型)。
public static void addDefinedColumnRequest(SyncClient client) {
AddDefinedColumnRequest addDefinedColumnRequest = new AddDefinedColumnRequest();
//设置数据表名称。
addDefinedColumnRequest.setTableName("<TABLE_NAME>");
//为数据表添加预定义列。
addDefinedColumnRequest.addDefinedColumn("definedColumnName01",DefinedColumnType.STRING);
addDefinedColumnRequest.addDefinedColumn("definedColumnName02",DefinedColumnType.INTEGER);
addDefinedColumnRequest.addDefinedColumn("definedColumnName03",DefinedColumnType.STRING);
client.addDefinedColumn(addDefinedColumnRequest);
}
如果不再需要某些预定义列,您可以删除预定义列。
以下示例用于删除数据表的预定义列definedColumnName01和definedColumnName02。
public static void deleteDefinedColumnRequest(SyncClient client){
DeleteDefinedColumnRequest deleteDefinedColumnRequest = new DeleteDefinedColumnRequest();
//设置数据表名称。
deleteDefinedColumnRequest.setTableName("<TABLE_NAME>");
//添加要删除的预定义列。
deleteDefinedColumnRequest.addDefinedColumn("definedColumnName01");
deleteDefinedColumnRequest.addDefinedColumn("definedColumnName02");
client.deleteDefinedColumn(deleteDefinedColumnRequest);
}
以下示例用于删除exampletable数据表。
private static void deleteTable(SyncClient client) {
//设置数据表名称。
DeleteTableRequest request = new DeleteTableRequest("<TABLE_NAME>");
client.deleteTable(request);
}
- 本页导读 (1)
- 注意事项
- 功能概述
- 使用方式
- 使用控制台
- 使用命令行工具
- 使用SDK