PHP SDK寫入資料、更新資料、批量寫入資料 - Tablestore

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

前提條件

已初始化Client。具體操作，請參見初始化OTSClient。
已建立資料表並寫入資料。具體操作，請參見建立資料表。

插入單行資料

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

介面

/**
 * 寫入一行資料。如果該行已存在，則先刪除原行資料（原行的所有列以及所有版本的資料），再寫入新行資料。返回該操作消耗的CU。
 * @api
 * @param [] $request 請求參數。
 * @return [] 請求返回。 
 * @throws OTSClientException 當參數檢查出錯或服務端返回校正出錯時拋出異常。
 * @throws OTSServerException 當OTS服務端返回錯誤時拋出異常。
 */
public function putRow(array $request);

請求資訊

請求參數

參數	說明
table_name	資料表名稱。
condition	使用條件更新，可以設定原行的存在性條件或者原行中某列的列值條件。更多資訊，請參見條件更新。 row_existence：行存在性條件。說明 `RowExistenceExpectationConst::CONST_IGNORE`表示無論此行是否存在均會插入新資料，如果之前行已存在，則寫入資料時會覆蓋原有資料。 `RowExistenceExpectationConst::CONST_EXPECT_EXIST`表示只有此行存在時才會插入新資料，寫入資料時會覆蓋原有資料。 `RowExistenceExpectationConst::CONST_EXPECT_NOT_EXIST`表示只有此行不存在時才會插入資料。 column_condition：列條件。
primary_key	行的主鍵。說明設定的主鍵個數和類型必須和資料表的主鍵個數和類型一致。當主鍵為自增列時，只需將自增列的值設定為預留位置。更多資訊，請參見主鍵列自增。資料表可包含1個~4個主鍵列。主鍵列是有順序的，與使用者添加的順序相同，例如PRIMARY KEY（A, B, C）與PRIMARY KEY（A, C, B）是不同的兩個主鍵結構。Table Store會按照主鍵的大小對行進行排序。每一項的順序是主鍵名、主索引值PrimaryKeyValue、主鍵類型PrimaryKeyType（可選）。 PrimaryKeyValue可以是整數、二進位和字串。 PrimaryKeyType可以是INTEGER、STRING（UTF-8編碼字串）、BINARY、PK_AUTO_INCR（主鍵列自增）四種，分別用`PrimaryKeyTypeConst::CONST_INTEGER`，`PrimaryKeyTypeConst::CONST_STRING`，`PrimaryKeyTypeConst::CONST_BINARY`，`PrimaryKeyTypeConst::CONST_PK_AUTO_INCR`表示，對於INTEGER和STRING，可以省略，其它類型不可省略。
attribute_columns	行的屬性列。每一項的順序是屬性名稱、屬性值ColumnValue、屬性類型ColumnType（可選）、時間戳記（可選）。 ColumnType可以是INTEGER、STRING（UTF-8編碼字串）、BINARY、BOOLEAN、DOUBLE五種，分別用`ColumnTypeConst::CONST_INTEGER`、`ColumnTypeConst::CONST_STRING`、`ColumnTypeConst::CONST_BINARY、ColumnTypeConst::CONST_BOOLEAN`、`ColumnTypeConst::CONST_DOUBLE`表示，其中BINARY不可省略，其他類型都可以省略，或者設定為null。時間戳記即資料的版本號碼。更多資訊，請參見資料版本和生命週期。資料的版本號碼可以由系統自動產生或者自訂，如果不設定此參數，則預設由系統自動產生。當由系統自動產生資料的版本號碼時，系統預設將目前時間的毫秒單位時間戳記（從1970-01-01 00:00:00 UTC計算起的毫秒數）作為資料的版本號碼。當自訂資料的版本號碼時，版本號碼需要為64位的毫秒單位時間戳記且在有效版本範圍內。
return_content	表示傳回型別。 return_type：設定為`ReturnTypeConst::CONST_PK`，表示返回主索引值，主要用於主鍵列自增情境。

請求格式

