多行数据操作 - 表格存储 Tablestore

表格存储提供了BatchWriteRow、BatchGetRow、GetRange等多行操作的接口。

如需了解表格存储各场景的应用案例，请参见适用场景。

前提条件

已初始化Client，详情请参见初始化。
已创建数据表并写入数据。

批量写（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);

请求参数
本操作是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中同时使用条件更新的用法。

批量读（BatchGetRow）

批量读接口用于一次请求读取多行数据，也支持一次对多张表进行读取。BatchGetRow由多个GetRow子操作组成。构造子操作的过程与使用GetRow接口时相同，也支持使用过滤器。

批量读取的所有行采用相同的参数条件，例如ColumnsToGet=[colA]，则要读取的所有行都只读取colA列。

BatchGetRow的各个子操作独立执行，表格存储会分别返回各个子操作的执行结果。

由于批量读取可能存在部分行失败的情况，失败行的错误信息在返回的BatchGetRowResponse中，但并不抛出异常。因此调用BatchGetRow接口时，需要检查返回值，判断每行的状态是否成功。

接口

/**
 * 读取指定的多行数据。
 * 请注意BatchGetRow在部分行读取失败时，会在返回的$response中表示，而不是抛出异常。详情请参见处理BatchGetRow的返回样例。
 * @api
 * @param [] $request 请求参数。
 * @return [] 请求返回。
 * @throws OTSClientException 当参数检查出错或服务端返回校验出错时。
 * @throws OTSServerException 当OTS服务端返回错误时。
 */
public function batchGetRow(array $request);

请求参数
BatchGetRow和GetRow的区别如下：
- 增加了数据表的层级结构，可以一次读取多个数据表的数据。
  tables以数据表为单位组织，后续为各个数据表的操作，设置了需要读取的行信息，参数说明请参见单行数据操作。
- primary_key变为primary_keys，支持设置多行的主键，可以一次读取多行数据。

请求格式

$result = $client->batchGetRow([
    'tables' => [                                            //设置数据表的层级结构。
        [
            'table_name' => '<string>',                      //设置数据表名称。
            'primary_keys' => [                              //设置主键。
                [
                    ['<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>
        ],
        //其他数据表。
    ]
]);

响应参数

tables以table为单位组织，和请求一一对应，参数说明请参见下表。


参数	说明
table_name	数据表名称。
is_ok	该行操作是否成功。如果值为true，则该行读取成功，此时error无效。如果值为false，则该行读取失败，此时consumed、primary_key、attribute_columns无效。
error	用于在操作失败时的响应消息中表示错误信息。 code表示当前单行操作的错误码。 message表示当前单行操作的错误信息。
consumed	本次操作消耗服务能力单元的值。 capacity_unit表示使用的读写能力单元。 read：读吞吐量 write：写吞吐量
primary_key	主键的值，和请求时一致。说明如果该行不存在，则primary_key为空列表[]。
attribute_columns	属性列的值。说明如果该行不存在，则attribute_columns为空列表[]。每一项的顺序是属性名、属性值ColumnValue、属性类型ColumnType、时间戳。时间戳为64位整数，用于表示属性列数据的多个不同的版本。返回结果中的属性会按照属性名的字典序升序，属性的多个版本按时间戳降序。其顺序不保证与请求中的columns_to_get一致。
next_token	宽行读取时下一次读取的位置，暂不可用。

结果格式

[
    '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' => [
                            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                    ],
                    'next_token' => '<string>'
                ],
                //其他行。
            ]
        ],
        //其他数据表。
    ]
]

示例

批量一次读取30行，分别从3个数据表中读取数据，每个数据表读取10行。

//从3个数据表中读取数据，每个数据表读取10行。
$tables = array();
for($i = 0; $i < 3; $i++) {
    $primary_keys = array();
    for($j = 0; $j < 10; $j++) {
        $primary_keys[] = [
            ['pk0', $i],
            ['pk1', $j]
        ];
    }
    $tables[] = [
        'table_name' => 'SampleTable' . $i,
        'max_versions' => 1,
        'primary_keys' => $primary_keys
    ];
}
$request = [
    'tables' => $tables
];
$response = $otsClient->batchGetRow ($request);

