GetRange - Tablestore - Centro de documentación de Alibaba Cloud

Lee los datos cuyos valores de clave principal se encuentran dentro del rango especificado.

Sintaxis de la solicitud

message GetRangeRequest {
    required string table_name = 1;
    required Direction direction = 2;
    repeated string columns_to_get = 3; // If you do not specify this parameter, all columns are read. 
    optional TimeRange time_range = 4;
    optional int32 max_versions = 5;
    optional int32 limit = 6;
    required bytes inclusive_start_primary_key = 7; // The start primary key information is encoded as binary data in the PlainBuffer format. 
    required bytes exclusive_end_primary_key = 8; // The end primary key information is encoded as binary data in the PlainBuffer format. 
    optional bytes filter = 10;
    optional string start_column = 11;
    optional string end_column = 12;
}

Parámetro	Tipo	Obligatorio	Descripción
table_name	string	Sí	Nombre de la tabla.
direction	Direction	Sí	Orden en el que desea ordenar las filas de la respuesta. Si establece este parámetro en FORWARD, el valor de inclusive_start_primary_key debe ser menor que el de exclusive_end_primary_key. Las filas de la respuesta se ordenan de forma ascendente según los valores de la clave principal. Si establece este parámetro en BACKWARD, el valor de inclusive_start_primary_key debe ser mayor que el de exclusive_end_primary_key. Las filas de la respuesta se ordenan de forma descendente según los valores de la clave principal.
columns_to_get	repeated string	No	Nombres de las columnas que desea devolver. Este parámetro admite un máximo de 128 cadenas. Si no especifica este parámetro, se devuelven todas las columnas de las filas que cumplen las condiciones de consulta. Si ninguna columna de una fila cumple las condiciones de consulta, la fila no se devuelve y el valor devuelto es null. Si una fila contiene algunas columnas que sí cumplen dichas condiciones, la fila se devuelve con solo esas columnas en la respuesta. Si existen nombres de columna duplicados, la respuesta incluye la columna una sola vez.
time_range	TimeRange	No. Solo uno de los parámetros max_versions o time_range es obligatorio.	Rango de marcas de tiempo de los datos que desea leer. Valores válidos: de 0 a `INT64.MAX`. Unidad: milisegundos. Para consultar datos dentro de un rango de marcas de tiempo, especifique start_time y end_time. El valor de time_range es un intervalo cerrado por la izquierda y abierto por la derecha. Por ejemplo: `[start_time, end_time)`. Si establece este parámetro en `[100, 200)`, la marca de tiempo de los datos en las columnas devueltas debe estar dentro del rango `[100, 200)`. Para consultar datos en una marca de tiempo específica, indique specific_time.
max_versions	int32	No. Solo uno de los parámetros max_versions o time_range es obligatorio.	Número máximo de versiones de datos que desea devolver. Por ejemplo, si el valor de max_versions es 2, se devuelve un máximo de dos versiones de datos por cada columna.
limit	int32	No	Número máximo de filas que desea devolver. El valor de este parámetro debe ser mayor que 0. Si la cantidad de filas que cumplen las condiciones de consulta supera este valor, la respuesta contiene un punto de interrupción que registra la posición donde terminó la lectura. La siguiente operación de lectura comenzará desde dicha posición. Tablestore devuelve hasta 5,000 filas de datos, independientemente de si especifica este parámetro. El tamaño total de las filas devueltas no puede superar los 4 MB.
inclusive_start_primary_key	bytes	Sí	Información de la clave principal desde donde inicia la lectura. Esta información se codifica en formato PlainBuffer. Para obtener más información, consulte PlainBuffer. Si una fila contiene la columna de clave principal inicial, se incluye en la respuesta.
exclusive_end_primary_key	bytes	Sí	Información de la clave principal donde finaliza la lectura. Esta información se codifica en formato PlainBuffer. Para obtener más información, consulte PlainBuffer. Si una fila contiene la columna de clave principal final, se excluye de la respuesta. En la operación GetRange, las columnas de clave principal en los valores de inclusive_start_primary_key y exclusive_end_primary_key pueden usar tipos exclusivos de esta operación: INF_MIN e INF_MAX. INF_MIN representa un valor infinitamente pequeño. Si una columna de clave principal tiene el tipo INF_MIN, sus valores son menores que los de cualquier otra columna. INF_MAX representa un valor infinitamente grande. Si una columna de clave principal tiene el tipo INF_MAX, sus valores son mayores que los de cualquier otra columna.
filter	bytes	No	Expresiones de las condiciones de filtro. Estas expresiones se serializan como datos binarios mediante Protobuf. Para obtener más información, consulte Filter.
start_column	string	No	Columna desde la cual inicia la lectura dentro de una fila. Este parámetro se utiliza para lecturas de columnas anchas. La respuesta incluye la columna inicial especificada. Las columnas se ordenan alfabéticamente según su nombre. Si una tabla contiene las columnas a, b y c, y el valor de start_column es b, la lectura comienza en la columna b y se devuelven las columnas b y c.
end_column	string	No	Columna donde finaliza la lectura dentro de una fila. Este parámetro se utiliza para lecturas de columnas anchas. La respuesta excluye la columna final especificada. Las columnas se ordenan alfabéticamente según su nombre. Si una tabla contiene las columnas a, b y c, y el valor de end_column es b, la lectura termina en la columna b y solo se devuelve la columna a.