$result = $client->putRow([
    'table_name' => '<string>', //設定資料表名稱。
    'condition' => [
        'row_existence' => <RowExistence>,   
        'column_condition' => <ColumnCondition>
    ],
    'primary_key' => [                              //設定主鍵。
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ],  
    'attribute_columns' => [         //設定屬性列。
            ['<string>', <ColumnValue>], 
            ['<string>', <ColumnValue>, <ColumnType>],
            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
    ],
    'return_content' => [
        'return_type' => <ReturnType>
    ]
]);

響應資訊

響應參數

參數	說明
consumed	本次操作消耗服務能力單元的值。 capacity_unit表示使用的讀寫能力單元。 read：讀輸送量 write：寫輸送量
primary_key	主鍵的值，和請求時一致。說明當在請求中設定return_type為ReturnTypeConst::CONST_PK時，會返回完整的主鍵，主要用於主鍵列自增。
attribute_columns	屬性列的值，和請求時一致，目前為空白。

響應格式

[
    'consumed' => [
        'capacity_unit' => [
            'read' => <integer>,
            'write' => <integer>
        ]
    ],
    'primary_key' => [ 
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ],  
    'attribute_columns' => []
]

樣本

插入資料時由系統自動產生資料版本號碼

以下樣本用於寫入10列屬性列，每列寫入1個版本，由系統自動產生資料的版本號碼（時間戳記）。