//处理返回的每个数据表。
foreach ($response['tables'] as $tableData) {
  print "Handling table {$tableData['table_name']} ...\n";

  //处理该数据表下的每行数据。
  foreach ($tableData['rows'] as $rowData) {

    if ($rowData['is_ok']) {

      //处理读取到的数据。
        $row = json_encode($rowData['primary_key']);
        print "Handling row: {$row}\n";

    } else {

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

详细代码示例请参见下表。


示例	说明
BatchGetRow1.php	展示了BatchGetRow获取单个数据表多行的用法。
BatchGetRow2.php	展示了BatchGetRow获取多个数据表多行的用法。
BatchGetRow3.php	展示了BatchGetRow获取单个数据表多行同时指定获取特定列的用法。
BatchGetRow4.php	展示了BatchGetRow处理返回结果的用法。
BatchGetRowWithColumnFilter.php	展示了BatchGetRow同时使用过滤器的用法。

范围读（GetRange）

范围读接口用于读取一个主键范围内的数据。

范围读接口支持按照确定范围进行正序读取和逆序读取，可以设置要读取的行数。如果范围较大，已扫描的行数或者数据量超过一定限制，会停止扫描，并返回已获取的行和下一个主键信息。您可以根据返回的下一个主键信息，继续发起请求，获取范围内剩余的行。

GetRange操作可能在如下情况停止执行并返回数据。

扫描的行数据大小之和达到4 MB。
扫描的行数等于5000。
返回的行数等于最大返回行数。
当前剩余的预留读吞吐量已全部使用，余量不足以读取下一条数据。

说明表格存储表中的行默认是按照主键排序的，而主键是由全部主键列按照顺序组成的，所以不能理解为表格存储会按照某列主键排序，这是常见的误区。

接口

/**
 * 范围读起始主键和结束主键间的数据。
 * 请注意服务端可能会截断此范围，需要判断返回中的next_start_primary_key来判断是否继续调用GetRange。
 * 可以指定最多读取多少行。
 * 在指定开始主键和结束主键时，可以使用INF_MIN和INF_MAX分别表示最小值和最大值，详情请参见如下代码样例。
 * @api
 * @param [] $request 请求参数。
 * @return [] 请求返回。
 * @throws OTSClientException 当参数检查出错或服务端返回校验出错时。
 * @throws OTSServerException 当OTS服务端返回错误时。
 */
public function getRange(array $request);

参数

GetRange和GetRow的区别如下：

primary_key变成inclusive_start_primary_key和exclusive_end_primary_key，前闭后开区间。
增加direction表示读取方向。
增加limit限制返回行数。


参数	说明
table_name	数据表名称。
inclusive_start_primary_key	本次范围读的起始主键和结束主键，起始主键和结束主键需要是有效的主键或者是由INF_MIN和INF_MAX类型组成的虚拟点，虚拟点的列数必须与主键相同。其中INF_MIN表示无限小，任何类型的值都比它大；INF_MAX表示无限大，任何类型的值都比它小。 inclusive_start_primary_key表示起始主键，如果该行存在，则返回结果中一定会包含此行。 exclusive_end_primary_key表示结束主键，无论该行是否存在，返回结果中都不会包含此行。数据表中的行按主键从小到大排序，读取范围是一个左闭右开的区间，正序读取时，返回的是大于等于起始主键且小于结束主键的所有的行。
exclusive_end_primary_key
direction	读取方向。如果值为正序（DirectionConst::CONST_FORWARD），则起始主键必须小于结束主键，返回的行按照主键由小到大的顺序进行排列。如果值为逆序（DirectionConst::CONST_BACKWARD），则起始主键必须大于结束主键，返回的行按照主键由大到小的顺序进行排列。例如同一表中有两个主键A和B，A<B。如正序读取[A, B)，则按从A至B的顺序返回主键大于等于A、小于B的行；逆序读取[B, A)，则按从B至A的顺序返回大于A、小于等于B的数据。
limit	数据的最大返回行数，此值必须大于 0。表格存储按照正序或者逆序返回指定的最大返回行数后即结束该操作的执行，即使该区间内仍有未返回的数据。此时可以通过返回结果中的next_start_primary_key记录本次读取到的位置，用于下一次读取。
max_versions	最多读取的版本数。说明 max_version与time_range必须至少设置一个。如果仅设置max_version，则返回所有版本中从新到旧最多指定数量版本的数据。如果仅设置time_range，则返回该范围内所有数据或指定版本数据。如果同时设置max_version和time_range，则返回版本号范围内从新到旧最多指定数量版本的数据。
time_range	读取版本号范围或特定版本号的数据。详情请参见TimeRange。说明 max_version与time_range必须至少设置一个。如果仅设置max_version，则返回所有版本中从新到旧最多指定数量版本的数据。如果仅设置time_range，则返回该范围内所有数据或指定版本数据。如果同时设置max_version和time_range，则返回版本号范围内从新到旧最多指定数量版本的数据。如果查询一个范围的数据，则需要设置start_time和end_time。start_time和end_time分别表示起始时间戳和结束时间戳，范围为前闭后开区间，即[start_time, end_time)。如果查询特定版本号的数据，则需要设置specific_time。specific_time表示特定的时间戳。 specific_time和[start_time, end_time)中只需要设置一个。时间戳的单位为毫秒，最小值为0，最大值为INT64.MAX。
columns_to_get	读取的列集合，列名可以是主键列或属性列。如果不设置返回的列名，则返回整行数据。说明查询一行数据时，默认返回此行所有列的数据。如果需要只返回特定列，可以通过设置columns_to_get参数限制。如果将col0和col1加入到columns_to_get中，则只返回col0和col1列的值。如果某行数据的主键属于读取范围，但是该行数据不包含指定返回的列，那么返回结果中不包含该行数据。当columns_to_get和column_filter同时使用时，执行顺序是先获取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->getRange([
    'table_name' => '<string>',                                     //设置表名称。
    'inclusive_start_primary_key' => [                              //设置起始主键。
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'exclusive_end_primary_key' => [                                //设置结束主键。
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'direction' => <Direction>,                                     //设置读取方向。
    'limit' => <Direction>,
    '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表示使用的读写能力单元。 read：读吞吐量 write：写吞吐量
primary_key	主键的值，和请求时一致。
attribute_columns	属性列的值。每一项的顺序是属性名、属性值ColumnValue、属性类型ColumnType、时间戳。时间戳为64位整数，单位为毫秒，用于表示属性列数据的多个不同的版本。返回结果中的属性会按照属性名的字典序升序，属性的多个版本按时间戳降序。其顺序不保证与请求中的columns_to_get一致。
next_start_primary_key	根据返回结果中的next_start_primary_key判断数据是否全部读取。当返回结果中next_start_primary_key不为空时，可以使用此返回值作为下一次GetRange操作的起始点继续读取数据。当返回结果中next_start_primary_key为空时，表示读取范围内的数据全部返回。

结果格式

[
    'consumed' => [
        'capacity_unit' => [
            'read' => <integer>,
            'write' => <integer>
        ]
    ],
    'next_start_primary_key' => [ 
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'rows' => [
        [
            'primary_key' => [ 
                ['<string>', <PrimaryKeyValue>], 
                ['<string>', <PrimaryKeyValue>],
                ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
            ],  
            'attribute_columns' => [
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>]
            ]
        ],
        //其他行。
    ]
]

示例

按照范围读取数据。

//查找PK0从1到4（左闭右开）的数据。
//范围的边界需要提供完整的主键，如果查询的范围不涉及到某一列值的范围，则需要将该列设置为无穷大（INF_MAX）或者无穷小（INF_MIN）。
$startPK = [
    ['PK0', 1], 
    ['PK1', null, PrimaryKeyTypeConst::CONST_INF_MIN]  //'INF_MIN'表示最小值。
];
//范围的边界需要提供完整的主键，如果查询的范围不涉及到某一列值的范围，则需要将该列设置为无穷大（INF_MAX）或者无穷小（INF_MIN）。
$endPK = [
    ['PK0', 4], 
    ['PK1', null, PrimaryKeyTypeConst::CONST_INF_MAX]  //'INF_MAX'表示最大值。
];
$request = [
    'table_name' => 'SampleTable',
    'max_versions' => 1,                          //设置读取最新版本。
    'direction' => DirectionConst::CONST_FORWARD, //设置正序查询。
    'inclusive_start_primary_key' => $startPK,    //设置开始主键。
    'exclusive_end_primary_key' => $endPK,        //设置结束主键。
    'limit' => 10                                 //设置最多返回10行数据。
];
$response = $otsClient->getRange ($request);
print "Read CU Consumed: {$response['consumed']['capacity_unit']['read']}\n";

foreach ($response['rows'] as $rowData) {
  //处理每一行数据。
}

详细代码示例请参见下表。


示例	说明
GetRange1.php	展示了GetRange的用法。
GetRange2.php	展示了GetRange指定获取列的用法。
GetRange3.php	展示了GetRange指定获取行数限制的用法。
GetRangeWithColumnFilter.php	展示了GetRange同时使用过滤器的用法。