調用UpdateRow更新指定行的資料 - Tablestore

調用UpdateRow介面更新指定行的資料。

說明

如果指定行不存在，則新增一行；如果指定行存在，則根據請求的內容在該行中新增、修改或者刪除指定列的值。

請求訊息結構

message UpdateRowRequest {
    required string table_name = 1;
    required bytes row_change = 2;
    required Condition condition = 3;
    optional ReturnContent return_content = 4;
    optional string transaction_id = 5;
}

名稱	類型	是否必選	描述
table_name	string	是	請求更新資料的表名。
row_change	bytes	是	更新的資料，包括主鍵和屬性列，由Plainbuffer編碼。更多資訊，請參見Plainbuffer。該行本次需要更新的全部屬性列，Table Store會根據row_change中UpdateType的內容在該行中新增、修改或者刪除指定列的值。該行已存在的且不在row_change中的列將不受影響。 UpdateType的取值範圍如下： PUT：此時value必須為有效屬性列值。如果該列不存在，則新增一列；如果該列存在，則覆蓋該列。 DELETE：此時該value必須為空白，需要指定timestamp。表示刪除該列特定版本的資料。 DELETE_ALL：此時該value和timestamp都必須為空白。表示刪除該列所有版本的資料。說明刪除本行的全部屬性列不等同於刪除本行。如果需要刪除本行，請使用DeleteRow操作。
condition	Condition	是	在資料更新前是否進行存在性檢查。取值範圍如下： IGNORE（預設）：不做行存在性檢查。如果忽略該行是否存在，則無論該行是否存在，都不會因此導致本次操作失敗。 EXPECT_EXIST：期望行存在。如果期待該行存在但該行不存在，則本次更新操作會失敗，返回錯誤。
return_content	ReturnContent	否	寫入成功後返回的資料類型。目前僅支援返回主鍵，主要用於主鍵列自增功能中。
transaction_id	string	否	局部事務ID。當使用局部事務功能更新資料時必須設定此參數。

響應訊息結構

message UpdateRowResponse {
    required ConsumedCapacity consumed = 1;
    optional bytes row = 2;
}

名稱

類型

描述

consumed

ConsumedCapacity

本次操作消耗的服務能力單元。更多資訊，請參見服務能力單元。

row

bytes

當設定了return_content後，返回的資料。如果未設定return_content或者沒傳回值，此處為NULL。

返回的資料為Plainbuffer格式。關於Plainbuffer編碼的更多資訊，請參見Plainbuffer。

使用SDK

您可以使用如下語言的SDK更新單行資料。

服務能力單元消耗

當更新的行不存在時，根據指定的條件檢查不同，更新資料消耗的服務能力單元不同。
- 如果指定條件檢查為IGNORE，則消耗寫服務能力單元的數值為本行的主鍵資料大小與要更新的屬性列資料大小之和除以4 KB向上取整。如果UpdateRow中包含有需要刪除的屬性列，只有其列名長度計入該屬性列資料大小。
- 如果指定條件檢查為EXPECT_EXIST，則本次插入失敗並且消耗1單位寫CU和1單位讀CU。
當更新的行存在時，根據指定的條件檢查不同，更新資料消耗的服務能力單元不同。
- 如果指定條件檢查為IGNORE，則消耗寫服務能力單元的數值為本行的主鍵資料大小與要更新的屬性列資料大小之和除以4 KB向上取整。如果UpdateRow中包含有需要刪除的屬性列，只有其列名長度計入該屬性列資料大小。
- 如果指定條件檢查為EXPECT_EXIST，則除了需要消耗在條件檢查為IGNORE情況下的寫CU外，還需消耗該行主鍵資料大小除以4 KB向上取整的讀CU。
關於資料大小的計算請參見產品定價。
如果請求逾時，結果未定義，則服務能力單元有可能被消耗，也可能未被消耗。
如果返回內部錯誤（HTTP狀態代碼：5XX），則此次操作不消耗服務能力單元，其他錯誤情況1個寫服務能力單元和1個讀服務能力單元。