GetRange - Tablestore: Central de Documentação do Alibaba Cloud

Sintaxe da requisição

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	Obrigatório	Descrição
table_name	string	Sim	O nome da tabela.
direction	Direction	Sim	A ordem de classificação das linhas na resposta. Se você definir este parâmetro como FORWARD, o valor de inclusive_start_primary_key deverá ser menor que o valor de exclusive_end_primary_key, e as linhas na resposta serão ordenadas de forma crescente pelos valores de chave primária. Se você definir este parâmetro como BACKWARD, o valor de inclusive_start_primary_key deverá ser maior que o valor de exclusive_end_primary_key, e as linhas na resposta serão ordenadas de forma decrescente pelos valores de chave primária.
columns_to_get	repeated string	Não	Os nomes das colunas a retornar. O valor deste parâmetro pode conter até 128 strings. Se você não especificar este parâmetro, todas as colunas das linhas que atendem às condições da consulta serão retornadas. Se nenhuma coluna de uma linha atender às condições da consulta, a linha não será retornada e o valor de retorno será nulo. Caso a linha contenha apenas algumas das colunas que atendem às condições, a linha será retornada com somente essas colunas na resposta. Se houver nomes de coluna duplicados, a resposta incluirá a coluna apenas uma vez.
time_range	TimeRange	Não. Apenas um entre max_versions e time_range é obrigatório.	O intervalo de timestamp dos dados a ler. Valores válidos: 0 a `INT64.MAX`. Unidade: milissegundo. Para consultar dados dentro de um intervalo de timestamp, especifique start_time e end_time. O valor de time_range é um intervalo fechado à esquerda e aberto à direita. Exemplo: `[start_time, end_time)`. Se você definir este parâmetro como `[100, 200)`, o timestamp dos dados nas colunas retornadas deverá estar no intervalo de `[100, 200)`. Para consultar dados em um timestamp específico, especifique specific_time.
max_versions	int32	Não. Apenas um entre max_versions e time_range é obrigatório.	O número máximo de versões de dados a retornar. Por exemplo, se o valor de max_versions for 2, no máximo duas versões de dados serão retornadas para cada coluna.
limit	int32	Não	O número máximo de linhas a retornar. O valor deste parâmetro deve ser maior que 0. Se a quantidade de linhas que atendem às condições da consulta exceder o valor deste parâmetro, a resposta conterá um ponto de interrupção que registra a posição em que a operação de leitura terminou. A próxima operação de leitura começa a partir dessa posição. O Tablestore retorna no máximo 5.000 linhas de dados, independentemente de você especificar ou não este parâmetro. O tamanho total das linhas retornadas não pode exceder 4 MB.
inclusive_start_primary_key	bytes	Sim	As informações de chave primária a partir das quais a operação de leitura começa. Essas informações são codificadas no formato PlainBuffer. Para mais informações, consulte PlainBuffer. Se uma linha contiver a coluna de chave primária inicial, essa linha será incluída na resposta.
exclusive_end_primary_key	bytes	Sim	As informações de chave primária nas quais a operação de leitura termina. Essas informações são codificadas no formato PlainBuffer. Para mais informações, consulte PlainBuffer. Se uma linha contiver a coluna de chave primária final, essa linha será excluída da resposta. Na operação GetRange, as colunas de chave primária nos valores de inclusive_start_primary_key e exclusive_end_primary_key podem ser um dos seguintes tipos dedicados a essa operação: INF_MIN e INF_MAX. INF_MIN indica um valor infinitamente pequeno. Quando o tipo de uma coluna de chave primária é INF_MIN, seus valores são menores que os de outras colunas. INF_MAX indica um valor infinitamente grande. Quando o tipo de uma coluna de chave primária é INF_MAX, seus valores são maiores que os de outras colunas.
filter	bytes	Não	As expressões das condições de filtro. Essas expressões são serializadas como dados binários por meio do Protobuf. Para mais informações, consulte Filter.
start_column	string	Não	A coluna a partir da qual a operação de leitura começa em uma linha. Este parâmetro é utilizado para leitura de colunas amplas. A resposta inclui a coluna inicial especificada. As colunas são ordenadas alfabeticamente por nome. Se uma tabela contiver as colunas a, b e c e o valor de start_column for b, a operação de leitura começa na coluna b, e as colunas b e c são retornadas.
end_column	string	Não	A coluna na qual a operação de leitura termina em uma linha. Este parâmetro é utilizado para leitura de colunas amplas. A resposta exclui a coluna final especificada. As colunas são ordenadas alfabeticamente por nome. Se uma tabela contiver as colunas a, b e c e o valor de end_column for b, a operação de leitura termina na coluna b, e apenas a coluna a é retornada.

