如何使用資料表 - Tablestore

資料表主要用於資料的儲存與查詢。建立資料表後，您可以根據實際管理資料表，例如擷取執行個體中的所有表名稱、查詢資料表的配置資訊、更新資料表的配置資訊等。

注意事項

主鍵自增列功能和局部事務功能不能同時使用。如果建立資料表時配置了主鍵自增列，則開啟局部事務的配置會不生效。
建立成功的資料表不能立刻提供讀寫服務。通常在建表成功後一分鐘左右，即可對新建立的表進行讀寫操作。
單個執行個體最多可以建立64張資料表。

功能概述

Table Store提供了CreateTable、ListTable、UpdateTable、DescribeTable和DeleteTable的表操作介面。

使用Tablestore儲存資料前，您需要通過調用CreateTable介面建立一個資料表。

建立資料表時，您需要指定資料表的結構資訊以及根據實際使用所需功能。其中資料表的結構資訊包括資料表名稱、主鍵定義以及預定義列配置。

為資料表配置最大版本數和資料生命週期。更多資訊，請參見資料版本和生命週期。
對於高效能執行個體，為資料表配置預留讀/寫輸送量。更多資訊，請參見預留讀/寫輸送量。
同時建立一個或者多個索引表。更多資訊，請參見二級索引介紹。
使用二級索引時，需要在建立資料表時預先定義一些非主鍵列以及其類型，作為索引表的索引列或者屬性列。您也可以在建立資料表後新增或者刪除預定義列。
為資料表開啟資料加密。更多資訊，請參見資料加密。
系統預設允許通過UpdateRow更新寫入資料到資料表。如果後續要使用多元索引生命週期，則必須禁止通過UpdateRow更新寫入資料。您也可以在建立資料表後修改表的是否允許更新狀態。
為資料表開啟局部事務。更多資訊，請參見局部事務。
如果建立資料表時未開啟局部事務功能，建立資料表後需要使用該功能，請提交工單進行申請。
重要
僅Java SDK 5.11.0及以上版本支援為資料表開啟局部事務。
為資料表配置主鍵列自增。更多資訊，請參見主鍵列自增。

建立資料表後，您可以根據實際需要執行相應操作。

操作	說明
列出表名稱	調用ListTable介面擷取當前執行個體下已建立的所有表名稱。
更新表資訊	調用UpdateTable介面修改配置資訊（TableOptions）、預留讀輸送量、預留寫輸送量（ReservedThroughput）或者是否允許更新狀態。
查詢表描述資訊	調用DescribeTable介面查詢指定表的結構、預留讀/寫輸送量詳情等資訊。
刪除資料表	調用DeleteTable介面刪除當前執行個體下指定資料表。重要刪除資料表會導致表不可用，且表資料不可恢複，請謹慎操作。刪除資料表前，請確保已刪除資料表的二級索引、多元索引和資料投遞任務。
管理預定義列	預定義列用於作為索引表的索引列或者屬性列。使用二級索引時，如果未設定預定義列或者預定義列不滿足需求，您可以為資料表增加預定義列。添加預定義列後，如果不再需要某些預定義列，您可以刪除預定義列。

使用方式

使用控制台

通過Table Store控制台執行如下操作建立資料表。

登入Table Store控制台。
在頁面上方，選擇資源群組和地區。
在概覽頁面，單擊執行個體名稱或在執行個體操作列單擊執行個體管理。
在執行個體詳情頁簽，單擊建立資料表。
在建立資料表對話方塊，配置資料表名稱和表主鍵，其他參數請根據實際情境進行配置。
說明
關於參數配置的更多資訊，請參見通過控制台建立資料表。
- 如果要使用自增主鍵列功能，請在配置表主鍵時，將非分區鍵的主鍵列選擇為自增列。
- 如果要使用多元索引生命週期功能，請將是否允許更新設定為否。
- 如果要進行資料落盤加解密，請開啟是否加密開關，然後根據實際需要選擇加密類型為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);
}