如何使用数据表 - 表格存储

数据表主要用于数据的存储与查询。创建数据表后，您可以根据实际管理数据表，例如获取实例中的所有表名称、查询数据表的配置信息、更新数据表的配置信息等。

注意事项

主键自增列功能和局部事务功能不能同时使用。如果创建数据表时配置了主键自增列，则开启局部事务的配置会不生效。
创建成功的数据表不能立刻提供读写服务。通常在建表成功后一分钟左右，即可对新创建的表进行读写操作。
单个实例最多可以创建64张数据表。

功能概述

表格存储提供了CreateTable、ListTable、UpdateTable、DescribeTable和DeleteTable的表操作接口。

使用表格存储存储数据前，您需要通过调用CreateTable接口创建一个数据表。

创建数据表时，您需要指定数据表的结构信息以及根据实际使用所需功能。其中数据表的结构信息包括数据表名称、主键定义以及预定义列配置。

为数据表配置最大版本数和数据生命周期。更多信息，请参见数据版本和生命周期。
对于高性能实例，为数据表配置预留读/写吞吐量。更多信息，请参见预留读/写吞吐量。
同时创建一个或者多个索引表。更多信息，请参见二级索引介绍。
使用二级索引时，需要在创建数据表时预先定义一些非主键列以及其类型，作为索引表的索引列或者属性列。您也可以在创建数据表后新增或者删除预定义列。
为数据表开启数据加密。更多信息，请参见数据加密。
系统默认允许通过UpdateRow更新写入数据到数据表。如果后续要使用多元索引生命周期，则必须禁止通过UpdateRow更新写入数据。您也可以在创建数据表后修改表的是否允许更新状态。
为数据表开启局部事务。更多信息，请参见局部事务。
如果创建数据表时未开启局部事务功能，创建数据表后需要使用该功能，请提交工单进行申请。
重要
仅Java SDK 5.11.0及以上版本支持为数据表开启局部事务。
为数据表配置主键列自增。更多信息，请参见主键列自增。

创建数据表后，您可以根据实际需要执行相应操作。

操作	说明
列出表名称	调用ListTable接口获取当前实例下已创建的所有表名称。
更新表信息	调用UpdateTable接口修改配置信息（TableOptions）、预留读吞吐量、预留写吞吐量（ReservedThroughput）或者是否允许更新状态。
查询表描述信息	调用DescribeTable接口查询指定表的结构、预留读/写吞吐量详情等信息。
删除数据表	调用DeleteTable接口删除当前实例下指定数据表。重要删除数据表会导致表不可用，且表数据不可恢复，请谨慎操作。删除数据表前，请确保已删除数据表的二级索引、多元索引和数据投递任务。
管理预定义列	预定义列用于作为索引表的索引列或者属性列。使用二级索引时，如果未设置预定义列或者预定义列不满足需求，您可以为数据表增加预定义列。添加预定义列后，如果不再需要某些预定义列，您可以删除预定义列。

使用方式

使用控制台

通过表格存储控制台执行如下操作创建数据表。

登录表格存储控制台。
在页面上方，选择资源组和地域。
在概览页面，单击实例名称或在实例操作列单击实例管理。
在实例详情页签，单击创建数据表。
在创建数据表对话框，配置数据表名称和表主键，其他参数请根据实际场景进行配置。
说明
关于参数配置的更多信息，请参见通过控制台创建数据表。
- 如果要使用自增主键列功能，请在配置表主键时，将非分区键的主键列选择为自增列。
- 如果要使用多元索引生命周期功能，请将是否允许更新设置为否。
- 如果要进行数据落盘加解密，请打开是否加密开关，然后根据实际需要选择加密类型为kms服务主密钥或BYOK自定义密钥。更多信息，请参见数据加密。
- 如果要创建本地二级索引或者全局二级索引，请打开创建二级索引开关并添加预定义列，然后添加二级索引。
- 如果要为数据表配置数据生命周期等，请打开高级设置开关并配置数据生命周期、最大版本数、数据有效版本偏差、预留读吞吐量或者预留写吞吐量。
单击确定。

创建数据表后，请根据实际需要执行相应操作管理数据表。

操作	说明
列出表名称	在数据表列表页签，查看实例内的所有表名称。
更新表信息	在数据表列表页签，单击数据表名称。在基本详情页签的基本信息区域，单击修改表属性。在修改表属性对话框，根据需要修改数据生命周期、最大版本数、数据有效版本偏差、是否允许更新。单击确定。
查询表描述信息	在数据表列表页签，单击数据表名称。在基本详情页签，查看表信息。在基本信息区域，您可以查看表的名称、最大版本数、数据生命周期、数据有效版本偏差、是否允许更新等信息；在高级功能区域，您可以查看表主键列表、预定义列信息等。
管理预定义列	在数据表列表页签，单击数据表名称。在基本详情页签的高级功能区域，单击添加预定义列。在添加预定义列对话框，单击添加预定义列，然后填写预定义列名称和选择字段类型。单击确定。添加预定义列后，在基本详情页签的高级功能区域，单击预定义列对应的图标，然后在删除预定义列对话框中单击确定。
删除数据表	在数据表列表页签，单击数据表操作列的图标，然后单击删除。在删除数据表对话框，确认表信息正确，单击删除。

使用命令行工具

通过命令行工具执行create命令创建数据表。更多信息，请参见创建表。

以下示例用于创建名称为mytable的数据表，该数据表有uid（string类型）和pid（integer类型）两个主键列，表中数据永不过期。

create -t mytable --pk '[{"c":"uid", "t":"string"}, {"c":"pid", "t":"integer"}]'

执行表操作前，您需要执行use命令选择要使用的表。更多信息，请参见使用表。

以下示例用于使用mytable数据表。

use --wc -t mytable

创建并使用数据表后，请根据实际需要执行相应操作管理数据表。

操作	说明
列出表名称	执行`list`命令列出表名称。更多信息，请参见列出表名称。以下示例用于列出所有数据表名称。 `list -w`
更新表信息	执行`alter`命令更新表信息。更多信息，请参见更新表。以下示例用于修改mytable数据表的数据生命周期为86400秒（即1天），最大版本数为1，且预留读CU和预留写CU均为0。 `alter -t mytable --ttl 86400 --version 1 --read_cu 0 --write_cu 0`
查询表描述信息	执行`desc`命令查看表描述信息。更多信息，请参见查看表信息。以下示例用于查看当前表的描述信息。 `desc`
删除数据表	执行drop命令删除不需要的表。更多信息，请参见删除表。以下示例用于删除mytable表。 `drop -t mytable -y`

使用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服务密钥加密的表

以下示例用于创建数据表时使用基于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);
}

更新高性能型实例中数据表的预留吞吐量

以下示例用于修改高性能型实例中数据表的预留吞吐量。

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);
}