Sintaxis de la respuesta

message GetRangeResponse {
    required ConsumedCapacity consumed = 1;
    required bytes rows = 2; 
    optional bytes next_start_primary_key = 3; 
}

Parámetro	Tipo	Descripción
consumed	ConsumedCapacity	Número de unidades de capacidad (CU) consumidas por la operación. Para obtener más información, consulte CU consumption.
rows	bytes	Filas que devuelve la operación. Estas filas se codifican en formato PlainBuffer. Para obtener más información, consulte PlainBuffer. Si el parámetro direction de la solicitud se establece en FORWARD, las filas de la respuesta se ordenan de forma ascendente según los valores de la clave principal. Si el parámetro direction de la solicitud se establece en BACKWARD, las filas de la respuesta se ordenan de forma descendente según los valores de la clave principal. Las columnas de clave principal y las columnas de atributos de cada fila en la respuesta incluyen únicamente las columnas que especificó en columns_to_get dentro de la solicitud. El orden de las columnas en la respuesta puede diferir del orden indicado en columns_to_get. Asimismo, el orden de las columnas de clave principal en la respuesta puede diferir del definido al crear la tabla. Si el valor de columns_to_get en la solicitud no contiene una columna de clave principal, se excluyen de la respuesta aquellas filas que no contengan las columnas de atributos indicadas en dicho parámetro. Esto ocurre incluso si los valores de clave principal de esas filas están dentro del rango de consulta.
next_start_primary_key	bytes	Punto de interrupción que registra la posición donde finalizó la lectura. Este punto se codifica en formato PlainBuffer. Para obtener más información, consulte PlainBuffer. Si el valor devuelto está vacío, la operación GetRange devolvió todos los datos que cumplen las condiciones de consulta. Si el valor devuelto no está vacío, la operación GetRange devolvió únicamente los datos dentro del rango `[inclusive_start_primary_key, next_start_primary_key)`. Para obtener los datos restantes, establezca inclusive_start_primary_key con el valor de next_start_primary_key. Conserve el valor de exclusive_end_primary_key de la solicitud original y vuelva a llamar a la operación GetRange. Nota La operación GetRange puede devolver hasta 5,000 filas por cada solicitud. El tamaño total de los datos en dichas filas no puede superar los 4 MB. La respuesta a una solicitud GetRange puede contener un valor para next_start_primary_key, incluso si no especificó un límite en la solicitud. Al llamar a la operación GetRange, compruebe siempre si la respuesta incluye next_start_primary_key.

Uso de los SDK de Tablestore

A continuación se muestran los SDK de Tablestore que puede utilizar para leer datos cuyos valores de clave principal se encuentren dentro de un rango específico:

SDK de Tablestore para Java: Read data whose primary key values are in the specified range
SDK de Tablestore para Go: Read data whose primary key values are in the specified range
SDK de Tablestore para Python: Read data whose primary key values are in the specified range
SDK de Tablestore para Node.js: Read data whose primary key values are in the specified range
SDK de Tablestore para .NET: Read data whose primary key values are in the specified range
SDK de Tablestore para PHP: Read data whose primary key values are in the specified range

Consumo de CU

El número de CU de lectura consumidas por la operación GetRange se redondea hacia arriba a partir de la siguiente fórmula: CU de lectura consumidas = (Tamaño de los datos en todas las columnas de clave principal de las filas que cumplen las condiciones de consulta + Tamaño de los datos en las columnas de atributos leídas) / 4 KB. Para obtener más información sobre cómo calcular el tamaño de los datos, consulte Data almacenamiento.
Si la solicitud excede el tiempo de espera y los resultados quedan indefinidos, es posible que se consuman CU o que no se consuman.
Si se devuelve un código de estado HTTP 5xx, lo cual indica que ocurrió un error interno, la operación no consume CU. Si se devuelven otros errores, se consume una CU de lectura.