Sintaxe da resposta

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

Parâmetro	Tipo	Descrição
consumed	ConsumedCapacity	O número de unidades de capacidade (CUs) consumidas pela operação. Para mais informações, consulte Consumo de CUs.
rows	bytes	As linhas retornadas pela operação, codificadas no formato PlainBuffer. Para mais informações, consulte PlainBuffer. Se direction na requisição estiver definido como FORWARD, as linhas na resposta são ordenadas de forma crescente pelos valores de chave primária. Se direction na requisição estiver definido como BACKWARD, as linhas na resposta são ordenadas de forma decrescente pelos valores de chave primária. As colunas de chave primária e as colunas de atributo de cada linha na resposta incluem somente as colunas especificadas em columns_to_get na requisição. A ordem das colunas na resposta pode diferir da ordem especificada em columns_to_get. Da mesma forma, a ordem das colunas de chave primária na resposta pode diferir da ordem definida na criação da tabela. Se o valor de columns_to_get na requisição não contiver uma coluna de chave primária, as linhas cujos valores de chave primária estejam dentro do intervalo de consulta, mas que não possuam as colunas de atributo especificadas em columns_to_get, serão excluídas da resposta.
next_start_primary_key	bytes	O ponto de interrupção que registra a posição em que a operação de leitura terminou. Esse ponto de interrupção é codificado no formato PlainBuffer. Para mais informações, consulte PlainBuffer. Se o valor de retorno estiver vazio, a operação GetRange retornou todos os dados que atendem às condições da consulta. Se o valor de retorno não estiver vazio, a operação GetRange retornou apenas os dados dentro do intervalo `[inclusive_start_primary_key, next_start_primary_key)`. Para obter os dados restantes, defina inclusive_start_primary_key com o valor de next_start_primary_key, mantenha o valor de exclusive_end_primary_key da requisição original e chame a operação GetRange novamente. Nota A operação GetRange pode retornar no máximo 5.000 linhas por requisição. O tamanho total dos dados nas linhas não pode exceder 4 MB. A resposta de uma requisição GetRange pode conter um valor de next_start_primary_key mesmo que você não especifique um limit na requisição. Ao chamar a operação GetRange, verifique sempre se a resposta contém next_start_primary_key.

Uso dos SDKs do Tablestore

Você pode utilizar os seguintes SDKs do Tablestore para ler dados cujos valores de chave primária estão dentro do intervalo especificado:

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

Consumo de CUs

O número de CUs de leitura consumidas pela operação GetRange é arredondado para cima a partir do resultado da seguinte fórmula: Número de CUs de leitura consumidas = (Tamanho dos dados em todas as colunas de chave primária das linhas que atendem às condições da consulta + Tamanho dos dados nas colunas de atributo lidas) / 4 KB. Para mais informações sobre como calcular o tamanho dos dados, consulte Data storage.
Se a requisição expirar e os resultados forem indefinidos, as CUs podem ou não ser consumidas.
Se um código de status HTTP 5xx for retornado, indicando um erro interno, a operação não consumirá CUs. Se outros erros forem retornados, uma CU de leitura será consumida.