全部產品
Search
文件中心

Tablestore:寫入資料

更新時間:Jun 30, 2024

Tablestore提供了單行插入、單行更新和批量寫入的寫入方式用於寫入資料到資料表。當要寫入資料到資料表時,您需要指定完整主鍵以及要增刪改的屬性列。在高並發應用中寫入資料時,您可以配置行存在性條件或者列條件實現按照指定條件更新資料。

前提條件

  • 已初始化Client。具體操作,請參見初始化OTSClient

  • 已建立資料表並寫入資料。

插入單行資料

調用PutRow介面新寫入一行資料。如果該行已存在,則先刪除原行資料(原行的所有列以及所有版本的資料),再寫入新行資料。

介面

// @param PutRowRequest    執行PutRow操作所需參數的封裝。
// @return PutRowResponse
PutRow(request *PutRowRequest) (*PutRowResponse, error)                    

參數

參數

說明

TableName

資料表名稱。

PrimaryKey

行的主鍵。主鍵包括主鍵列名、主鍵類型和主索引值。

重要
  • 設定的主鍵個數和類型必須和資料表的主鍵個數和類型一致。

  • 當主鍵為自增列時,只需將相應主鍵指定為自增主鍵。更多資訊,請參見主鍵列自增

Columns

行的屬性列。每一項的順序是屬性名稱、屬性值ColumnValue、屬性類型ColumnType(可選)、時間戳記(可選)。

  • 屬性名稱即屬性列的名稱,屬性類型即屬性列的資料類型。更多資訊,請參見命名規則和資料類型

    屬性類型可以是INTEGER、STRING(UTF-8編碼字串)、BINARY、BOOLEAN和DOUBLE五種,分別用ColumnType.INTEGERColumnType.STRINGColumnType.BINARYColumnType.BOOLEANColumnType.DOUBLE表示,其中BINARY不可省略,其他類型均可省略。

  • 時間戳記即資料的版本號碼,可以由系統自動產生或者自訂,如果不設定此參數,則預設由系統自動產生。更多資訊,請參見資料版本和生命週期

    • 當由系統自動產生資料的版本號碼時,系統預設將目前時間的毫秒單位時間戳記(從1970-01-01 00:00:00 UTC計算起的毫秒數)作為資料的版本號碼。

    • 當自訂資料的版本號碼時,版本號碼需要為64位的毫秒單位時間戳記且在有效版本範圍內。

Condition

使用條件更新,可以設定原行的存在性條件或者原行中某列的列值條件。更多資訊,請參見條件更新

樣本

以下樣本用於插入一行資料。

putRowRequest := new(tablestore.PutRowRequest)
putRowChange := new(tablestore.PutRowChange)
putRowChange.TableName = tableName
putPk := new(tablestore.PrimaryKey)
putPk.AddPrimaryKeyColumn("pk1", "pk1value1")
putPk.AddPrimaryKeyColumn("pk2", int64(2))
putPk.AddPrimaryKeyColumn("pk3", []byte("pk3"))
putRowChange.PrimaryKey = putPk
putRowChange.AddColumn("col1", "col1data1")
putRowChange.AddColumn("col2", int64(3))
putRowChange.AddColumn("col3", []byte("test"))
putRowChange.SetCondition(tablestore.RowExistenceExpectation_IGNORE)
putRowRequest.PutRowChange = putRowChange
_, err := client.PutRow(putRowRequest)

if err != nil {
    fmt.Println("putrow failed with error:", err)
} else {
    fmt.Println("putrow finished")
 }                    

詳細代碼請參見PutRow@GitHub

更新單行資料

調用UpdateRow介面更新一行資料,可以增加和刪除一行中的屬性列,刪除屬性列指定版本的資料,或者更新已存在的屬性列的值。如果更新的行不存在,則新增一行資料。

說明

當UpdateRow請求中只包含刪除指定的列且該行不存在時,則該請求不會新增一行資料。

介面

// 更新表中的一行資料。
// @param UpdateRowRequest      執行UpdateRow操作所需參數的封裝。
// @return UpdateRowResponse    UpdateRow操作的響應內容。
UpdateRow(request *UpdateRowRequest) (*UpdateRowResponse, error)                    

參數

參數

說明

TableName

資料表名稱。

PrimaryKey

行的主鍵。主鍵包括主鍵列名、主鍵類型和主索引值。

重要

設定的主鍵個數和類型必須和資料表的主鍵個數和類型一致。

Columns

