全部产品
弹性计算 会员服务 网络 安全 移动云 数加·大数据分析及展现 数加·大数据应用 管理与监控 云通信 阿里云办公 培训与认证 智能硬件
存储与CDN 数据库 域名与网站(万网) 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 更多
表格存储

多行操作

更新时间:2018-07-02 23:01:53

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

批量读(BatchGetRow)

API说明

批量读取一个或多个表中的若干行数据。

BatchGetRow 操作可视为多个 GetRow 操作的集合,各个操作独立执行,独立返回结果,独立计算服务能力单元。

与执行大量的 GetRow 操作相比,使用 BatchGetRow 操作可以有效减少请求的响应时间,提高数据的读取速率。

参数与 GetRow 接口参数一致。需要注意的是,批量读取的所有行采用相同的参数条件,比如 columns_to_get=[colA], 则要读取的所有行都只读取 colA 这一列。

与 BatchWriteRow 接口类似,使用 BatchGetRow 接口时也需要检查返回值。存在部分行失败,而不抛出异常的情况,此时失败行的信息在 BatchGetRowResponse 中。

接口

  1. /**
  2. * 读取指定的多行数据。
  3. * API说明:https://help.aliyun.com/document_detail/27310.html
  4. * 请注意,BatchGetRow在部分行读取失败时,会在返回的$response中表示,而不是抛出异常。请参见样例:处理BatchGetRow的返回。
  5. * @api
  6. * @param [] $request 请求参数
  7. * @return [] 请求返回
  8. * @throws OTSClientException 当参数检查出错或服务端返回校验出错时
  9. * @throws OTSServerException 当OTS服务端返回错误时
  10. */
  11. public function batchGetRow(array $request);

请求格式

  1. $result = $client->batchGetRow([
  2. 'tables' => [ // REQUIRED
  3. [
  4. 'table_name' => '<string>', // REQUIRED
  5. 'primary_keys' => [ // REQUIRED
  6. [
  7. ['<string>', <PrimaryKeyValue>],
  8. ['<string>', <PrimaryKeyValue>],
  9. ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
  10. ],
  11. // other primary keys
  12. ]
  13. 'max_versions' => <integer>,
  14. 'time_range' => [
  15. 'start_time' => <integer>,
  16. 'end_time' => <integer>,
  17. 'specific_time' => <integer>
  18. ],
  19. 'start_column' => '<string>',
  20. 'end_column' => '<string>',
  21. 'token' => '<string>',
  22. 'columns_to_get' => [
  23. '<string>',
  24. '<string>',
  25. //...
  26. ],
  27. 'column_filter' => <ColumnCondition>
  28. ],
  29. // other tables.
  30. ]
  31. ]);

请求格式说明

  • 和GetRow的区别
    • primary_key变为primary_keys,可以一次读取多行。
    • 增加了表的层级结构,可以一次读取多表。
  • tables 以表为单位组织,后续为各个表的操作,指定了需要读取的行信息。
    • table_name 表名。必须设置。
    • primary_keys 行的主键值列表。(必须设置)。列表的每一项都是一个primary_key, 以下是每个primary_key的结构
      • 表的主键可包含多个主键列。主键列是有顺序的,与用户添加的顺序相同。比如 PRIMARY KEY (A, B, C) 与 PRIMARY KEY (A, C, B) 是不同的两个主键结构。表格存储会按照整个主键的大小对行进行排序,具体请参见表格存储数据模型和查询操作
      • 每一项的顺序是 主键名、主键值、主键类型PrimaryKeyType(可选)。
      • PrimaryKeyValue可以是整数和字符串。
      • PrimaryKeyType可以是INTEGER、STRING(UTF-8编码字符串)、BINARY三种,分别用PrimaryKeyTypeConst::CONST_INTEGER,PrimaryKeyTypeConst::CONST_STRING,PrimaryKeyTypeConst::CONST_BINARY表示,对于INTEGER和STRING,可以省略,其它类型不可省略。
    • max_versions 最多读取多少个版本(常用)。
    • time_range 要读取的版本号的范围。参见TimeRange
      • start_time 起始时间戳。单位是毫秒。时间戳的取值最小值为0,最大值为INT64.MAX。若要查询一个范围,则指定start_time和end_time,前闭后开区间。
      • end_time 结束时间戳。单位是毫秒。时间戳的取值最小值为0,最大值为INT64.MAX。
      • specific_time 特定的时间戳值,若要查询一个特定时间戳,则指定specific_time。specific_time和[start_time, end_time) 两个中设置一个即可。单位是毫秒。时间戳的取值最小值为0,最大值为INT64.MAX。
    • max_versions 与 time_range 必须至少设置一个。
      • 如果仅指定 max_versions,则返回所有版本里从新到旧至多指定数量个数据。
      • 如果仅指定 time_range,则返回该范围内所有数据。
      • 如果同时指定 max_versions 和 time_range,则返回版本范围内从新到旧至多指定数量个数据。
    • 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 过滤条件,满足条件才会返回。和condition里面的column_condition类似。参见过滤器

