建立資料表 - Tablestore

使用CreateTable介面建立資料表時，需要指定資料表的結構資訊和配置資訊，高效能執行個體中的資料表還可以根據需要設定預留讀/寫輸送量。建立資料表的同時支援建立一個或者多個索引表。

说明

建立資料表後需要幾秒鐘進行載入，在此期間對該資料表的讀/寫資料操作均會失敗。請等待資料表載入完畢後再進行資料操作。
建立資料表時必須指定資料表的主鍵。主鍵包含1個~4個主鍵列，每一個主鍵列都有名稱和類型。

前提條件

已通過控制台建立執行個體。具體操作，請參見建立執行個體。
已初始化Client。具體操作，請參見初始化。

參數


參數	說明
tableMeta	資料表的結構資訊，包括如下內容： tableName：資料表名稱。 primaryKey：資料表的主鍵定義。更多資訊，請參見主鍵和屬性。说明屬性列不需要定義。Table Store每行的資料列都可以不同，屬性列的列名在寫入時指定。 Table Store可包含1個~4個主鍵列。主鍵列是有順序的，與使用者添加的順序相同。例如PRIMARY KEY（A, B, C）與PRIMARY KEY（A, C, B）是不同的兩個主鍵結構。Table Store會按照整個主鍵的大小對行進行排序。第一列主鍵作為分區鍵。分區鍵相同的資料會存放在同一個分區內，所以相同分區鍵下最好不要超過10 GB以上資料，否則會導致單分區過大，無法分裂。另外，資料的讀/寫訪問最好在不同的分區鍵上均勻分布，有利於負載平衡。 definedColumns：預先定義一些非主鍵列以及其類型，可以作為索引表的屬性列或索引列。
tableOptions	資料表的配置資訊。更多資訊，請參見資料版本和生命週期。配置資訊包括如下內容： timeToLive：資料生命週期，即資料的到期時間。當資料的儲存時間超過設定的資料生命週期時，系統會自動清理超過資料生命週期的資料。資料生命週期至少為86400秒（一天）或-1（資料永不到期）。建立資料表時，如果希望資料永不到期，可以設定資料生命週期為-1；建立資料表後，可以通過UpdateTable介面動態修改資料生命週期。單位為秒。说明如果需要使用索引，則資料生命週期必須設定為-1（資料永不到期）。 maxVersions：最大版本數，即屬性列能夠保留資料的最大版本個數。當屬性列資料的版本個數超過設定的最大版本數時，系統會自動刪除較早版本的資料。建立資料表時，可以自訂屬性列的最大版本數；建立資料表後，可以通過UpdateTable介面動態修改資料表的最大版本數。说明如果需要使用索引，則最大版本數必須設定為1。 maxTimeDeviation：有效版本偏差，即寫入資料的時間戳記與系統目前時間的偏差允許最大值。只有當寫入資料所有列的版本號碼與寫入時時間的差值在資料有效版本偏差範圍內，資料才能成功寫入。屬性列的有效版本範圍為[資料寫入時間-有效版本偏差，資料寫入時間+有效版本偏差)。建立資料表時，如果未設定有效版本偏差，系統會使用預設值86400；建立資料表後，可以通過UpdateTable介面動態修改有效版本偏差。單位為秒。
reservedThroughtput	為資料表配置預留讀輸送量或預留寫輸送量。容量型執行個體中的資料表的預留讀/寫輸送量只能設定為0，不允許預留。預設值為0，即完全隨用隨付。單位為CU。當預留讀輸送量或預留寫輸送量大於0時，Table Store會根據配置為資料表預留相應資源，且資料表建立成功後，將會立即按照預留輸送量開始計費，超出預留的部分進行隨用隨付。更多資訊，請參見計費概述。當預留讀輸送量或預留寫輸送量設定為0時，Table Store不會為資料表預留相應資源。
localTxnEnabled	是否開啟局部事務功能。類型為Boolean。預設值為false，表示不開啟局部事務。如果要在建立資料表時開啟局部事務，請設定此參數為true。重要僅Java SDK 5.11.0及以上版本支援此功能。主鍵自增列功能和局部事務功能不能同時使用。如果建立資料表時配置了主鍵自增列，則開啟局部事務的配置會不生效。如果建立資料表時未開啟局部事務功能，建立資料表後需要使用該功能，請提交工單進行申請。
indexMetas	索引表的結構資訊，每個indexMeta都包括如下內容： indexName：索引表名稱。 primaryKey：索引表的索引列，索引列為資料表主鍵和預定義列的組合。使用本地二級索引時，索引表的第一個主鍵列必須與資料表的第一個主鍵列相同。 definedColumns：索引表的屬性列，索引表屬性列為資料表的預定義列的組合。 indexType：索引類型。可選值包括IT_GLOBAL_INDEX和IT_LOCAL_INDEX。當不設定indexType或者設定indexType為IT_GLOBAL_INDEX時，表示使用全域二級索引。使用全域索引時，Table Store以非同步方式將資料表中被索引的列和主鍵列的資料自動同步到索引表中，正常情況下同步延遲達到毫秒層級。當設定indexType為IT_LOCAL_INDEX時，表示使用本地二級索引。使用本地二級索引時，Table Store以同步方式將資料表中被索引的列和主鍵列的資料自動同步到索引表中，當資料寫入資料表後，即可從索引表中查詢到資料。 indexUpdateMode：索引更新模式。可選值包括IUM_ASYNC_INDEX和IUM_SYNC_INDEX。當不設定indexUpdateMode或者設定indexUpdateMode為IUM_ASYNC_INDEX時，表示非同步更新。使用全域二級索引時，索引更新模式必須設定為非同步更新（IUM_ASYNC_INDEX）。當設定indexUpdateMode為IUM_SYNC_INDEX時，表示同步更新。使用本地二級索引時，索引更新模式必須設定為同步更新（IUM_SYNC_INDEX）。