行的屬性列。

  • 增加或更新資料時,需要設定屬性名稱、屬性值、屬性類型(可選)、時間戳記(可選)。

    屬性名稱即屬性列的名稱,屬性類型即屬性列的資料類型。更多資訊,請參見命名規則和資料類型

    時間戳記即資料的版本號碼,可以由系統自動產生或者自訂,如果不設定此參數,則預設由系統自動產生。更多資訊,請參見資料版本和生命週期

    • 當由系統自動產生資料的版本號碼時,系統預設將目前時間的毫秒單位時間戳記(從1970-01-01 00:00:00 UTC計算起的毫秒數)作為資料的版本號碼。

    • 當自訂資料的版本號碼時,版本號碼需要為64位的毫秒單位時間戳記且在有效版本範圍內。

  • 刪除屬性列特定版本的資料時,只需要設定屬性名稱和時間戳記。

    時間戳記是64位整數,單位為毫秒,表示某個特定版本的資料。

  • 刪除屬性列時,只需要設定屬性名稱。

    說明

    刪除一行的全部屬性列不等同於刪除該行,如果需要刪除該行,請使用DeleteRow操作。

Condition

使用條件更新,可以設定原行的存在性條件或者原行中某列的列值條件。更多資訊,請參見條件更新

樣本

以下樣本用於更新一行資料。

updateRowRequest := new(tablestore.UpdateRowRequest)
updateRowChange := new(tablestore.UpdateRowChange)
updateRowChange.TableName = tableName
updatePk := new(tablestore.PrimaryKey)
updatePk.AddPrimaryKeyColumn("pk1", "pk1value1")
updatePk.AddPrimaryKeyColumn("pk2", int64(2))
updatePk.AddPrimaryKeyColumn("pk3", []byte("pk3"))
updateRowChange.PrimaryKey = updatePk
updateRowChange.DeleteColumn("col1")
updateRowChange.PutColumn("col2", int64(77))
updateRowChange.PutColumn("col4", "newcol3")
updateRowChange.SetCondition(tablestore.RowExistenceExpectation_EXPECT_EXIST)
updateRowRequest.UpdateRowChange = updateRowChange
_, err := client.UpdateRow(updateRowRequest)

if err != nil {
    fmt.Println("update failed with error:", err)
} else {
    fmt.Println("update row finished")
}                    

詳細代碼請參見UpdateRow@GitHub

批量寫入資料

調用BatchWriteRow介面在一次請求中進行批量寫入操作或者一次對多張表進行寫入。

BatchWriteRow操作由多個PutRow、UpdateRow、DeleteRow子操作組成,構造子操作的過程與使用PutRow介面、UpdateRow介面和DeleteRow介面時相同。

BatchWriteRow的各個子操作獨立執行,Tablestore會分別返回各個子操作的執行結果。

注意事項

  • 由於批量寫入可能存在部分行失敗的情況,失敗行的Index及錯誤資訊在返回的BatchWriteRowResponse中,但並不拋出異常。因此調用BatchWriteRow介面時,需要檢查傳回值,判斷每行的狀態是否成功;如果不檢查傳回值,則可能會忽略掉部分操作的失敗。

    當服務端檢查到某些操作出現參數錯誤時,BatchWriteRow介面可能會拋出參數錯誤的異常,此時該請求中所有的操作都未執行。

  • BatchWriteRow操作單次支援寫入的最大行數為200行,且所有行的資料量總和不能超過4 MB。

介面

// 對多個資料表中的多行資料進行增加、刪除或者更新操作。
// @param BatchWriteRowRequest             執行BatchWriteRow操作所需參數的封裝。
// @return  BatchWriteRowResponse          BatchWriteRow操作的響應內容。
BatchWriteRow(request *BatchWriteRowRequest) (*BatchWriteRowResponse,error)                  

樣本

以下樣本用於批量寫入100行資料。

batchWriteReq := &tablestore.BatchWriteRowRequest{}
for i := 0; i < 100; i++ {
    putRowChange := new(tablestore.PutRowChange)
    putRowChange.TableName = tableName
    putPk := new(tablestore.PrimaryKey)
    putPk.AddPrimaryKeyColumn("pk1", "pk1value1")
    putPk.AddPrimaryKeyColumn("pk2", int64(i))
    putPk.AddPrimaryKeyColumn("pk3", []byte("pk3"))
    putRowChange.PrimaryKey = putPk
    putRowChange.AddColumn("col1", "fixvalue")
    putRowChange.SetCondition(tablestore.RowExistenceExpectation_IGNORE)
    batchWriteReq.AddRowChange(putRowChange)
}

response, err := client.BatchWriteRow(batchWriteReq)
if err != nil {
    fmt.Println("batch request failed with:", response)
} else {
    fmt.Println("batch write row finished")
}                   

詳細代碼請參見BatchWriteRow@GitHub

常見問題

相關文檔

  • 當要在高並發應用中實現按照指定條件更新資料時,您可以通過條件更新實現。更多資訊,請參見條件更新

  • 當要為線上應用提供即時統計功能時,例如統計文章的PV(即時瀏覽量)等,您可以通過原子計數器實現。更多資訊,請參見原子計數器

  • 當要進行單行寫或多行寫的原子操作,您可以通過局部事務實現。更多資訊,請參見局部事務

  • 寫入資料後,即可根據需要讀取或者刪除表中資料。更多資訊,請參見讀取資料刪除資料