BatchWriteRow

BatchWriteRow 是 PutRow、UpdateRow、DeleteRow 操作的集合，每個子操作獨立執行、獨立返回結果、獨立計算服務能力單元（CU）。

與逐行調用單行寫操作相比，BatchWriteRow 可有效減少請求往返次數，提升資料寫入輸送量。

請求訊息結構

message BatchWriteRowRequest {
    repeated TableInBatchWriteRowRequest tables = 1;
    optional string transaction_id = 2;
    optional bool is_atomic = 3;
}

參數	類型	是否必需	描述
tables	TableInBatchWriteRowRequest	是	指定需要執行寫操作的行資訊。以下任一情況將返回整體錯誤：指定的表不存在。包含同名的表。表名不符合命名規則和資料類型命名規範。行操作未指定主鍵、主鍵列名稱不符合規範或主鍵列類型不正確。屬性列名稱不符合命名規則和資料類型命名規範。屬性列名稱與主鍵列名稱相同。主鍵列或屬性列的值大小超過使用限制限制。同一表中存在主鍵完全相同的請求。所有表的行操作總數超過 200 個，或總資料量超過 4 MB。某張表內沒有行操作，返回 OTSParameterInvalidException 錯誤。 PutRowInBatchWriteRowRequest 包含的列數超過 1024 個。 UpdateRowInBatchWriteRowRequest 中 ColumnUpdate 的個數超過 1024 個。
transaction_id	string	否	局部事務 ID。使用局部事務功能批量寫入資料時必須設定此參數。
is_atomic	bool	否	指定批量寫操作是否以原子操作方式執行。

響應訊息結構

說明

BatchWriteRow 可能出現行層級的部分失敗，此時返回的HTTP狀態代碼仍為 200。需檢查每個 RowInBatchWriteRowResponse 中的 is_ok 欄位，確認每行的執行結果並進行相應處理。

message BatchWriteRowResponse {
    repeated TableInBatchWriteRowResponse tables = 1;
}

參數

類型

描述

tables

TableInBatchWriteRowResponse

各表中每個操作的響應資訊，包括執行狀態、錯誤碼和消耗的 CU。

響應中 TableInBatchWriteRowResponse 的順序與請求中 TableInBatchWriteRowRequest 的順序一致；每個表內，put_rows、update_rows、delete_rows 對應的 RowInBatchWriteRowResponse 順序，分別與請求中 PutRowInBatchWriteRowRequest、UpdateRowInBatchWriteRowRequest、DeleteRowInBatchWriteRowRequest 的順序相同。

某行操作失敗時，對應 RowInBatchWriteRowResponse 中的 is_ok 為 false。

使用 SDK

以下SDK支援 BatchWriteRow 批量寫入操作：

服務能力單元消耗

如果本次操作整體失敗，則不消耗任何服務能力單元。
如果請求逾時，結果未定義，則服務能力單元有可能被消耗，也可能未被消耗。
其他情況下，每個 PutRowInBatchWriteRowRequest、UpdateRowInBatchWriteRowRequest、DeleteRowInBatchWriteRowRequest 均視作對應的單行寫操作，獨立計算讀寫 CU。詳情請參見PutRow 服務能力單元消耗、UpdateRow 服務能力單元消耗和DeleteRow 服務能力單元消耗。