全部產品
Search

搜尋本產品

    Tablestore：建立資料表

    文件中心

    Tablestore：建立資料表

    更新時間：Jul 03, 2024

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

    注意事項

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

    • 建立資料表時必須指定資料表的主鍵。主鍵包含1個~4個主鍵列，每一個主鍵列都包括名稱和類型。

    • 如果在系統設計中存在使用主鍵列自增功能的情境，例如電商網站的商品ID、大型網站的使用者ID、論壇文章的ID、聊天工具的訊息ID等，您可以通過在建立資料表時配置主鍵列自增實現。具體操作，請參見主鍵列自增。

    前提條件

    介面

    //說明：根據指定的表結構資訊建立資料表。
//request是CreateTableRequest類的執行個體，它包含TableMeta和TableOption以及ReservedThroughput。
//請參見TableMeta類的文檔。
//當建立一個資料表後，通常需要等待幾秒鐘時間使partition load完成，才能進行各種操作。
//返回：CreateTableResponse
CreateTable(request *CreateTableRequest) (*CreateTableResponse, error)

    參數

    請結合下表參數說明和建立資料表APICreateTable中的訊息結構介紹進行代碼中的參數配置。

    參數

    是否必選

    說明

    TableMeta

    是

    資料表的結構資訊。包括如下內容：

    • TableName（必選）：資料表名稱。

    • PrimaryKey（可選）：資料表的主鍵定義。

      說明

      屬性列不需要定義。Table Store每行的資料列都可以不同，屬性列的列名在寫入時指定。

      • Table Store可包含1個~4個主鍵列。主鍵列是有順序的，與使用者添加的順序相同，例如PRIMARY KEY（A, B, C）與PRIMARY KEY（A, C, B）是不同的兩個主鍵結構。Table Store會按照主鍵的大小為行排序。

      • 第一列主鍵作為分區鍵。分區鍵相同的資料會存放在同一個分區內，所以相同分區鍵下的資料盡量不要超過10 GB，否則會導致單分區過大，無法分裂。另外，資料的讀/寫訪問最好在不同的分區鍵上均勻分布，有利於負載平衡。

    • DefinedColumns（可選）：預先定義一些非主鍵列以及其類型，可以作為索引表的屬性列或索引列。

      重要

      如果要在建立資料表時同時配置二級索引，則需要配置此項。

    TableOption

    否

    資料表的配置資訊，可選配置。更多資訊，請參見資料版本和生命週期。

    配置資訊包括如下內容：

    • TimeToAlive：資料生命週期，即資料的到期時間。當資料的儲存時間超過設定的資料生命週期時，系統會自動清理超過資料生命週期的資料。

      資料生命週期至少為86400秒（一天）或-1（資料永不到期）。

      建立資料表時，如果希望資料永不到期，可以設定資料生命週期為-1；建立資料表後，可以通過UpdateTable介面動態修改資料生命週期。

      單位為秒。

      重要

      如果需要使用索引，則資料生命週期必須滿足如下條件中的任意一個。

      • 資料表的資料生命週期為-1（資料永不到期）。

      • 資料表的資料生命週期不為-1時，資料表為禁止更新狀態。

    • MaxVersion：最大版本數，即屬性列能夠保留資料的最大版本個數。當屬性列資料的版本個數超過設定的最大版本數時，系統會自動刪除較早版本的資料。

      建立資料表時，可以自訂屬性列的最大版本數；建立資料表後，可以通過UpdateTable介面動態修改資料表的最大版本數。

      重要

      如果需要使用索引，則最大版本數必須設定為1。

    • DeviationCellVersionInSec：有效版本偏差，即寫入資料的時間戳記與系統目前時間的偏差允許最大值。只有當寫入資料所有列的版本號碼與寫入時時間的差值在資料有效版本偏差範圍內，資料才能成功寫入。

      屬性列的有效版本範圍為[max{資料寫入時間-有效版本偏差,資料寫入時間-資料生命週期}，資料寫入時間+有效版本偏差)。

      建立資料表時，如果未設定有效版本偏差，系統會使用預設值86400；建立資料表後，可以通過UpdateTable介面動態修改有效版本偏差。

    ReservedThroughput

    否

    為資料表配置預留讀輸送量或預留寫輸送量， 可選配置。

    重要

    容量型執行個體中的資料表的預留讀/寫輸送量只能設定為0，不允許預留。

    預設值為0，即完全隨用隨付。

    單位為CU。

    • 當預留讀輸送量或預留寫輸送量大於0時，Table Store會根據配置為資料表預留相應資源，且資料表建立成功後，將會立即按照預留輸送量開始計費，超出預留的部分進行隨用隨付。更多資訊，請參見計費概述。

    • 當預留讀輸送量或預留寫輸送量設定為0時，Table Store不會為資料表預留相應資源。

    IndexMeta

    否

    索引表的結構資訊，可選配置。包括如下內容：

    重要

    如果要在建立資料表時同時配置二級索引，則需要配置此項。

    • IndexName：索引表名稱。

    • PrimaryKey：索引表的索引列，索引列為資料表主鍵和預定義列的組合。

      使用本地二級索引時，索引表的第一個主鍵列必須與資料表的第一個主鍵列相同。

    • DefinedColumns：索引表的屬性列，索引表屬性列為資料表的預定義列的組合。

    • IndexType：索引類型。可選值包括IT_GLOBAL_INDEX和IT_LOCAL_INDEX。

      • 當不設定IndexType或者設定IndexType為IT_GLOBAL_INDEX時，表示使用全域二級索引。

        使用全域二級索引時，Table Store以非同步方式將資料表中被索引的列和主鍵列的資料自動同步到索引表中，正常情況下同步延遲達到毫秒層級。

      • 當設定IndexType為IT_LOCAL_INDEX時，表示使用本地二級索引。

        使用本地二級索引時，Table Store以同步方式將資料表中被索引的列和主鍵列的資料自動同步到索引表中，當資料寫入資料表後，即可從索引表中查詢到資料。

    樣本

    建立資料表時不帶索引

    以下樣本用於建立一個含有2個主鍵列的資料表。該表的主鍵為pk0（Integer類型）和pk1（String類型），屬性列值最多保留3個版本的資料，並且資料永不到期。

    func CreateTableSample(client *tablestore.TableStoreClient, tableName string) {
    createTableRequest := new(tablestore.CreateTableRequest)
    //建立主鍵列的schema，包括PK的個數、名稱和類型。
    //第一個PK列為整數，名稱是pk0，此列同時也是分區鍵。
    //第二個PK列為字串，名稱是pk1。
    tableMeta := new(tablestore.TableMeta)
    tableMeta.TableName = tableName
    tableMeta.AddPrimaryKeyColumn("pk0", tablestore.PrimaryKeyType_INTEGER)
    tableMeta.AddPrimaryKeyColumn("pk1", tablestore.PrimaryKeyType_STRING)
    tableOption := new(tablestore.TableOption)
    tableOption.TimeToAlive = -1
    tableOption.MaxVersion = 3
    reservedThroughput := new(tablestore.ReservedThroughput)
    reservedThroughput.Readcap = 0
    reservedThroughput.Writecap = 0
    createTableRequest.TableMeta = tableMeta
    createTableRequest.TableOption = tableOption
    createTableRequest.ReservedThroughput = reservedThroughput
    _, err := client.CreateTable(createTableRequest)
    if (err != nil) {
        fmt.Println("Failed to create table with error:", err)
    } else {
        fmt.Println("Create table finished")
    }
}

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

    以下樣本用於同時建立資料表和全域二級索引。該表包含pk1（String類型）和pk2（Integer類型）兩列主鍵且包含defcol1（String類型）和defcol2（Integer類型）兩個預定義列，屬性列值只保留最新版本資料以及資料永不到期。該全域二級索引的主鍵列為defcol1、pk1和pk2，屬性列為defcol2。

    func CreateTableWithGlobalIndexSample(client *tablestore.TableStoreClient, tableName string) {
    createTableRequest := new(tablestore.CreateTableRequest)

    tableMeta := new(tablestore.TableMeta)
    tableMeta.TableName = tableName
    tableMeta.AddPrimaryKeyColumn("pk1", tablestore.PrimaryKeyType_STRING)
    tableMeta.AddPrimaryKeyColumn("pk2", tablestore.PrimaryKeyType_INTEGER)
    tableMeta.AddDefinedColumn("defcol1", tablestore.DefinedColumn_STRING)
    tableMeta.AddDefinedColumn("defcol2", tablestore.DefinedColumn_INTEGER)

    indexMeta := new(tablestore.IndexMeta) //建立索引表Meta。
    indexMeta.AddPrimaryKeyColumn("defcol1") //為索引表添加主鍵列。設定資料表的definedcol1列作為索引表的主鍵。
    indexMeta.AddDefinedColumn("defcol2") //為索引表添加屬性列。設定資料表的definedcol2列作為索引表的屬性列。
    indexMeta.IndexName = "indexSample"

    tableOption := new(tablestore.TableOption)
    tableOption.TimeToAlive = -1 //資料的到期時間，單位為秒，-1表示永不到期。帶索引表的資料表資料生命週期必須設定為-1。
    tableOption.MaxVersion = 1 //儲存的最大版本數，1表示每列上最多儲存一個版本即儲存最新的版本。帶索引表的資料表最大版本數必須設定為1。
    reservedThroughput := new(tablestore.ReservedThroughput)

    createTableRequest.TableMeta = tableMeta
    createTableRequest.TableOption = tableOption
    createTableRequest.ReservedThroughput = reservedThroughput
    createTableRequest.AddIndexMeta(indexMeta)

    _, err := client.CreateTable(createTableRequest)
    if err != nil {
        fmt.Println("Failed to create table with error:", err)
    } else {
        fmt.Println("Create table finished")
    }
}

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

    以下樣本用於同時建立資料表和本地二級索引。該表的主鍵為pk1（String類型）和pk2（Integer類型）且包括defcol1（String類型）和defcol2（Integer類型）兩個預定義列，屬性列值只保留最新版本資料以及資料永不到期。該本地二級索引的主鍵列為pk1、defcol1和pk2，屬性列為defcol2。

    func CreateTableWithLocalIndexSample(client *tablestore.TableStoreClient, tableName string) {
    createTableRequest := new(tablestore.CreateTableRequest)

    tableMeta := new(tablestore.TableMeta)
    tableMeta.TableName = tableName
    tableMeta.AddPrimaryKeyColumn("pk1", tablestore.PrimaryKeyType_STRING)
    tableMeta.AddPrimaryKeyColumn("pk2", tablestore.PrimaryKeyType_INTEGER)
    tableMeta.AddDefinedColumn("defcol1", tablestore.DefinedColumn_STRING)
    tableMeta.AddDefinedColumn("defcol2", tablestore.DefinedColumn_INTEGER)

    indexMeta := new(tablestore.IndexMeta) //建立索引表Meta。
    indexMeta.IndexType = tablestore.IT_LOCAL_INDEX //設定索引類型為本地二級索引（IT_LOCAL_INDEX）。

    indexMeta.AddPrimaryKeyColumn("pk1") //為索引表添加主鍵列。索引表的第一列主鍵必須與資料表的第一列主鍵相同。
    indexMeta.AddPrimaryKeyColumn("defcol1") //為索引表添加主鍵列。設定資料表的definedcol1列作為索引表的主鍵。
    indexMeta.AddDefinedColumn("defcol2") //為索引表添加屬性列。設定資料表的definedcol2列作為索引表的屬性列。
    indexMeta.IndexName = "indexSample"

    tableOption := new(tablestore.TableOption)
    tableOption.TimeToAlive = -1 //資料的到期時間，單位為秒，-1表示永不到期。帶索引表的資料表資料生命週期必須設定為-1。
    tableOption.MaxVersion = 1 //儲存的最大版本數，1表示每列上最多儲存一個版本即儲存最新的版本。帶索引表的資料表最大版本數必須設定為1。
    reservedThroughput := new(tablestore.ReservedThroughput)

    createTableRequest.TableMeta = tableMeta
    createTableRequest.TableOption = tableOption
    createTableRequest.ReservedThroughput = reservedThroughput
    createTableRequest.AddIndexMeta(indexMeta)

    _, err := client.CreateTable(createTableRequest)
    if err != nil {
        fmt.Println("Failed to create table with error:", err)
    } else {
        fmt.Println("Create table finished")
    }
}

    相關文檔

    • 關於API說明的更多資訊，請參見CreateTable。詳細代碼請參見CreateTable@GitHub。

    • 如果要讀寫表中的資料，您可以通過調用讀寫資料介面實現。具體操作，請參見基礎資料操作。

    • 如果要修改表的資料生命週期、最大版本數等資訊，您可以通過更新表實現。具體操作，請參見更新表。

    • 為資料表開啟局部事務後，您可以建立局部事務用於讀寫局部事務範圍內的資料。具體操作，請參見局部事務。

    • 如果要查看執行個體中已存在的所有表，您可以通過列出表名稱來實現。具體操作，請參見列出表名稱。

    • 如果要查看錶的最大版本數、資料生命週期等配置資訊，您可以通過查看錶描述資訊實現。具體操作，請參見查詢表描述資訊。

    • 如果要使用二級索引加速資料查詢，但是在建立資料表時未設定預定義列，您可以在建立資料表後為資料表增加或刪除預定義列。具體操作，請參見預定義列操作。

    • 如果不再使用資料表，您可以刪除資料表。具體操作，請參見刪除資料表。