结果格式

  1. [
  2. 'tables' => [
  3. [
  4. 'table_name' => '<string>',
  5. 'rows' => [
  6. [
  7. 'is_ok' => true || false,
  8. 'error' => [
  9. 'code' => '<string>',
  10. 'message' => '<string>',
  11. ]
  12. 'consumed' => [
  13. 'capacity_unit' => [
  14. 'read' => <integer>,
  15. 'write' => <integer>
  16. ]
  17. ],
  18. 'primary_key' => [
  19. ['<string>', <PrimaryKeyValue>],
  20. ['<string>', <PrimaryKeyValue>],
  21. ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
  22. ],
  23. 'attribute_columns' => [
  24. ['<string>', <ColumnValue>, <ColumnType>, <integer>]
  25. ['<string>', <ColumnValue>, <ColumnType>, <integer>]
  26. ['<string>', <ColumnValue>, <ColumnType>, <integer>]
  27. ],
  28. 'next_token' => '<string>'
  29. ],
  30. // other rows
  31. ]
  32. ],
  33. // other tables.
  34. ]
  35. ]

结果格式说明

  • API说明 (介绍了整体失败和部分失败的几种情况,务必查阅!!!)
  • tables 以table为单位组织,和请求一一对应。
    • table_name 该表的表名。
    • is_ok 该行操作是否成功。若为 true,则该行读取成功,error 无效;若为 false,则该行读取失败,consumed、primary_key、attribute_columns无效。
    • error 用于在操作失败时的响应消息中表示错误信息。
      • code 当前单行操作的错误码,具体含义可参考错误码
      • message 当前单行操作的错误信息,具体含义可参考错误码
    • consumed 本次操作消耗服务能力单元的值。
      • capacity_unit 使用的读写单元量
        • read 读吞吐量
        • write 写吞吐量
    • primary_key 主键的值,和请求一致。
    • 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表示。
      • 时间戳是64bit整数,用来表示属性的多个不同的版本
      • 返回结果中的属性会按照属性名的字典序升序,属性的多个版本按时间戳降序。
      • 其顺序不保证与 request 中的 columns_to_get 一致
    • next_token 宽行读取时,下一次读取的起始位置,暂不可用。

示例

批量一次读 30 行。

  1. // 从3张表中读取数据, 每张表读取10行。
  2. $tables = array();
  3. for($i = 0; $i < 3; $i++) {
  4. $primary_keys = array();
  5. for($j = 0; $j < 10; $j++) {
  6. $primary_keys[] = [
  7. ['pk0', $i],
  8. ['pk1', $j]
  9. ];
  10. }
  11. $tables[] = [
  12. 'table_name' => 'SampleTable' . $i,
  13. 'max_versions' => 1,
  14. 'primary_keys' => $primary_keys
  15. ];
  16. }
  17. $request = [
  18. 'tables' => $tables
  19. ];
  20. $response = $otsClient->batchGetRow ($request);
  21. // 处理返回的每个表
  22. foreach ($response['tables'] as $tableData) {
  23. print "Handling table {$tableData['table_name']} ...\n";
  24. // 处理这个表下的每行数据
  25. foreach ($tableData['rows'] as $rowData) {
  26. if ($rowData['is_ok']) {
  27. // 处理读取到的数据
  28. $row = json_encode($rowData['primary_key']);
  29. print "Handling row: {$row}\n";
  30. } else {
  31. // 处理出错
  32. print "Error: {$rowData['error']['code']} {$rowData['error']['message']}\n";
  33. }
  34. }
  35. }
  • 更详细的可以参考
