表格存储提供了PutRow和UpdateRow接口用于写入单行数据以及BatchWriteRow接口用于批量写入数据。
如果需要了解表格存储各场景的应用案例,请参见快速玩转Tablestore入门与实战。
前提条件
- 已初始化Client,详情请参见初始化。
- 已创建数据表并写入数据。
插入单行数据
调用PutRow接口新写入一行数据。如果该行已存在,则先删除原行数据(原行的所有列以及所有版本的数据),再写入新行数据。
接口
/**
* 写入一行数据。如果该行已存在,则先删除原行数据(原行的所有列以及所有版本的数据),再写入新行数据。返回该操作消耗的CU。
* @api
* @param [] $request 请求参数。
* @return [] 请求返回。
* @throws OTSClientException 当参数检查出错或服务端返回校验出错时抛出异常。
* @throws OTSServerException 当OTS服务端返回错误时抛出异常。
*/
public function putRow(array $request);
请求参数
参数 | 说明 |
---|---|
table_name | 数据表名称。 |
condition | 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件。更多信息,请参见条件更新。
|
primary_key | 行的主键。
说明
|
attribute_columns | 行的属性列。
|
return_content | 表示返回类型。
return_type:设置为 |
请求格式
$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表示使用的读写能力单元。
|
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' => []
]
示例
- 示例1
写入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);
- 示例2
写入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);
- 示例3
期望原行不存在时,写入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);
- 示例4
期望原行存在且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);
更新单行数据
接口
/**
* 更新一行数据。
* @api
* @param [] $request 请求参数。
* @return [] 请求返回。
* @throws OTSClientException 当参数检查出错或服务端返回校验出错时抛出异常。
* @throws OTSServerException 当OTS服务端返回错误时抛出异常。
*/
public function updateRow(array $request);
请求参数
参数 | 说明 |
---|---|
table_name | 数据表名称。 |
condition | 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件。更多信息,请参见条件更新。 |
primary_key | 行的主键。
说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
|
update_of_attribute_columns | 更新的属性列。
|
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表示使用的读写能力单元。
|
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' => []
]
示例
- 示例1
更新一些列,删除某列的某一版本,删除某列。
$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);
- 示例2
设置更新的条件。
$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操作由多个PutRow、UpdateRow、DeleteRow子操作组成,构造子操作的过程与使用PutRow接口、UpdateRow接口和DeleteRow接口时相同,也支持使用条件更新。
BatchWriteRow的各个子操作独立执行,表格存储会分别返回各个子操作的执行结果。
注意事项
由于批量写入可能存在部分行失败的情况,失败行的Index及错误信息在返回的BatchWriteRowResponse中,但并不抛出异常。因此调用BatchWriteRow接口时,需要检查返回值,判断每行的状态是否成功;如果不检查返回值,则可能会忽略掉部分操作的失败。
当服务端检查到某些操作出现参数错误时,BatchWriteRow接口可能会抛出参数错误的异常,此时该请求中所有的操作都未执行。
接口
/**
* 写入、更新或者删除指定的多行数据。
* 请注意BatchWriteRow在部分行写入失败时,会在返回的$response中表示,而不是抛出异常。更多信息,请参见处理BatchWriteRow的返回样例。
* @api
* @param [] $request 请求参数。
* @return [] 请求返回。
* @throws OTSClientException 当参数检查出错或服务端返回校验出错时。
* @throws OTSServerException 当OTS服务端返回错误时。
*/
public function batchWriteRow(array $request);
请求参数
- 增加了数据表的层级结构,可以一次处理多个数据表。
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>
]
],
//其他数据表。
]
]);
响应参数
参数 | 说明 |
---|---|
table_name | 数据表名称。 |
is_ok | 该行操作是否成功。
|
error | 用于在操作失败时的响应消息中表示错误信息。
|
consumed | 本次操作消耗服务能力单元的值。
capacity_unit表示使用的读写单元。
|
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中同时使用条件更新的用法。 |