$attr = array();
for($i = 0; $i < 10; $i++) {
    $attr[] = ['Col'. $i, $i]; 
}
$request = [
    'table_name' => 'MyTable',
    'condition' => RowExistenceExpectationConst::CONST_IGNORE, //condition可以為IGNORE、EXPECT_EXIST和EXPECT_NOT_EXIST。
    'primary_key' => [ //設定主鍵。
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'attribute_columns' => $attr
];
$response = $otsClient->putRow ($request);

插入資料時自訂資料版本號碼

以下樣本用於寫入10列屬性列，每列寫入3個版本，自訂資料的版本號碼（時間戳記）。

$attr = array();
$timestamp = getMicroTime();
for($i = 0; $i < 10; $i++) {
    for($j = 0; $j < 3; $j++) {
        $attr[] = ['Col'. $i, $j, null, $timestamp+$j];
    }
}
$request = [
    'table_name' => 'MyTable',
    'condition' => RowExistenceExpectationConst::CONST_IGNORE, //condition可以為IGNORE、EXPECT_EXIST和EXPECT_NOT_EXIST。
    'primary_key' => [ //設定主鍵。
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'attribute_columns' => $attr
];
$response = $otsClient->putRow ($request);

插入資料時使用行條件

以下樣本用於當原行不存在時，寫入10列屬性列，每列寫入3個版本，自訂資料的版本號碼（時間戳記）。

$attr = array();
$timestamp = getMicroTime();
for($i = 0; $i < 10; $i++) {
    for($j = 0; $j < 3; $j++) {
        $attr[] = ['Col'. $i, $j, null, $timestamp+$j];
    }
}
$request = [
    'table_name' => 'MyTable',
    'condition' => RowExistenceExpectationConst::CONST_EXPECT_NOT_EXIST, //設定期望原行不存在時，寫入資料。
    'primary_key' => [ //設定主鍵。
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'attribute_columns' => $attr
];
$response = $otsClient->putRow ($request);

插入資料時使用列條件和行條件

以下樣本當原行存在且Col0列的值大於100時，寫入10列屬性列，每列寫入3個版本，自訂資料的版本號碼（時間戳記）。

$attr = array();
$timestamp = getMicroTime();
for($i = 0; $i < 10; $i++) {
    for($j = 0; $j < 3; $j++) {
        $attr[] = ['Col'. $i, $j, null, $timestamp+$j];
    }
}
$request = [
    'table_name' => 'MyTable',
    'condition' => [
        'row_existence' => RowExistenceExpectationConst::CONST_EXPECT_EXIST,//期望原行存在。
        'column_condition' => [                  //使用條件更新，滿足條件則更新。
            'column_name' => 'Col0',
            'value' => 100,
            'comparator' => ComparatorTypeConst::CONST_GREATER_THAN
        ]
    ,
    'primary_key' => [ //設定主鍵。
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'attribute_columns' => $attr
];
$response = $otsClient->putRow ($request);

更新單行資料

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

說明

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

介面

/**
 * 更新一行資料。
 * @api
 * @param [] $request 請求參數。
 * @return [] 請求返回。
 * @throws OTSClientException 當參數檢查出錯或服務端返回校正出錯時拋出異常。
 * @throws OTSServerException 當OTS服務端返回錯誤時拋出異常。
 */
public function updateRow(array $request);

請求資訊

請求參數

參數	說明
table_name	資料表名稱。
condition	使用條件更新，可以設定原行的存在性條件或者原行中某列的列值條件。更多資訊，請參見條件更新。
primary_key	行的主鍵。重要設定的主鍵個數和類型必須和資料表的主鍵個數和類型一致。
update_of_attribute_columns	更新的屬性列。增加或更新資料時，需要設定屬性名稱、屬性值、屬性類型（可選）、時間戳記（可選）。屬性名稱即屬性列的名稱，屬性類型即屬性列的資料類型。更多資訊，請參見命名規則和資料類型。時間戳記即資料的版本號碼，可以由系統自動產生或者自訂，如果不設定此參數，則預設由系統自動產生。更多資訊，請參見資料版本和生命週期。當由系統自動產生資料的版本號碼時，系統預設將目前時間的毫秒單位時間戳記（從1970-01-01 00:00:00 UTC計算起的毫秒數）作為資料的版本號碼。當自訂資料的版本號碼時，版本號碼需要為64位的毫秒單位時間戳記且在有效版本範圍內。刪除屬性列特定版本的資料時，只需要設定屬性名稱和時間戳記。時間戳記是64位整數，單位為毫秒，表示某個特定版本的資料。刪除屬性列時，只需要設定屬性名稱。說明刪除一行的全部屬性列不等同於刪除該行，如果需要刪除該行，請使用DeleteRow操作。
return_content	表示傳回型別。 return_type：目前只需要設定為ReturnTypeConst::CONST_PK，表示返回主索引值，主要用於主鍵列自增情境。

請求格式

$result = $client->updateRow([
    'table_name' => '<string>', //設定資料表名稱。
    'condition' => [
        'row_existence' => <RowExistence>,
        'column_condition' => <ColumnCondition>
    ],
    'primary_key' => [                         //設定主鍵。
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'update_of_attribute_columns' => [         //設定更新的屬性列。
        'PUT' => [
            ['<string>', <ColumnValue>], 
            ['<string>', <ColumnValue>, <ColumnType>],
            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
        ],
        'DELETE' => [
            ['<string>', <integer>], 
            ['<string>', <integer>], 
            ['<string>', <integer>], 
            ['<string>', <integer>]
        ],
        'DELETE_ALL' => [
            '<string>',
            '<string>',
            '<string>',
            '<string>'
        ],        
    ],
    'return_content' => [
        'return_type' => <ReturnType>
    ]
]);

響應資訊

響應參數

參數	說明
consumed	本次操作消耗服務能力單元的值。 capacity_unit表示使用的讀寫能力單元。 read：讀輸送量 write：寫輸送量
primary_key	主鍵的值，和請求時一致。說明當在請求中設定return_type為ReturnTypeConst::CONST_PK時，會返回完整的主鍵，主要用於主鍵列自增。
attribute_columns	屬性列的值，和請求時一致，目前為空白。

結果格式

[
    'consumed' => [
        'capacity_unit' => [
            'read' => <integer>,
            'write' => <integer>
        ]
    ],
    'primary_key' => [ 
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ],  
    'attribute_columns' => []
]

樣本

更新資料時不使用條件

以下樣本用於更新一些列，刪除某列的某一版本，刪除某列。

$request = [
    'table_name' => 'MyTable',
    'condition' => RowExistenceExpectationConst::CONST_IGNORE,
    'primary_key' => [ //設定主鍵。
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'update_of_attribute_columns' => [
        'PUT' => [                       //更新一些列。
            ['Col0', 100],
            ['Col1', 'Hello'],
            ['Col2', 'a binary', ColumnTypeConst::CONST_BINARY],
            ['Col3', 100, null, 1526418378526]
        ],
        'DELETE' => [                    //刪除某列的某一版本。
            ['Col10', 1526418378526]
        ],
        'DELETE_ALL' => [
            'Col11'                      //刪除某一列。
        ]
    ]
];
$response = $otsClient->updateRow($request);

更新資料時使用列條件和行條件

以下樣本用於當原行存在且Col0列的值大於100時更新資料。

$request = [
    'table_name' => 'MyTable',
    'primary_key' => [ //設定主鍵。
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'condition' => [
        'row_existence' => RowExistenceExpectationConst::CONST_EXPECT_EXIST, //期望原行存在。
        'column_filter' => [                                                 //當Col0列的值大於100時更新資料。
            'column_name' => 'Col0',
            'value' => 100,
            'comparator' => ComparatorTypeConst::CONST_GREATER_THAN
        ]
    ],    
    'update_of_attribute_columns' => [
        'PUT' => [                       //更新一些列。
            ['Col0', 100],
            ['Col1', 'Hello'],
            ['Col2', 'a binary', ColumnTypeConst::CONST_BINARY],
            ['Col3', 100, null, 1526418378526]
        ],
        'DELETE' => [                    //刪除某列的某一版本。
            ['Col10', 1526418378526]
        ],
        'DELETE_ALL' => [
            'Col11'                      //刪除某一列。
        ]
    ]
];

批量寫入資料

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

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

注意事項

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

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

介面

/**
 * 寫入、更新或者刪除指定的多行資料。
 * 請注意BatchWriteRow在部分行寫入失敗時，會在返回的$response中表示，而不是拋出異常。更多資訊，請參見處理BatchWriteRow的返回範例。
 * @api
 * @param [] $request 請求參數。
 * @return [] 請求返回。
 * @throws OTSClientException 當參數檢查出錯或服務端返回校正出錯時。
 * @throws OTSServerException 當OTS服務端返回錯誤時。
 */
public function batchWriteRow(array $request);

請求資訊

請求參數

本操作是PutRow、UpdateRow、DeleteRow的組合。

增加了資料表的層級結構，可以一次處理多個資料表。
tables以資料表為單位組織，後續為各個資料表的操作，設定需要寫入、修改或刪除的行資訊。
增加了operation_type參數，用於區分操作類型。
操作類型可以為PUT、UPDATE、DELETE，分別用OperationTypeConst::CONST_PUT、OperationTypeConst::CONST_UPDATE、OperationTypeConst::CONST_DELETE表示。
- 當操作類型為PUT時，primary_key和attribute_columns有效。
- 當操作類型為UPDATE時，primary_key和update_of_attribute_columns有效。
- 當操作類型為DELETE時，primary_key有效。

請求格式

$result = $client->batchWriteRow([
    'tables' => [                                            //設定資料表的層級結構。
        [
            'table_name' => '<string>',                      //設定資料表名稱。
            'operation_type' => <OperationType>,
            'condition' => [
                'row_existence' => <RowExistence>,   
                'column_condition' => <ColumnCondition>
            ],
            'primary_key' => [                               //設定主鍵。
                ['<string>', <PrimaryKeyValue>], 
                ['<string>', <PrimaryKeyValue>],
                ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
            ], 
            'attribute_columns' => [                        //當操作類型為PUT時必須設定。
                    ['<string>', <ColumnValue>], 
                    ['<string>', <ColumnValue>, <ColumnType>],
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>]
            ],
            'update_of_attribute_columns' => [               //當操作類型為UPDATE時必須設定。
                'PUT' => [
                    ['<string>', <ColumnValue>], 
                    ['<string>', <ColumnValue>, <ColumnType>],
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                ],
                'DELETE' => [
                    ['<string>', <integer>], 
                    ['<string>', <integer>], 
                    ['<string>', <integer>], 
                    ['<string>', <integer>]
                ],
                'DELETE_ALL' => [
                    '<string>',
                    '<string>',
                    '<string>',
                    '<string>'
                ],
            ],
            'return_content' => [
                'return_type' => <ReturnType>
            ]
        ],
        //其他資料表。
    ]
]);

響應資訊

響應參數

tables以table為單位組織，和請求一一對應，參數說明請參見下表。

參數	說明
table_name	資料表名稱。
is_ok	該行操作是否成功。如果值為true，則該行寫入成功，此時error無效。如果值為false，則該行寫入失敗。
error	用於在操作失敗時的響應訊息中表示錯誤資訊。 code表示當前單行操作的錯誤碼。 message表示當前單行操作的錯誤資訊。
consumed	本次操作消耗服務能力單元的值。 capacity_unit表示使用的讀寫單元。 read：讀輸送量 write：寫輸送量
primary_key	主鍵的值，和請求時一致。設定return_type時會有值，主要用於主鍵列自增。
attribute_columns	屬性列的值，和請求時一致，目前為空白。

結果格式

[
    'tables' => [
        [
            'table_name' => '<string>',
            'rows' => [
                [
                    'is_ok' => true || false,
                    'error' => [
                        'code' => '<string>',
                        'message' => '<string>',
                    ]
                    'consumed' => [
                        'capacity_unit' => [
                            'read' => <integer>,
                            'write' => <integer>
                        ]
                    ],
                    'primary_key' => [ 
                        ['<string>', <PrimaryKeyValue>], 
                        ['<string>', <PrimaryKeyValue>],
                        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
                    ],
                    'attribute_columns' => []
                ],
                //其他行。
            ]
        ],
        //其他資料表。
    ]
]

樣本

以下樣本用於批量寫入30行資料，分別向3個資料表中寫入資料，每個資料表中寫入10行。

//向3個資料表中寫入資料，每個資料表中寫入10行。
$tables = array();
for($i = 0; $i < 3; $i++) {
    $rows = array();
    for($j = 0; $j < 10; $j++) {
        $rows[] = [
            'operation_type' => OperationTypeConst::CONST_PUT, //設定作業類型為PUT。
            'condition' => RowExistenceExpectationConst::CONST_IGNORE,
            'primary_key' => [
                ['pk0', $i],
                ['pk1', $j]
            ],
            'attribute_columns' => [
                ['Col0', 4],
                ['Col2', '成杭京']
            ]
        ];
    }
    $tables[] = [
        'table_name' => 'SampleTable' . $i,
        'rows' => $rows
    ];
}
$request = [
    'tables' => $tables
];
$response = $otsClient->batchWriteRow ($request);
//處理返回的每個資料表。
foreach ($response['tables'] as $tableData) {
  print "Handling table {$tableData['table_name']} ...\n";

  //處理該資料表下的PutRow返回的結果。
  $putRows = $tableData['rows'];

  foreach ($putRows as $rowData) {

    if ($rowData['is_ok']) {
      //寫入成功。
      print "Capacity Unit Consumed: {$rowData['consumed']['capacity_unit']['write']}\n";
    } else {

      //處理出錯。
      print "Error: {$rowData['error']['code']} {$rowData['error']['message']}\n";
    }
  }
}

詳細程式碼範例請參見下表。

樣本	說明
BatchWriteRow1.php	展示了BatchWriteRow中多個PUT的用法。
BatchWriteRow2.php	展示了BatchWriteRow中多個UPDATE的用法。
BatchWriteRow3.php	展示了BatchWriteRow中多個DELETE的用法。
BatchWriteRow4.php	展示了BatchWriteRow中組合使用UPDATE、PUT和DELETE的用法。
BatchWriteRowWithColumnFilter.php	展示了BatchWriteRow中同時使用條件更新的用法。

Tablestore：寫入資料

前提條件

插入單行資料

介面

請求資訊

請求參數

請求格式

響應資訊

響應參數

響應格式

樣本

插入資料時由系統自動產生資料版本號碼

插入資料時自訂資料版本號碼

插入資料時使用行條件

插入資料時使用列條件和行條件

更新單行資料

介面

請求資訊

請求參數

請求格式

響應資訊

響應參數

結果格式

樣本

更新資料時不使用條件

更新資料時使用列條件和行條件

批量寫入資料

注意事項

介面

請求資訊

請求參數

請求格式

響應資訊

響應參數

結果格式

樣本

常見問題

相關文檔