文档

数据表操作

更新时间:

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

注意事项

  • 主键自增列功能和局部事务功能不能同时使用。如果创建数据表时配置了主键自增列,则开启局部事务的配置会不生效。

  • 创建成功的数据表不能立刻提供读写服务。通常在建表成功后一分钟左右,即可对新创建的表进行读写操作。

  • 单个实例最多可以创建64张数据表。

功能概述

表格存储提供了CreateTableListTableUpdateTableDescribeTableDeleteTable的表操作接口。

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

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

  • 为数据表配置最大版本数和数据生命周期。更多信息,请参见数据版本和生命周期

  • 对于按量模式下的高性能实例,为数据表配置预留读/写吞吐量。更多信息,请参见预留读/写吞吐量

  • 同时创建一个或者多个索引表。更多信息,请参见二级索引简介

    使用二级索引时,需要在创建数据表时预先定义一些非主键列以及其类型,作为索引表的索引列或者属性列。您也可以在创建数据表后新增或者删除预定义列。

  • 为数据表开启数据加密。更多信息,请参见数据加密

  • 系统默认允许通过UpdateRow更新写入数据到数据表。如果后续要使用多元索引生命周期,则必须禁止通过UpdateRow更新写入数据。您也可以在创建数据表后修改表的是否允许更新状态。

  • 为数据表开启局部事务。更多信息,请参见局部事务

    如果创建数据表时未开启局部事务功能,创建数据表后需要使用该功能,请提交工单进行申请。

    重要

    仅Java SDK 5.11.0及以上版本支持为数据表开启局部事务。

  • 为数据表配置主键列自增。更多信息,请参见主键列自增

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

操作

说明

列出表名称

调用ListTable接口获取当前实例下已创建的所有表名称。

更新表信息

调用UpdateTable接口修改配置信息(TableOptions)、预留读吞吐量、预留写吞吐量(ReservedThroughput)或者是否允许更新状态。

查询表描述信息

调用DescribeTable接口查询指定表的结构、预留读/写吞吐量详情等信息。

删除数据表

调用DeleteTable接口删除当前实例下指定数据表。

重要
  • 删除数据表会导致表不可用,且表数据不可恢复,请谨慎操作。

  • 删除数据表前,请确保已删除数据表的二级索引、多元索引和数据投递任务。

管理预定义列

预定义列用于作为索引表的索引列或者属性列。

使用二级索引时,如果未设置预定义列或者预定义列不满足需求,您可以为数据表增加预定义列。

添加预定义列后,如果不再需要某些预定义列,您可以删除预定义列。

使用方式

使用控制台

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

  1. 登录表格存储控制台

  2. 在页面上方,选择资源组和地域。

  3. 概览页面,单击实例名称或在实例操作列单击实例管理

  4. 实例详情页签,单击创建数据表

  5. 创建数据表对话框,配置数据表名称表主键,其他参数请根据实际场景进行配置。

    说明

    关于参数配置的更多信息,请参见通过控制台创建数据表

    • 如果要使用自增主键列功能,请在配置表主键时,将非分区键的主键列选择为自增列

    • 如果要使用多元索引生命周期功能,请设置是否允许更新

    • 如果要进行落盘加密数据,请打开是否加密开关并选择加密类型KMS服务主密钥

    • 如果要创建本地二级索引或者全局二级索引,请打开创建二级索引开关并添加预定义列,然后添加二级索引。

    • 如果要为数据表配置数据生命周期等,请打开高级设置开关并配置数据生命周期、最大版本数、数据有效版本偏差、预留读吞吐量或者预留写吞吐量。

  6. 单击确定

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

操作

说明

列出表名称

数据表列表页签,查看实例内的所有表名称。

更新表信息

  1. 数据表列表页签,单击数据表名称。

  2. 基本详情页签的基本信息区域,单击修改表属性

  3. 修改表属性对话框,根据需要修改数据生命周期、最大版本数、数据有效版本偏差、是否允许更新。

  4. 单击确定

查询表描述信息

  1. 数据表列表页签,单击数据表名称。

  2. 基本详情页签,查看表信息。

    基本信息区域,您可以查看表的名称、最大版本数、数据生命周期、数据有效版本偏差、是否允许更新等信息;在高级功能区域,您可以查看表主键列表、预定义列信息等。

管理预定义列

  1. 数据表列表页签,单击数据表名称。

  2. 基本详情页签的高级功能区域,单击添加预定义列

  3. 添加预定义列对话框,单击添加预定义列,然后填写预定义列名称和选择字段类型。

  4. 单击确定

