建立資料表 - Tablestore

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

说明

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

前提條件

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

介面

/**
 * 建立資料表，並設定主鍵的個數、名稱、順序和類型，以及預留讀寫輸送量、TTL和stream選項。
 * @api
 * @param [] $request 請求參數。
 * @return [] 返回為空白。CreateTable成功時不返回任何資訊，此處返回一個空的array，與其他API保持一致。
 * @throws OTSClientException 當參數檢查出錯或服務端返回校正出錯時拋出異常。
 * @throws OTSServerException 當OTS服務端返回錯誤時拋出異常。
 */
public function createTable(array $request);

參數

請求參數


參數	說明
table_meta	資料表的結構資訊，包括如下內容： table_name：資料表名稱。 primary_key_schema：資料表的主鍵定義。更多資訊，請參見主鍵和屬性。说明屬性列不需要定義。Tablestore每行的資料列都可以不同，屬性列的列名在寫入時指定。每一項的順序是主鍵名，主鍵類型PrimaryKeyType，主鍵設定PrimaryKeyOption（可選）。 PrimaryKeyType可以是INTEGER、STRING（UTF-8編碼字串）、BINARY三種，分別用`PrimaryKeyTypeConst::CONST_INTEGER`、`PrimaryKeyTypeConst::CONST_STRING`、`PrimaryKeyTypeConst::CONST_BINARY`表示。 PrimaryKeyOption可以是PK_AUTO_INCR（自增列），用`PrimaryKeyOptionConst::CONST_PK_AUTO_INCR`表示。更多資訊，請參見主鍵列自增。 Tablestore可包含1個~4個主鍵列。主鍵列是有順序的，與使用者添加的順序相同。例如PRIMARY KEY（A, B, C）與PRIMARY KEY（A, C, B）是不同的兩個主鍵結構。Tablestore會按照整個主鍵的大小對行進行排序。第一列主鍵作為分區鍵。分區鍵相同的資料會存放在同一個分區內，所以相同分區鍵下最好不要超過10 GB以上資料，否則會導致單分區過大，無法分裂。另外，資料的讀/寫訪問最好在不同的分區鍵上均勻分布，有利於負載平衡。 defined_column：預先定義一些非主鍵列以及其類型，可以作為索引表的屬性列或索引列。
table_options	資料表的配置資訊。更多資訊，請參見資料版本和生命週期。配置資訊包括如下內容： time_to_live：資料生命週期，即資料的到期時間。當資料的儲存時間超過設定的資料生命週期時，系統會自動清理超過資料生命週期的資料。資料生命週期至少為86400秒（一天）或-1（資料永不到期）。建立資料表時，如果希望資料永不到期，可以設定資料生命週期為-1；建立資料表後，可以通過UpdateTable介面動態修改資料生命週期。單位為秒。说明如果需要使用索引，則資料生命週期必須設定為-1（資料永不到期）。 max_versions：最大版本數，即屬性列能夠保留資料的最大版本個數。當屬性列資料的版本個數超過設定的最大版本數時，系統會自動刪除較早版本的資料。建立資料表時，可以自訂屬性列的最大版本數；建立資料表後，可以通過UpdateTable介面動態修改資料表的最大版本數。说明如果需要使用索引，則最大版本數必須設定為1。 deviation_cell_version_in_sec：有效版本偏差，即寫入資料的時間戳記與系統目前時間的偏差允許最大值。只有當寫入資料所有列的版本號碼與寫入時時間的差值在資料有效版本偏差範圍內，資料才能成功寫入。屬性列的有效版本範圍為[max{資料寫入時間-有效版本偏差,資料寫入時間-資料生命週期}，資料寫入時間+有效版本偏差)。建立資料表時，如果未設定有效版本偏差，系統會使用預設值86400；建立資料表後，可以通過UpdateTable介面動態修改有效版本偏差。單位為秒。 allow_update：是否允許UpdateRow相關更新寫入操作。預設值為true，表示允許UpdateRow相關更新寫入操作；當設定allow_update為false時，表示禁止UpdateRow相關更新寫入操作。
reserved_throughput	為資料表配置預留讀輸送量或預留寫輸送量。容量型執行個體中的資料表的預留讀/寫輸送量只能設定為0，不允許預留。預設值為0，即完全隨用隨付。單位為CU。當預留讀輸送量或預留寫輸送量大於0時，Tablestore會根據配置為資料表預留相應資源，且資料表建立成功後，將會立即按照預留輸送量開始計費，超出預留的部分進行隨用隨付。更多資訊，請參見計費概述。當預留讀輸送量或預留寫輸送量設定為0時，Tablestore不會為資料表預留相應資源。
stream_spec	Stream相關設定（可選配置）。 enable_stream：資料表是否開啟Stream。 expiration_time：Stream資料的到期時間，較早的修改記錄將會被刪除，單位為小時。只有當設定enable_stream為true時才能設定此參數。
index_metas	索引表的結構資訊，每個index_meta都包括如下內容： name：索引表名稱。 primary_key：索引表的索引列，索引列為資料表主鍵和預定義列的任意組合。 defined_column：索引表的屬性列，索引表屬性列為資料表的預定義列的組合。 index_update_mode：索引表更新模式。可選值包括`IndexUpdateModeConst::ASYNC_INDEX`和`IndexUpdateModeConst::SYNC_INDEX`。當不設定index_update_mode或者設定index_update_mode為`IndexUpdateModeConst::ASYNC_INDEX`時，表示非同步更新。使用全域二級索引時，索引更新模式必須設定為非同步更新（`IndexUpdateModeConst::ASYNC_INDEX`）。當設定index_update_mode為`IndexUpdateModeConst::SYNC_INDEX`時，表示同步更新。使用本地二級索引時，索引更新模式必須設定為同步更新（`IndexUpdateModeConst::SYNC_INDEX`）。 index_type：索引表類型。可選值包括`IndexTypeConst::GLOBAL_INDEX`和`IndexTypeConst::LOCAL_INDEX`。當不設定index_type或者設定index_type為`IndexTypeConst::GLOBAL_INDEX`時，表示使用全域二級索引。使用全域索引時，Tablestore以非同步方式將資料表中被索引的列和主鍵列的資料自動同步到索引表中，正常情況下同步延遲達到毫秒層級。當設定index_type為`IndexTypeConst::LOCAL_INDEX`時，表示使用本地二級索引。使用本地二級索引時，Tablestore以同步方式將資料表中被索引的列和主鍵列的資料自動同步到索引表中，當資料寫入資料表後，即可從索引表中查詢到資料。