示例文件 示例内容
BatchGetRow1.php 展示了BatchGetRow获取单表多行的用法
BatchGetRow2.php 展示了BatchGetRow获取多表多行的用法
BatchGetRow3.php 展示了BatchGetRow获取单表多行同时制定获取特定列的用法
BatchGetRow4.php 展示了BatchGetRow如何处理返回结果的用法
BatchGetRowWithColumnFilter.php 展示了BatchGetRow的同时进行条件过滤的用法

批量写(BatchWriteRow)

API说明

批量插入、修改或删除一个或多个表中的若干行数据。

BatchWriteRow 操作可视为多个 PutRow、UpdateRow、DeleteRow 操作的集合,各个操作独立执行,独立返回结果,独立计算服务能力单元。

BatchWriteRow 接口可以在一次请求中进行批量的写入操作,写入操作包括 PutRow、UpdateRow 和 DeleteRow,也支持一次对多张表进行写入。

构造单个操作的过程与使用 PutRow 接口、UpdateRow 接口和 DeleteRow 接口时相同,也支持设置更新条件。

调用 BatchWriteRow 接口时,需要特别注意的是检查返回值。因为是批量写入,可能存在部分行成功部分行失败的情况,此时失败行的 Index 及错误信息在返回的 BatchWriteRowResponse 中,而并不抛出异常。若不检查,可能会忽略掉部分操作的失败。另一方面,BatchWriteRow 接口也是可能抛出异常的。比如,服务端检查到某些操作出现参数错误,可能会抛出参数错误的异常,在抛出异常的情况下该请求中所有的操作都未执行。

接口

  1. /**
  2. * 写入、更新或者删除指定的多行数据。
  3. * API说明:https://help.aliyun.com/document_detail/27311.html
  4. * 请注意,BatchWriteRow在部分行读取失败时,会在返回的$response中表示,而不是抛出异常。请参见样例:处理BatchWriteRow的返回。
  5. * @api
  6. * @param [] $request 请求参数
  7. * @return [] 请求返回
  8. * @throws OTSClientException 当参数检查出错或服务端返回校验出错时
  9. * @throws OTSServerException 当OTS服务端返回错误时
  10. */
  11. public function batchWriteRow(array $request);

请求格式

  1. $result = $client->batchWriteRow([
  2. 'tables' => [ // REQUIRED
  3. [
  4. 'table_name' => '<string>', // REQUIRED
  5. 'operation_type' => <OperationType>,
  6. 'condition' => [
  7. 'row_existence' => <RowExistence>,
  8. 'column_condition' => <ColumnCondition>
  9. ],
  10. 'primary_key' => [ // REQUIRED
  11. ['<string>', <PrimaryKeyValue>],
  12. ['<string>', <PrimaryKeyValue>],
  13. ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
  14. ],
  15. 'attribute_columns' => [ // REQUIRED in PUT
  16. ['<string>', <ColumnValue>],
  17. ['<string>', <ColumnValue>, <ColumnType>],
  18. ['<string>', <ColumnValue>, <ColumnType>, <integer>]
  19. ],
  20. 'update_of_attribute_columns' => [ // REQUIRED in UPDATE
  21. 'PUT' => [
  22. ['<string>', <ColumnValue>],
  23. ['<string>', <ColumnValue>, <ColumnType>],
  24. ['<string>', <ColumnValue>, <ColumnType>, <integer>]
  25. ],
  26. 'DELETE' => [
  27. ['<string>', <integer>],
  28. ['<string>', <integer>],
  29. ['<string>', <integer>],
  30. ['<string>', <integer>]
  31. ],
  32. 'DELETE_ALL' => [
  33. '<string>',
  34. '<string>',
  35. '<string>',
  36. '<string>'
  37. ],
  38. ],
  39. 'return_content' => [
  40. 'return_type' => <ReturnType>
  41. ]
  42. ],
  43. // other tables.
  44. ]
  45. ]);

