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

批量读(BatchGetRow)

API说明

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

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

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

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

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

接口
    /**
     * 读取指定的多行数据。
     * API说明:https://help.aliyun.com/document_detail/27310.html
     * 请注意,BatchGetRow在部分行读取失败时,会在返回的$response中表示,而不是抛出异常。请参见样例:处理BatchGetRow的返回。
     * @api
     * @param [] $request 请求参数
     * @return [] 请求返回 
     * @throws OTSClientException 当参数检查出错或服务端返回校验出错时
     * @throws OTSServerException 当OTS服务端返回错误时
     */
    public function batchGetRow(array $request);  
请求格式
$result = $client->batchGetRow([
    'tables' => [                                            // REQUIRED
        [
            'table_name' => '<string>',                      // REQUIRED
            'primary_keys' => [                              // REQUIRED
                [
                    ['<string>', <PrimaryKeyValue>], 
                    ['<string>', <PrimaryKeyValue>],
                    ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
                ], 
                // other primary keys
            ]
            '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>
        ],
        // other tables.
    ]
]);

请求格式说明
  • 和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类似。参见过滤器
结果格式
[
    '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>'
                ],
                // other rows
            ]
        ],
        // other tables.
    ]
]
结果格式说明
  • 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 行。

    // 从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的同时进行条件过滤的用法

批量写(BatchWriteRow)

API说明

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

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

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

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

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

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

$result = $client->batchWriteRow([
    'tables' => [                                            // REQUIRED
        [
            'table_name' => '<string>',                      // REQUIRED
            'operation_type' => <OperationType>,
            'condition' => [
                'row_existence' => <RowExistence>,   
                'column_condition' => <ColumnCondition>
            ],
            'primary_key' => [                               // REQUIRED
                ['<string>', <PrimaryKeyValue>], 
                ['<string>', <PrimaryKeyValue>],
                ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
            ], 
            'attribute_columns' => [                        // REQUIRED in PUT
                    ['<string>', <ColumnValue>], 
                    ['<string>', <ColumnValue>, <ColumnType>],
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>]
            ],
            'update_of_attribute_columns' => [               // REQUIRED in 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>
            ]
        ],
        // other tables.
    ]
]);

请求格式说明
  • 本操作是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 表示返回主键值(主要用于主键列自增场景)

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

批量导入 30 行数据。

    // 向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的同时进行条件更新的用法

范围读(GetRange)

API说明

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

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

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

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

$result = $client->getRange([
    'table_name' => '<string>',                                     // REQUIRED
    'inclusive_start_primary_key' => [                              // REQUIRED
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'exclusive_end_primary_key' => [                                // REQUIRED
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'direction' => <Direction>,                                     // REQUIRED
    '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>
]);

请求格式说明
  • 和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类似。参见过滤器
结果格式
[
    '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>]
            ]
        ],
        // other rows
    ]
]
结果格式说明
  • 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 操作。
示例

按照范围读取。

    // 这里查找uid从1-4(左闭右开)的数据
    // 范围的边界需要提供完整的PK,若查询的范围不涉及到某一列值的范围,则需要将该列设置为无穷大或者无穷小
    $startPK = [
        ['PK0', 1], 
        ['PK1', null, PrimaryKeyTypeConst::CONST_INF_MIN]  // 'INF_MIN' 用来表示最小值
    ];
    // 范围的边界需要提供完整的PK,若查询的范围不涉及到某一列值的范围,则需要将该列设置为无穷大或者无穷小
    $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同时进行条件过滤的用法