GetRange__API 概览_API 参考_表格存储-阿里云

行为：

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

请求结构：

message GetRangeRequest {
    required string table_name = 1;
    required Direction direction = 2;
    repeated string columns_to_get = 3;
    optional int32 limit = 4;
    repeated Column inclusive_start_primary_key = 5;
    repeated Column exclusive_end_primary_key = 6;
    optional ColumnCondition filter = 7;
}

table_name：

类型：string。
是否必要参数：是。
要读取的数据所在的表名。

direction：

类型：Direction。
是否必要参数：是。
本次查询的顺序。若为正序，则 inclusive_start_primary 应小于 exclusive_end_primary，响应中各行按照主键由小到大的顺序进行排列；若为逆序，则 inclusive_start_primary 应大于 exclusive_end_primary，响应中各行按照主键由大到小的顺序进行排列。

columns_to_get：

类型：repeated string。
是否必要参数：否。
需要返回的全部列的列名。若为空，则返回读取结果中每行的所有列。
如果给出了重复的列名，返回结果只会包含一次该列。
columns_to_get 中 string 的个数不应超过 128 个。

limit：

类型：int32。
是否必要参数：否。
本次读取最多返回的行数，若查询到的行数超过此值，则通过响应中包含的断点记录本次读取到的位置，以便下一次读取。此值必须大于 0。
无论是否设置此值，表格存储最多返回行数为 5000 且总数据大小不超过 1 M 。

inclusive_start_primary_key：

类型: repeated Column。
是否必要参数: 是。
本次范围读取的起始主键，若该行存在，则响应中一定会包含此行。

exclusive_end_primary_key：

类型：repeated Column。
是否必要参数：是。
本次范围读取的终止主键，无论该行是否存在，响应中都不会包含此行。
在 GetRange 中，inclusive_start_primary_key 和 exclusive_end_primary_key 中的 Column 的 type 可以使用本操作专用的两个类型 INF_MIN 和 INF_MAX。类型为 INF_MIN 的 Column 永远小于其它 Column；类型为 INF_MAX 的 Column 永远大于其它 Column。

filter：

类型：ColumnCondition。
是否必要参数：否。
过滤条件表达式。

响应消息结构：

message GetRangeResponse {
    required ConsumedCapacity consumed = 1;
    repeated Column next_start_primary_key = 2;
    repeated Row rows = 3;
}

consumed：

类型：ConsumedCapacity。
本次操作消耗的服务能力单元。

next_start_primary_key：

类型：repeated Column。
本次 GetRange 操作的断点信息。
若为空，则本次 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 操作。

注意：表格存储系统中限制了 GetRange 操作的响应消息中数据不超过 5000 行，大小不超过 4 M，并且返回的数据量不超过当前剩余的预留读吞吐量。即使在 GetRange 请求中未设定 limit，在响应中仍可能出现 next_start_primary_key。因此在使用 GetRange 时一定要对响应中是否有 next_start_primary_key 进行处理。

rows：

类型：repeated Row。
读取到的所有数据，若请求中 direction 为 FORWARD，则所有行按照主键由小到大进行排序；若请求中 direction 为 BACKWARD，则所有行按照主键由大到小进行排序。
其中每行的 primary_key_columns 和 attribute_columns 均只包含在 columns_to_get 中指定的列，其顺序不保证与 request 中的 columns_to_get 一致；primary_key_columns 的顺序亦不保证与建表时指定的顺序一致。
如果请求中指定的 columns_to_get 不含有任何主键列，那么其主键在查询范围内。但没有任何一个属性列在 columns_to_get 中的行将不会出现在响应消息里。

服务能力单元消耗：

GetRange 操作消耗读服务能力单元的数值为查询范围内所有行主键数据大小与实际读取的属性列数据大小之和除以 4 KB 向上取整。关于数据大小的计算请参见购买指导。
如果请求超时，结果未定义，服务能力单元有可能被消耗，也可能未被消耗。
如果返回内部错误（HTTP 状态码：5XX），则此次操作不消耗服务能力单元，其他错误情况消耗 1 个读服务能力单元。

请求示例：

GetRangeRequest {
  table_name: "consume_history"
  direction: FORWARD
  columns_to_get: "CardID"
  columns_to_get: "SellerID"
  columns_to_get: "DeviceID"
  columns_to_get: "OrderNumber"
  columns_to_get: "Amount"
  columns_to_get: "Remarks"
  limit: 2
  inclusive_start_primary_key {
    name: "CardID"
    value {
      type: STRING
      v_string: "2007035023"
    }
  }
  inclusive_start_primary_key {
    name: "SellerID"
    value {
      type: INF_MIN
    }
  }
  inclusive_start_primary_key {
    name: "DeviceID"
    value {
      type: INF_MIN
    }
  }
  inclusive_start_primary_key {
    name: "OrderNumber"
    value {
      type: INF_MIN
    }
  }
  exclusive_end_primary_key {
    name: "CardID"
    value {
      type: STRING
      v_string: "2007035023"
    }
  }
  exclusive_end_primary_key {
    name: "SellerID"
    value {
      type: INF_MIN
    }
  }
  exclusive_end_primary_key {
    name: "DeviceID"
    value {
      type: INF_MIN
    }
  }
  exclusive_end_primary_key {
    name: "OrderNumber"
    value {
      type: INF_MIN
    }
  }
}

响应示例：

consumed {
  capacity_unit {
    read: 1
  }
}
next_start_primary_key {
  name: "CardID"
  value {
    type: STRING
    v_string: "2007035023"
  }
}
next_start_primary_key {
  name: "SellerID"
  value {
    type: STRING
    v_string: "00026"
  }
}
next_start_primary_key {
  name: "DeviceID"
  value {
    type: STRING
    v_string: "065499"
  }
}
next_start_primary_key {
  name: "OrderNumber"
  value {
    type: INTEGER
    v_int: 166666
  }
}
rows {
  primary_key_columns {
    name: "CardID"
    value {
      type: STRING
      v_string: "2007035023"
    }
  }
  primary_key_columns {
    name: "SellerID"
    value {
      type: STRING
      v_string: "00022"
    }
  }
  primary_key_columns {
    name: "DeviceID"
    value {
      type: STRING
      v_string: "061104"
    }
  }
  primary_key_columns {
    name: "OrderNumber"
    value {
      type: INTEGER
      v_int: 142857
    }
  }
  attribute_columns {
    name: "Amount"
    value {
      type: DOUBLE
      v_double: 2.5
    }
  }
  attribute_columns {
    name: "Remarks"
    value {
      type: STRING
      v_string: "ice cream"
    }
  }
}
rows {
  primary_key_columns {
    name: "CardID"
    value {
      type: STRING
      v_string: "2007035023"
    }
  }
  primary_key_columns {
    name: "SellerID"
    value {
      type: STRING
      v_string: "00026"
    }
  }
  primary_key_columns {
    name: "DeviceID"
    value {
      type: STRING
      v_string: "065499"
    }
  }
  primary_key_columns {
    name: "OrderNumber"
    value {
      type: INTEGER
      v_int: 153846
    }
  }
  attribute_columns {
    name: "Amount"
    value {
      type: DOUBLE
      v_double: 0.5
    }
  }
}

最后更新：2016-11-23 16:03:56