請求格式

$result = $client->createTable([
    'table_meta' => [                  //設定資料表結構資訊，必須配置。
        'table_name' => '<string>', 
        'primary_key_schema' => [
            ['<string>', <PrimaryKeyType>], 
            ['<string>', <PrimaryKeyType>],
            ['<string>', <PrimaryKeyType>, <PrimaryKeyOption>]
        ]
    ], 
    'reserved_throughput' => [         //設定預留讀寫輸送量，必須配置。
        'capacity_unit' => [
            'read' => <integer>, 
            'write' => <integer>
        ]
    ],
    'table_options' => [              //設定資料表配置資訊，必須配置。
        'time_to_live' => <integer>,   
        'max_versions' => <integer>,    
        'deviation_cell_version_in_sec' => <integer>  
    ],
    'stream_spec' => [
        'enable_stream' => true || false,
        'expiration_time' => <integer>
    ]
]);

響應參數
返回為空白，出錯時會拋出異常。
結果格式
```
[]      
```

樣本

建立資料表時不帶索引

建立一個有3個主鍵列，預留讀/寫輸送量為(0, 0)的資料表，TTL永不到期，儲存兩個版本的資料，同時開啟Stream。

//建立主鍵列的schema，包括主鍵的個數、名稱和類型。
//第一個主鍵列為整數，名稱是pk0，此主鍵列也是分區鍵。
//第二個主鍵列為字串，名稱是pk1。
//第三個主鍵列為二進位，名稱是pk2。
$result = $client->createTable([
    'table_meta' => [
        'table_name' => 'SampleTable', 
        'primary_key_schema' => [
            ['PK0', PrimaryKeyTypeConst::CONST_INTEGER], 
            ['PK1', PrimaryKeyTypeConst::CONST_STRING],
            ['PK2', PrimaryKeyTypeConst::CONST_BINARY]
        ]
    ], 
    'reserved_throughput' => [
        'capacity_unit' => [
            'read' => 0, 
            'write' => 0
        ]
    ],
    'table_options' => [
        'time_to_live' => -1,   
        'max_versions' => 2,    
        'deviation_cell_version_in_sec' => 86400  
    ],
    'stream_spec' => [
        'enable_stream' => true,
        'expiration_time' => 24
    ]
]);

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

