表格存储提供了PutRow、GetRow、UpdateRow和DeleteRow等单行操作的接口。
如果需要了解表格存储各场景的应用案例,请参见快速玩转Tablestore入门与实战。
前提条件
- 已初始化Client,详情请参见初始化。
- 已创建数据表并写入数据。
插入一行数据(PutRow)
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:设置为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表示使用的读写能力单元。
|
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);
读取一行数据(GetRow)
GetRow接口用于读取一行数据。
- 如果该行存在,则返回该行的各主键列以及属性列。
- 如果该行不存在,则返回中不包含行,并且不会报错。
接口
/**
* 读取一行数据。
* @api
* @param [] $request 请求参数。
* @return [] 请求返回。
* @throws OTSClientException 当参数检查出错或服务端返回校验出错时抛出异常。
* @throws OTSServerException 当OTS服务端返回错误时抛出异常。
*/
public function getRow(array $request);
请求参数
参数 | 说明 |
---|---|
table_name | 数据表名称。 |
primary_key | 行的主键。
说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
|
max_versions | 最多读取的版本数。
说明 max_versions与time_range必须至少设置一个。
|
time_range | 读取版本号范围或特定版本号的数据。更多信息,请参见TimeRange。
说明 max_versions与time_range必须至少设置一个。
specific_time和 时间戳的单位为毫秒,最小值为0,最大值为INT64.MAX。 |
columns_to_get | 读取的列集合,列名可以是主键列或属性列。
如果不设置返回的列名,则返回整行数据。 说明
|
start_column | 读取的起始列,主要用于宽行读,返回的结果中包含当前起始列。
列的顺序按照列名的字典序排序。例如一张表有“a”,”b”,”c”三列,读取时设置start_column为“b”,则会从”b”列开始读,返回”b”,”c”两列。 |
end_column | 读取时的结束列,主要用于宽行读,返回的结果中不包含当前结束列。
列的顺序按照列名的字典序排序。例如一张表有”a”,”b”,”c”三列,读取时指定end_column为“b”,则读到”b”列时会结束,返回”a”列。 |
token | 宽行读取时下一次读取的起始位置,暂不可用。 |
column_filter | 使用过滤器,在服务端对读取结果再进行一次过滤,只返回符合过滤器中条件的数据行。更多信息,请参见过滤器。
说明 当columns_to_get和column_filter同时使用时,执行顺序是先获取columns_to_get指定的列,再在返回的列中进行条件过滤。
|
请求格式
$result = $client->getRow([
'table_name' => '<string>', //设置数据表名称。
'primary_key' => [ //设置主键。
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
],
'max_versions' => <integer>,
'time_range' => [
'start_time' => <integer>,
'end_time' => <integer>,
'specific_time' => <integer>
],
'start_column' => '<string>',
'end_column' => '<string>',
'token' => '<string>',
'columns_to_get' => [
'<string>',
'<string>',
//...
],
'column_filter' => <ColumnCondition>
]);
响应参数
参数 | 说明 |
---|---|
consumed | 本次操作消耗服务能力单元的值。
capacity_unit表示使用的读写能力单元。
|
primary_key | 主键的值,和请求时一致。
说明 如果该行不存在,则primary_key为空列表[]。
|
attribute_columns | 属性列的值。
说明 如果该行不存在,则attribute_columns为空列表[]。
|
next_token | 宽行读取时下一次读取的位置,暂不可用。 |
结果格式
[
'consumed' => [
'capacity_unit' => [
'read' => <integer>,
'write' => <integer>
]
],
'primary_key' => [
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
],
'attribute_columns' => [
['<string>', <ColumnValue>, <ColumnType>, <integer>]
['<string>', <ColumnValue>, <ColumnType>, <integer>]
['<string>', <ColumnValue>, <ColumnType>, <integer>]
],
'next_token' => '<string>'
]
示例
- 示例1
读取一行,设置读取最新版本的数据和读取的列。
$request = [ 'table_name' => 'MyTable', 'primary_key' => [ //设置主键。 ['PK0', 123], ['PK1', 'abc'] ], 'max_versions' => 1, //设置读取最新版本。 'columns_to_get' => ['Col0'] //设置读取的列。 ]; $response = $otsClient->getRow ($request);
- 示例2
在读取一行数据时使用过滤器。
$request = [ 'table_name' => 'MyTable', 'primary_key' => [ //设置主键。 ['PK0', 123], ['PK1', 'abc'] ], 'max_versions' => 1, //设置读取最新版本。 'column_filter' => [ //设置过滤器,当Col0列的值为0时,返回该行。 'column_name' => 'Col0', 'value' => 0, 'comparator' => ComparatorTypeConst::CONST_EQUAL, 'pass_if_missing' => false //如果Col0列不存在,则不返回该行。 ] ]; $response = $otsClient->getRow ($request);
更新一行数据(UpdateRow)
接口
/**
* 更新一行数据。
* @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' //删除某一列。 ] ] ];
删除一行数据(DeleteRow)
DeleteRow接口用于删除一行数据。如果删除的行不存在,则不会发生任何变化。
接口
/**
* 删除一行数据。
* @api
* @param [] $request 请求参数。
* @return [] 请求返回。
* @throws OTSClientException 当参数检查出错或服务端返回校验出错时抛出异常。
* @throws OTSServerException 当OTS服务端返回错误时抛出异常。
*/
public function deleteRow(array $request);
请求参数
参数 | 说明 |
---|---|
table_name | 数据表名称。 |
condition | 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件。更多信息,请参见条件更新。 |
primary_key | 行的主键。
说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
|
return_content | 表示返回类型。
return_type:目前只需要设置为ReturnTypeConst::CONST_PK,表示返回主键值,主要用于主键列自增场景。 |
请求格式
$result = $client->deleteRow([
'table_name' => '<string>', //设置数据表名称。
'condition' => [
'row_existence' => <RowExistence>,
'column_condition' => <ColumnCondition>
],
'primary_key' => [ //设置主键。
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
],
'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'] ], 'return_content' => [ 'return_type' => ReturnTypeConst::CONST_PK //使用主键列自增时,可以设置return_type返回主键。 ] ]; $response = $otsClient->deleteRow($request);
- 示例2
设置删除条件。
$request = [ 'table_name' => 'MyTable', 'condition' => [ 'row_existence' => RowExistenceExpectationConst::CONST_EXPECT_EXIST, //期望原行存在。 'column_filter' => [ //当Col0列的值大于100时删除数据。 'column_name' => 'Col0', 'value' => 100, 'comparator' => ComparatorTypeConst::CONST_GREATER_THAN ], ], 'primary_key' => [ //设置主键。 ['PK0', 123], ['PK1', 'abc'] ] ]; $response = $otsClient->deleteRow ($request);