请求格式说明

  • 本操作是PutRow, UpdateRow, DeleteRow的组合。
    • 增加了operation_type来区分操作类型。
    • 增加了表的层级结构,可以一次处理多个表。
  • tables 以表为单位组织,后续为各个表的操作,指定了需要写入/修改/删除的行信息。
    • table_name 表名。必须设置。
    • condition 。参加条件更新
      • row_existence 行存在性条件
      • column_condition 列条件
    • operation_type 操作类型。可以为PUT(OperationTypeConst::CONST_PUT),UPDATE(OperationTypeConst::CONST_UPDATE), DELETE(OperationTypeConst::CONST_DELETE)
      • PUT. primary_key 和 attribute_columns有效。对应说明参考PutRow.
      • UPDATE. primary_key 和 update_of_attribute_columns有效。对应说明参考UpdateRow.
      • DELETE. primary_key有效。对应说明参考DeleteRow.
    • return_content 表示返回类型。
      • return_type 目前只需要设置这个。
        • ReturnTypeConst::CONST_PK 表示返回主键值(主要用于主键列自增场景)

          结果格式

  1. [
  2. 'tables' => [
  3. [
  4. 'table_name' => '<string>',
  5. 'rows' => [
  6. [
  7. 'is_ok' => true || false,
  8. 'error' => [
  9. 'code' => '<string>',
  10. 'message' => '<string>',
  11. ]
  12. 'consumed' => [
  13. 'capacity_unit' => [
  14. 'read' => <integer>,
  15. 'write' => <integer>
  16. ]
  17. ],
  18. 'primary_key' => [
  19. ['<string>', <PrimaryKeyValue>],
  20. ['<string>', <PrimaryKeyValue>],
  21. ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
  22. ],
  23. 'attribute_columns' => []
  24. ],
  25. // other rows
  26. ]
  27. ],
  28. // other tables.
  29. ]
  30. ]

结果格式说明

  • API说明 (介绍了整体失败和部分失败的几种情况,务必查阅!!!)
  • tables 以table为单位组织,和请求一一对应。
    • table_name 该表的表名。
    • is_ok 该行操作是否成功。若为 true,则该行写入成功,error 无效;若为 false,则该行写入失败。
    • error 用于在操作失败时的响应消息中表示错误信息。
      • code 当前单行操作的错误码,具体含义可参考错误码
      • message 当前单行操作的错误信息,具体含义可参考错误码
    • consumed 本次操作消耗服务能力单元的值。
      • capacity_unit 使用的读写单元量
        • read 读吞吐量
        • write 写吞吐量
    • primary_key 主键的值,和请求一致。设置返回PK的时候会有值,主要用于主键列自增。
    • attribute_columns 属性的值, 目前为空。

示例

批量导入 30 行数据。

  1. // 向3张表中插入数据, 每张表插入10行。
  2. $tables = array();
  3. for($i = 0; $i < 3; $i++) {
  4. $rows = array();
  5. for($j = 0; $j < 10; $j++) {
  6. $rows[] = [
  7. 'operation_type' => OperationTypeConst::CONST_PUT, //操作是PUT
  8. 'condition' => RowExistenceExpectationConst::CONST_IGNORE,
  9. 'primary_key' => [
  10. ['pk0', $i],
  11. ['pk1', $j]
  12. ],
  13. 'attribute_columns' => [
  14. ['Col0', 4],
  15. ['Col2', '成杭京']
  16. ]
  17. ];
  18. }
  19. $tables[] = [
  20. 'table_name' => 'SampleTable' . $i,
  21. 'rows' => $rows
  22. ];
  23. }
  24. $request = [
  25. 'tables' => $tables
  26. ];
  27. $response = $otsClient->batchWriteRow ($request);
  28. // 处理返回的每个表
  29. foreach ($response['tables'] as $tableData) {
  30. print "Handling table {$tableData['table_name']} ...\n";
  31. // 处理这个表下的PutRow返回的结果
  32. $putRows = $tableData['rows'];
  33. foreach ($putRows as $rowData) {
  34. if ($rowData['is_ok']) {
  35. // 写入成功
  36. print "Capacity Unit Consumed: {$rowData['consumed']['capacity_unit']['write']}\n";
  37. } else {
  38. // 处理出错
  39. print "Error: {$rowData['error']['code']} {$rowData['error']['message']}\n";
  40. }
  41. }
  42. }
  • 更详细的可以参考