$request = array (
    'table_meta' => array (
        'table_name' => 'SampleTable', //資料表名稱。
        'primary_key_schema' => array (
            array('PK0', PrimaryKeyTypeConst::CONST_INTEGER),
            array('PK1', PrimaryKeyTypeConst::CONST_STRING)
        ),
        'defined_column' => array(
            array('col1', DefinedColumnTypeConst::DCT_STRING),
            array('col2', DefinedColumnTypeConst::DCT_INTEGER)
        )
    ),

    'reserved_throughput' => array (
        'capacity_unit' => array (
            'read' => 0, //設定預留讀寫輸送量為0個讀CU和0個寫CU。
            'write' => 0
        )
    ),
    'table_options' => array(
        'time_to_live' => -1,   //資料的到期時間，單位為秒，-1表示永不到期。帶索引表的資料表資料生命週期必須設定為-1。
        'max_versions' => 1,    //儲存的最大版本數，1表示每列上最多儲存一個版本即儲存最新的版本。帶索引表的資料表最大版本數必須設定為1。
        'deviation_cell_version_in_sec' => 86400  //資料有效版本偏差，單位為秒。
    ),
    'index_metas' => array(
        array(
            'name' => 'indexName1',
            'primary_key' => array('col1'),
            'defined_column' => array('col2'),
            'index_type' => IndexTypeConst::GLOBAL_INDEX,
            'index_update_mode' => IndexUpdateModeConst::ASYNC_INDEX
        ),
        array(
            'name' => 'indexName2',
            'primary_key' => array('PK1'),
            'defined_column' => array('col1', 'col2')
        )
    )
);
$this->otsClient->createTable($request);

建立資料表時帶索引且索引為本地二級索引

$request = array (
    'table_meta' => array (
        'table_name' => 'SampleTable', //資料表名稱。
        'primary_key_schema' => array (
            array('PK0', PrimaryKeyTypeConst::CONST_INTEGER),
            array('PK1', PrimaryKeyTypeConst::CONST_STRING)
        ),
        'defined_column' => array(
            array('col1', DefinedColumnTypeConst::DCT_STRING),
            array('col2', DefinedColumnTypeConst::DCT_INTEGER)
        )
    ),

    'reserved_throughput' => array (
        'capacity_unit' => array (
            'read' => 0, //設定預留讀寫輸送量為0個讀CU和0個寫CU。
            'write' => 0
        )
    ),
    'table_options' => array(
        'time_to_live' => -1,   //資料的到期時間，單位為秒，-1表示永不到期。帶索引表的資料表資料生命週期必須設定為-1。
        'max_versions' => 1,    //儲存的最大版本數，1表示每列上最多儲存一個版本即儲存最新的版本。帶索引表的資料表最大版本數必須設定為1。
        'deviation_cell_version_in_sec' => 86400  //資料有效版本偏差，單位為秒。
    ),
    'index_metas' => array(
        array(
            'name' => 'indexName3',
            'primary_key' => array('PK0', 'col1'),
            'defined_column' => array('col2'),
            'index_type' => IndexTypeConst::LOCAL_INDEX,
            'index_update_mode' => IndexUpdateModeConst::SYNC_INDEX
        ),
        array(
            'name' => 'indexName4',
            'primary_key' => array('PK0', 'col2'),
            'defined_column' => array('col1'),
            'index_type' => IndexTypeConst::LOCAL_INDEX,
            'index_update_mode' => IndexUpdateModeConst::SYNC_INDEX
        )
    )
);
$this->otsClient->createTable($request);