全部產品
Search
文件中心

Tablestore:建立資料表

更新時間:Nov 13, 2024

本文將通過參數說明和範例程式碼為您介紹如何使用 PHP SDK 建立資料表。在建立資料表時,您需要指定資料表的結構資訊和配置資訊。高效能型執行個體中的資料表還可以根據需要設定預留讀寫輸送量。

注意事項

  • 建立資料表後需要幾秒鐘進行載入,在此期間對該資料表的讀寫資料操作均會失敗。請等待資料表載入完畢後再進行資料操作。

  • 如果您有主鍵資料自增的需求,例如電商網站的商品 ID、論壇文章的 ID 等情境,可以在建立資料時配置主鍵列自增。具體操作,請參見主鍵列自增

前提條件

介面

/**
 * 根據指定表結構資訊建立資料表。
 * 當建立一個資料表後,通常需要等待幾秒鐘時間使partition load完成,才能進行各種操作。
 * @param [] $request 請求參數。
 * @return [] 返回為空白。
 * @throws OTSClientException 當參數檢查出錯或服務端返回校正出錯時拋出異常。
 * @throws OTSServerException 當OTS服務端返回錯誤時拋出異常。
 */
public function createTable(array $request);           

參數說明

request包含以下參數:

參數

說明

table_meta(必選

資料表的結構資訊,包括如下內容:

  • table_name(必選):資料表名稱。

  • primary_key_schema(必選):資料表的主鍵定義。更多資訊,請參見核心組件

    • 主鍵資料類型可以為 STRING、INTEGER 或 BINARY。

    • 可以設定 1~4 個主鍵列。Table Store將按照設定的順序產生主鍵,預設按升序進行排序。

    • 第一個主鍵列將作為分區鍵。

  • defined_column(可選):預定義列資訊。資料類型可以為 STRING、INTEGER、BLOB、DOUBLE 或 BOOLEAN。

    說明
    • 預定義列是預先定義的一些非主鍵列,通常被用作二級索引的主鍵列或預定義列,以實現快速查詢資料的需求。

    • 屬性列在建立表時無需定義,您可以在寫入資料時為每行資料指定不同的屬性列和列名。

table_options(必選

資料表的配置資訊,包括如下內容:

  • time_to_live(必選):資料生命週期,即資料的到期時間,單位為秒。

    資料生命週期的取值最低為 86400 秒(一天),也可設定為 -1(永不到期)。

    重要

    如果要使用多元索引或二級索引,必須將資料生命週期設定為 -1,或者將 allow_update 參數設定為 false。

  • max_versions(必選):最大版本數,即屬性列能夠保留資料的最大版本個數。

    重要

    如果要使用多元索引或二級索引,最大版本數必須設定為 1。

  • deviation_cell_version_in_sec(必選):有效版本偏差,即寫入資料的時間戳記與系統目前時間的偏差允許最大值,單位為秒。

    屬性列的有效取值範圍是一個左閉右開的區間:[max{資料寫入時間-有效版本偏差,資料寫入時間-資料生命週期},資料寫入時間+有效版本偏差)

  • allow_update(可選):是否允許更新。預設為true。

    重要

    如果要使用多元索引的生命週期功能,必須設定此參數為 false。如果您需要更新資料,可使用 PutRow 介面寫入資料。

index_metas(可選)

索引列表。每個索引包含以下內容:

  • name(必選):索引名稱。

  • primary_key(必選):索引的主鍵列。可以由資料表的主鍵列和預定義列組成。

    重要

    使用本地二級索引時,索引第一個主鍵列必須是資料表的第一個主鍵列。

  • defined_column(必選):索引的預定義列。可以由資料表的預定義列組成。

  • index_type(可選):索引類型。取值範圍如下:

    • GLOBAL_INDEX(預設值):全域二級索引。

    • LOCAL_INDEX:本地二級索引。

  • index_update_mode(可選):索引更新模式。取值範圍如下:

    • ASYNC_INDEX(預設值):非同步更新。

      說明

      使用全域二級索引時,索引更新模式必須設定為非同步更新。

    • SYNC_INDEX:同步更新。

      說明

      使用本地二級索引時,索引更新模式必須設定為同步更新。

reserved_throughput(必選

預留讀寫輸送量,單位為 CU。預設值為 0。

重要

僅高效能型執行個體支援設定資料表的預留讀寫輸送量為非零值。

stream_spec(可選)

資料表的 Stream 配置資訊,包括如下內容:

  • enable_stream(可選):是否開啟 stream。預設值為 false,即不開啟 stream。

  • expiration_time(可選):stream 到期時間,表示增量日誌到期時間長度。單位為小時,最大值為 168 小時(7 天)。

    說明

    開啟 stream 時,必須設定 expirationTime 參數。

樣本

建立資料表

以下樣本用於建立資料表。

$result = $client->createTable([
    'table_meta' => [
        //設定資料表名稱。
        'table_name' => '<TABLE_NAME>', 
        //設定資料表主鍵列。主鍵為pk1(String類型)和pk2(Integer類型),其中pk1主鍵列為分區鍵,pk2主鍵列為自增列。
        'primary_key_schema' => [
            ['pk1', PrimaryKeyTypeConst::CONST_STRING],
            ['pk2', PrimaryKeyTypeConst::CONST_INTEGER, PrimaryKeyOptionConst::CONST_PK_AUTO_INCR]
        ]
    ], 
    'table_options' => [
        //資料的到期時間,-1表示永不到期。
        'time_to_live' => -1, 
        //最大版本數,屬性列值最多保留1個版本,即儲存最新的版本。
        'max_versions' => 1,   
        //有效版本偏差,寫入資料的時間戳記與系統目前時間的偏差不能超過86400秒(即1天)。
        'deviation_cell_version_in_sec' => 86400  
    ],
    'reserved_throughput' => [
        //設定預留讀寫輸送量,容量型執行個體中的資料表只能設定為0,高效能型執行個體中的資料表可以設定為非零值。
        'capacity_unit' => [
            'read' => 0, 
            'write' => 0
        ]
    ]
]);

建立資料表時配置二級索引

建立資料表時配置全域二級索引

以下樣本用於同時建立資料表和全域二級索引。

$request = array (
    'table_meta' => array (
        //設定資料表名稱。
        'table_name' => '<TABLE_NAME>',
        //設定資料表主鍵列。主鍵為pk1(String類型)和pk2(Integer類型)。
        'primary_key_schema' => array (
            array('pk1', PrimaryKeyTypeConst::CONST_STRING),
            array('pk2', PrimaryKeyTypeConst::CONST_INTEGER)
        ),
        //設定資料表預定義列。預定義列為defcol1(String類型)和defcol2(Integer類型)。
        'defined_column' => array(
            array('defcol1', DefinedColumnTypeConst::DCT_STRING),
            array('defcol2', DefinedColumnTypeConst::DCT_INTEGER)
        )
    ),
    'table_options' => [
        //資料的到期時間,-1表示永不到期。
        'time_to_live' => -1, 
        //最大版本數,屬性列值最多保留1個版本,即儲存最新的版本。
        'max_versions' => 1,   
        //有效版本偏差,寫入資料的時間戳記與系統目前時間的偏差不能超過86400秒(即1天)。
        'deviation_cell_version_in_sec' => 86400  
    ],
    'reserved_throughput' => array (
        //設定預留讀寫輸送量,容量型執行個體中的資料表只能設定為0,高效能型執行個體中的資料表可以設定為非零值。
        'capacity_unit' => array (
            'read' => 0,
            'write' => 0
        )
    ),
    'index_metas' => array(
        array(
            //設定索引名稱。
            'name' => '<INDEX_NAME>',
            //為索引添加主鍵。主鍵列為defcol1、pk1和pk2。 
            'primary_key' => array('defcol1', 'pk1', 'pk2'),
            //為索引添加預定義列。預定義列為defcol2。
            'defined_column' => array('defcol2'),
            //設定索引類型為全域二級索引。 
            'index_type' => IndexTypeConst::GLOBAL_INDEX,
            //設定索引更新模式為非同步更新。 
            'index_update_mode' => IndexUpdateModeConst::ASYNC_INDEX
        ),
    )
);

//調用建立表方法。 
$result = $client->createTable($request);

建立資料表時配置本地二級索引

以下樣本用於同時建立資料表和本地二級索引。

$request = array (
    'table_meta' => array (
        //設定資料表名稱。
        'table_name' => '<TABLE_NAME>',
        //設定資料表主鍵列。主鍵為pk1(String類型)和pk2(Integer類型)。
        'primary_key_schema' => array (
            array('pk1', PrimaryKeyTypeConst::CONST_STRING),
            array('pk2', PrimaryKeyTypeConst::CONST_INTEGER)
        ),
        //設定資料表預定義列。預定義列為defcol1(String類型)和defcol2(Integer類型)。
        'defined_column' => array(
            array('defcol1', DefinedColumnTypeConst::DCT_STRING),
            array('defcol2', DefinedColumnTypeConst::DCT_INTEGER)
        )
    ),
    'table_options' => [
        //資料的到期時間,-1表示永不到期。
        'time_to_live' => -1, 
        //最大版本數,屬性列值最多保留1個版本,即儲存最新的版本。
        'max_versions' => 1,   
        //有效版本偏差,寫入資料的時間戳記與系統目前時間的偏差不能超過86400秒(即1天)。
        'deviation_cell_version_in_sec' => 86400  
    ],
    'reserved_throughput' => array (
        //設定預留讀寫輸送量,容量型執行個體中的資料表只能設定為0,高效能型執行個體中的資料表可以設定為非零值。
        'capacity_unit' => array (
            'read' => 0,
            'write' => 0
        )
    ),
    'index_metas' => array(
        array(
            //設定索引名稱。
            'name' => '<INDEX_NAME>',
            //為索引添加主鍵。主鍵列為pk1、defcol1和pk2。
            'primary_key' => array('pk1', 'defcol1', 'pk2'),
            //為索引添加預定義列。預定義列為defcol2。
            'defined_column' => array('defcol2'),
            //設定索引類型為本地二級索引。 
            'index_type' => IndexTypeConst::LOCAL_INDEX,
            //設定索引更新模式為同步更新。 
            'index_update_mode' => IndexUpdateModeConst::SYNC_INDEX
        ),
    )
);

//調用建立表方法。 
$result = $client->createTable($request);

相關文檔