多行操作_PHP SDK_SDK 参考_表格存储-阿里云

表格存储的 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说明（介绍了整体失败和部分失败的几种情况，务必查阅。）
MaxCompute
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有效。
  - UPDATE. primary_key 和 update_of_attribute_columns有效。
  - DELETE. primary_key有效。
- 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同时进行条件过滤的用法