樣本

建立資料表時不帶索引

private static void createTable(SyncClient client) {
    TableMeta tableMeta = new TableMeta("TableName");
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema(PRIMARY_KEY_NAME, PrimaryKeyType.STRING)); //為主表添加主鍵列。
    
    int timeToLive = -1; //資料的到期時間，單位為秒，-1表示永不到期。帶索引表的資料表資料生命週期必須設定為-1。
    int maxVersions = 3; //儲存的最大版本數，1表示每列上最多儲存一個版本即儲存最新的版本。帶索引表的資料表最大版本數必須設定為1。
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
        
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
    request.setReservedThroughput(new ReservedThroughput(new CapacityUnit(0, 0))); //設定預留讀寫輸送量，容量型執行個體中的資料表只能設定為0，高效能執行個體中的資料表可以設定為非零值。
    client.createTable(request);
}

建立資料表時帶索引且索引類型為全域二級索引

private static void createTable(SyncClient client) {
    TableMeta tableMeta = new TableMeta("TableName");
    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)); //為資料表添加預定義列。

    int timeToLive = -1; //資料的到期時間，單位為秒，-1表示永不到期。帶索引表的資料表資料生命週期必須設定為-1。
    int maxVersions = 1; //儲存的最大版本數，1表示每列上最多儲存一個版本即儲存最新的版本。帶索引表的資料表最大版本數必須設定為1。
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);

    ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
    IndexMeta indexMeta = new IndexMeta("IndexName");
    indexMeta.addPrimaryKeyColumn("defcol1"); //為索引表添加主鍵列。
    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("TableName");
    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)); //為資料表添加預定義列。

    int timeToLive = -1; //資料的到期時間，單位為秒，-1表示永不到期。帶索引表的資料表資料生命週期必須設定為-1。
    int maxVersions = 1; //儲存的最大版本數，1表示每列上最多儲存一個版本即儲存最新的版本。帶索引表的資料表最大版本數必須設定為1。
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);

    ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
    IndexMeta indexMeta = new IndexMeta("IndexName");
    indexMeta.setIndexType(IT_LOCAL_INDEX);     //設定索引類型為本地二級索引（IT_LOCAL_INDEX）。
    indexMeta.setIndexUpdateMode(IUM_SYNC_INDEX);  //設定索引更新模式為同步更新（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);
}

建立資料表時開啟局部事務功能

private static void createTable(SyncClient client) {
    TableMeta tableMeta = new TableMeta("TableName");
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER));

    int timeToLive = -1; //資料的到期時間，單位為秒，-1表示永不到期。帶索引表的資料表資料生命週期必須設定為-1。
    int maxVersions = 1; //儲存的最大版本數，1表示每列上最多儲存一個版本即儲存最新的版本。帶索引表的資料表最大版本數必須設定為1。
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);

    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
    request.setLocalTxnEnabled(true); //開啟局部事務。當為資料表配置了主鍵自增列時，此配置無效。

    client.createTable(request);
}