示例文件 示例内容
BatchWriteRow1.php 展示了BatchWriteRow中多个PUT的用法
BatchWriteRow2.php 展示了BatchWriteRow中多个UPDATE的用法
BatchWriteRow3.php 展示了BatchWriteRow中多个DELETE的用法
BatchWriteRow4.php 展示了BatchWriteRow中混合进行UPDATE,PUT,DELETE的用法
BatchWriteRowWithColumnFilter.php 展示了BatchWriteRow的同时进行条件更新的用法

范围读(GetRange)

API说明

读取指定主键范围内的数据。

范围读取接口用于读取一个范围内的数据。表格存储表中的行都是按照主键排序的,而主键是由全部主键列按照顺序组成的,所以不能理解为表格存储会按照某列主键排序,这是常见的误区。

GetRange 接口支持按照给定范围正序读取和反序读取,可以限定要读取的行数。如果范围较大,已经扫描的行数或者数据量超过一定限制,会停止继续扫描,返回已经获取的行和下一个主键的位置。用户可以根据返回的下一个主键位置,继续发起请求,获取范围内剩余的行。

接口

  1. /**
  2. * 范围读取起始主键和结束主键之间的数据。
  3. * 请注意,这个范围有可能会被服务端截断,你需要判断返回中的 next_start_primary_key 来决定是否继续调用 GetRange。
  4. * 你可以指定最多读取多少行。
  5. * 在指定开始主键和结束主键时,你可以用 INF_MIN 和 INF_MAX 来代表最大值和最小值,详见下面的代码样例。
  6. * API说明:https://help.aliyun.com/document_detail/27309.html
  7. * @api
  8. * @param [] $request 请求参数
  9. * @return [] 请求返回
  10. * @throws OTSClientException 当参数检查出错或服务端返回校验出错时
  11. * @throws OTSServerException 当OTS服务端返回错误时
  12. */
  13. public function getRange(array $request);

请求格式

  1. $result = $client->getRange([
  2. 'table_name' => '<string>', // REQUIRED
  3. 'inclusive_start_primary_key' => [ // REQUIRED
  4. ['<string>', <PrimaryKeyValue>],
  5. ['<string>', <PrimaryKeyValue>],
  6. ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
  7. ],
  8. 'exclusive_end_primary_key' => [ // REQUIRED
  9. ['<string>', <PrimaryKeyValue>],
  10. ['<string>', <PrimaryKeyValue>],
  11. ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
  12. ],
  13. 'direction' => <Direction>, // REQUIRED
  14. 'limit' => <Direction>,
  15. 'max_versions' => <integer>,
  16. 'time_range' => [
  17. 'start_time' => <integer>,
  18. 'end_time' => <integer>,
  19. 'specific_time' => <integer>
  20. ],
  21. 'start_column' => '<string>',
  22. 'end_column' => '<string>',
  23. 'token' => '<string>',
  24. 'columns_to_get' => [
  25. '<string>',
  26. '<string>',
  27. //...
  28. ],
  29. 'column_filter' => <ColumnCondition>
  30. ]);