添加预定义列后,在基本详情页签的高级功能区域,单击预定义列对应的image.png图标,然后在删除预定义列对话框中单击确定

删除数据表

  1. 数据表列表页签,单击数据表操作列的image.png图标,然后单击删除

  2. 删除数据表对话框,确认表信息正确,单击删除

使用命令行工具

通过命令行工具执行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 SDKGo SDKPython SDKNode.js SDK.NET SDKPHP SDK创建数据表以及管理数据表。此处以Java SDK为例介绍数据表的创建和管理。

重要

不同SDK支持的功能可能存在不同,请以实际为准。

请根据实际场景选择合适示例进行数据表创建。

创建表时不带索引

以下示例用于创建数据表。该表的主键为pk(String类型),属性列值最多保留3个版本数据以及数据永不过期。

private static void createTable(SyncClient client) {
    //设置数据表名称。
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    //为数据表添加主键列。
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk", PrimaryKeyType.STRING)); 
    //数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
    int timeToLive = -1; 
    //保存的最大版本数,1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
    int maxVersions = 3; 
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
        
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
    request.setReservedThroughput(new ReservedThroughput(new CapacityUnit(0, 0))); //设置预留读写吞吐量,容量型实例中的数据表只能设置为0,高性能实例中的数据表可以设置为非零值。
    client.createTable(request);
}

创建表时配置全局二级索引

以下示例用于同时创建数据表和全局二级索引。该表包含pk1(String类型)和pk2(Integer类型)两列主键且包含defcol1(String类型)和defcol2(Integer类型)两个预定义列,属性列值只保留最新版本数据以及数据永不过期。该全局二级索引的主键列为defcol1、pk1和pk2,属性列为defcol2。

private static void createTable(SyncClient client) {
    //设置数据表名称。
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    //为数据表添加主键列。
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING)); 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER)); 
    //为数据表添加预定义列。
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol1", DefinedColumnType.STRING)); 
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol2", DefinedColumnType.INTEGER)); 
    //数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
    int timeToLive = -1; 
    //保存的最大版本数,1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
    int maxVersions = 1; 
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);

    ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
    //设置索引表名称。
    IndexMeta indexMeta = new IndexMeta("<INDEX_NAME>");
    //为索引表添加主键列。
    indexMeta.addPrimaryKeyColumn("defcol1"); 
    //为索引表添加属性列。
    indexMeta.addDefinedColumn("defcol2"); 
    indexMetas.add(indexMeta);

    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas); //创建数据表的同时创建索引表。

    client.createTable(request);
}

创建表时配置本地二级索引

以下示例用于同时创建数据表和本地二级索引。该表的主键为pk1(String类型)和pk2(Integer类型)且包括defcol1(String类型)和defcol2(Integer类型)两个预定义列,属性列值只保留最新版本数据以及数据永不过期。该本地二级索引的主键列为pk1、defcol1和pk2,属性列为defcol2。

private static void createTable(SyncClient client) {
    //设置数据表名称。
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    //为数据表添加主键列。
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING)); 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER)); 
    //为数据表添加预定义列。
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol1", DefinedColumnType.STRING)); 
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol2", DefinedColumnType.INTEGER)); 
    //数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
    int timeToLive = -1; 
    //保存的最大版本数,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);  
    //为索引表添加主键列。索引表的第一列主键必须与数据表的第一列主键相同。
    indexMeta.addPrimaryKeyColumn("pk1"); 
    //为索引表添加主键列。
    indexMeta.addPrimaryKeyColumn("defcol1"); 
    //为索引表添加属性列。
    indexMeta.addDefinedColumn("defcol2"); 
    indexMetas.add(indexMeta);

    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas); //创建数据表的同时创建索引表。

    client.createTable(request);
}

创建表时开启局部事务

以下示例用于创建数据表时开启局部事务功能。该表的主键为pk1(String类型)和pk2(Integer类型),属性列值只保留最新版本数据以及数据永不过期。

private static void createTable(SyncClient client) {
    //设置数据表名称。
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    //为数据表添加主键列。
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER));
    //数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
    int timeToLive = -1; 
    //保存的最大版本数,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);
    }
}

更新表数据

以下示例用于更新exampletable数据表的最大版本数为5。

private static void updateTable(SyncClient client) {
    //数据的过期时间,单位为秒,-1表示数据永不过期。
    int timeToLive = -1;
    //将最大版本数更新为5。
    int maxVersions = 5; 
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
    //设置数据表名称。
    UpdateTableRequest request = new UpdateTableRequest("<TABLE_NAME>");
    request.setTableOptionsForUpdate(tableOptions);
    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)
文档反馈