请求格式说明

  • 和GetRow的区别
    • primary_key 变成 inclusive_start_primary_key,exclusive_end_primary_key,前闭后开区间。
    • 增加 direction 表示方向。
    • 增加 limit 限制返回行数。
  • table_name 表名。必须设置。
  • inclusive_start_primary_key 本次范围读取的起始主键,若该行存在,则响应中一定会包含此行。(必须设置)。
    • 表的主键可包含多个主键列。主键列是有顺序的,与用户添加的顺序相同。比如 PRIMARY KEY (A, B, C) 与 PRIMARY KEY (A, C, B) 是不同的两个主键结构。表格存储会按照整个主键的大小对行进行排序,具体请参见表格存储数据模型和查询操作
    • 每一项的顺序是 主键名、主键值、主键类型PrimaryKeyType(可选)。
    • PrimaryKeyValue可以是整数和字符串。
    • PrimaryKeyType可以是INTEGER、STRING(UTF-8编码字符串)、BINARY三种,分别用PrimaryKeyTypeConst::CONST_INTEGER,PrimaryKeyTypeConst::CONST_STRING,PrimaryKeyTypeConst::CONST_BINARY表示,对于INTEGER和STRING,可以省略,其它类型不可省略。
    • PrimaryKeyType有两种特定类型,INF_MIN, INF_MAX。类型为 INF_MIN 的 Column 永远小于其它 Column;类型为 INF_MAX 的 Column 永远大于其它 Column。
    • 分别用PrimaryKeyTypeConst::CONST_INF_MIN,PrimaryKeyTypeConst::CONST_INF_MAX表示。对应的primaryKeyValue可以设置为null.
  • exclusive_end_primary_key 本次范围读取的终止主键,无论该行是否存在,响应中都不会包含此行。(必须设置)。
    • 表的主键可包含多个主键列。主键列是有顺序的,与用户添加的顺序相同。比如 PRIMARY KEY (A, B, C) 与 PRIMARY KEY (A, C, B) 是不同的两个主键结构。表格存储会按照整个主键的大小对行进行排序,具体请参见表格存储数据模型和查询操作
    • 每一项的顺序是 主键名、主键值、主键类型PrimaryKeyType(可选)。
    • PrimaryKeyValue可以是整数和字符串。
    • PrimaryKeyType可以是INTEGER、STRING(UTF-8编码字符串)、BINARY三种,分别用PrimaryKeyTypeConst::CONST_INTEGER,PrimaryKeyTypeConst::CONST_STRING,PrimaryKeyTypeConst::CONST_BINARY表示,对于INTEGER和STRING,可以省略,其它类型不可省略。
    • PrimaryKeyType有两种特定类型,INF_MIN, INF_MAX。类型为 INF_MIN 的 Column 永远小于其它 Column;类型为 INF_MAX 的 Column 永远大于其它 Column。
    • 分别用PrimaryKeyTypeConst::CONST_INF_MIN,PrimaryKeyTypeConst::CONST_INF_MAX表示。对应的primaryKeyValue可以设置为null.
  • direction 本次查询的顺序(必须设置)。若为正序(DirectionConst::CONST_FORWARD),则 inclusive_start_primary 应小于 exclusive_end_primary,响应中各行按照主键由小到大的顺序进行排列;若为逆序(DirectionConst::CONST_BACKWARD),则 inclusive_start_primary 应大于 exclusive_end_primary,响应中各行按照主键由大到小的顺序进行排列。
  • limit 本次读取最多返回的行数。
    • 若查询到的行数超过此值,则通过响应中包含的断点记录本次读取到的位置,以便下一次读取。此值必须大于 0。
    • 无论是否设置此值,表格存储最多返回行数为 5000 且总数据大小不超过 4 M 。
  • max_versions 最多读取多少个版本(常用)。
  • time_range 要读取的版本号的范围。参见TimeRange
    • start_time 起始时间戳。单位是毫秒。时间戳的取值最小值为0,最大值为INT64.MAX。若要查询一个范围,则指定start_time和end_time,前闭后开区间。
    • end_time 结束时间戳。单位是毫秒。时间戳的取值最小值为0,最大值为INT64.MAX。
    • specific_time 特定的时间戳值,若要查询一个特定时间戳,则指定specific_time。specific_time和[start_time, end_time) 两个中设置一个即可。单位是毫秒。时间戳的取值最小值为0,最大值为INT64.MAX。
  • max_versions 与 time_range 必须至少设置一个。
    • 如果仅指定 max_versions,则返回所有版本里从新到旧至多指定数量个数据。
    • 如果仅指定 time_range,则返回该范围内所有数据。
    • 如果同时指定 max_versions 和 time_range,则返回版本范围内从新到旧至多指定数量个数据。
  • 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 过滤条件,满足条件才会返回。和condition里面的column_condition类似。参见过滤器

结果格式

  1. [
  2. 'consumed' => [
  3. 'capacity_unit' => [
  4. 'read' => <integer>,
  5. 'write' => <integer>
  6. ]
  7. ],
  8. 'next_start_primary_key' => [
  9. ['<string>', <PrimaryKeyValue>],
  10. ['<string>', <PrimaryKeyValue>],
  11. ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
  12. ],
  13. 'rows' => [
  14. [
  15. 'primary_key' => [
  16. ['<string>', <PrimaryKeyValue>],
  17. ['<string>', <PrimaryKeyValue>],
  18. ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
  19. ],
  20. 'attribute_columns' => [
  21. ['<string>', <ColumnValue>, <ColumnType>, <integer>]
  22. ['<string>', <ColumnValue>, <ColumnType>, <integer>]
  23. ['<string>', <ColumnValue>, <ColumnType>, <integer>]
  24. ]
  25. ],
  26. // other rows
  27. ]
  28. ]

结果格式说明

  • API说明 (详细解说,务必查阅!!!)
  • consumed 本次操作消耗服务能力单元的值。
    • capacity_unit 使用的读写单元量
      • read 读吞吐量
      • write 写吞吐量
  • rows
    • 读取到的所有数据,若请求中 direction 为 FORWARD,则所有行按照主键由小到大进行排序;若请求中 direction 为 BACKWARD,则所有行按照主键由大到小进行排序。
    • 其中每行的 attribute_columns 只包含在 columns_to_get 中指定的列,其顺序不保证与 request 中的 columns_to_get 一致
    • 如果请求中指定的 columns_to_get 不含有任何主键列,那么其主键在查询范围内。但没有任何一个属性列在 columns_to_get 中的行将不会出现在响应消息里。
    • primary_key 主键的值,和请求一致。设置返回PK的时候会有值,主要用于主键列自增。
    • 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表示。
      • 时间戳是64bit整数,用来表示属性的多个不同的版本
      • 返回结果中的属性会按照属性名的字典序升序,属性的多个版本按时间戳降序。
  • next_start_primary_key 本次 GetRange 操作的断点信息。
    • 格式和primary_key一样。
    • 若为空,则本次 GetRange 的响应消息中已包含了请求范围内的所有数据。
    • 若不为空,则表示本次 GetRange 的响应消息中只包含了 [inclusive_start_primary_key, next_start_primary_key) 间的数据,若需要剩下的数据,需要将 next_start_primary_key 作为 inclusive_start_primary_key,原始请求中的 exclusive_end_primary_key 作为 exclusive_end_primary_key 继续执行 GetRange 操作。

示例

按照范围读取。

  1. // 这里查找uid从1-4(左闭右开)的数据
  2. // 范围的边界需要提供完整的PK,若查询的范围不涉及到某一列值的范围,则需要将该列设置为无穷大或者无穷小
  3. $startPK = [
  4. ['PK0', 1],
  5. ['PK1', null, PrimaryKeyTypeConst::CONST_INF_MIN] // 'INF_MIN' 用来表示最小值
  6. ];
  7. // 范围的边界需要提供完整的PK,若查询的范围不涉及到某一列值的范围,则需要将该列设置为无穷大或者无穷小
  8. $endPK = [
  9. ['PK0', 4],
  10. ['PK1', null, PrimaryKeyTypeConst::CONST_INF_MAX] // 'INF_MAX' 用来表示最大值
  11. ];
  12. $request = [
  13. 'table_name' => 'SampleTable',
  14. 'max_versions' => 1, // 设置读取最新版本
  15. 'direction' => DirectionConst::CONST_FORWARD, // 前向查询
  16. 'inclusive_start_primary_key' => $startPK, // 开始主键
  17. 'exclusive_end_primary_key' => $endPK, // 结束主键
  18. 'limit' => 10 // 最多返回10行
  19. ];
  20. $response = $otsClient->getRange ($request);
  21. print "Read CU Consumed: {$response['consumed']['capacity_unit']['read']}\n";
  22. foreach ($response['rows'] as $rowData) {
  23. // 处理每一行数据
  24. }
  • 更详细的可以参考
示例文件 示例内容
GetRange1.php 展示了GetRange的用法
GetRange2.php 展示了GetRange指定获取列的用法
GetRange3.php 展示了GetRange指定获取行数限制的用法
GetRangeWithColumnFilter.php 展示了GetRange同时进行条件过滤的用法
本文导读目录