Range query - Tablestore SDK for Java - Tablestore: Central de Documentação do Alibaba Cloud

Pré-requisitos

Instale o Tablestore SDK for Java e inicialize um cliente.

Descrição do recurso

A consulta de intervalo corresponde às linhas cujos valores de campo indexado estão dentro de um intervalo especificado. Você pode definir apenas o limite inferior, apenas o limite superior ou ambos. Pelo menos um limite é obrigatório. Em campos Text, a linha corresponde se qualquer token gerado a partir do valor do campo estiver dentro do intervalo.

Use greaterThan, greaterThanOrEqual, lessThan e lessThanOrEqual para especificar as condições maior que, maior ou igual a, menor que e menor ou igual a. Defina o tipo de consulta como RangeQuery ao chamar search.

SearchResponse search(SearchRequest request)

O exemplo a seguir consulta valores Long no campo price dentro do intervalo semiaberto [100, 500). A consulta retorna até 10 linhas e o número total de correspondências.

String tableName = "example_table";
String indexName = "example_index";

RangeQuery rangeQuery = new RangeQuery();
rangeQuery.setFieldName("price");
rangeQuery.greaterThanOrEqual(ColumnValue.fromLong(100L));
rangeQuery.lessThan(ColumnValue.fromLong(500L));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(rangeQuery);
searchQuery.setLimit(10);
searchQuery.setTrackTotalCount(SearchQuery.TRACK_TOTAL_COUNT);

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchRequest.ColumnsToGet columnsToGet = new SearchRequest.ColumnsToGet();
columnsToGet.setReturnAll(true);
request.setColumnsToGet(columnsToGet);

SearchResponse response = client.search(request);
System.out.println(response.getTotalCount());
System.out.println(response.getRows());

Parâmetros

Solicitação de busca

O objeto request é do tipo SearchRequest e contém os seguintes parâmetros:

Nome	Tipo	Descrição
tableName (obrigatório)	String	Nome da tabela de dados.
indexName (obrigatório)	String	Nome do índice de busca.
searchQuery (obrigatório)	SearchQuery	Condição de consulta e configurações gerais.
columnsToGet (opcional)	SearchRequest.ColumnsToGet	Colunas a retornar. Se este parâmetro não for configurado, apenas as colunas de chave primária serão retornadas.
timeoutInMillisecond (opcional)	int	Tempo limite da consulta no nível da solicitação, em milissegundos. O valor padrão é `-1`, que não configura um tempo limite específico para a consulta.
routingValues (opcional)	`List<PrimaryKey>`	Valores de chave primária correspondentes aos campos de roteamento personalizado. Deixe este parâmetro indefinido se o roteamento personalizado não estiver configurado.

Configurações de consulta

O objeto request.searchQuery é do tipo SearchQuery e contém os seguintes parâmetros:

Nome	Tipo	Descrição
query (obrigatório)	Query	Condição de consulta. Para consultas de intervalo, defina este parâmetro como um objeto `RangeQuery`.
offset (opcional)	Integer	Posição inicial da consulta.
limit (opcional)	Integer	Número máximo de linhas a retornar. Defina como `0` para não retornar nenhuma linha.
highlight (opcional)	Highlight	Configurações de resumo e destaque para campos `Text`. Para mais detalhes, consulte Summary and highlighting.
collapse (opcional)	Collapse	Configurações de colapso de campo para remover duplicatas dos resultados com base em um campo específico. Para mais detalhes, consulte Collapse query results.
sort (opcional)	Sort	Ordem de classificação dos resultados. Para mais detalhes, consulte Sort and paginate results.
trackTotalCount (opcional)	int	Número máximo esperado de linhas correspondentes a contar. O valor padrão é `TRACK_TOTAL_COUNT_DISABLED`, que desativa a contagem. Defina como `TRACK_TOTAL_COUNT` para contar todas as linhas correspondentes. Um valor menor melhora o desempenho da consulta.
filter (opcional)	SearchFilter	Filtro aplicado aos resultados de `query`.
aggregationList (opcional)	`List<Aggregation>`	Configurações de agregação. Para mais detalhes, consulte Aggregation.
groupByList (opcional)	`List<GroupBy>`	Configurações de agrupamento. Para mais detalhes, consulte Aggregation.
token (opcional)	byte[]	Token de paginação. Defina este parâmetro com o valor `nextToken` da resposta anterior para continuar a leitura das linhas. Ao definir `token`, o SDK limpa `sort`, pois o token já contém as condições de classificação.

Condição de consulta

O objeto request.searchQuery.query é do tipo RangeQuery e contém os seguintes parâmetros:

Nome	Tipo	Descrição
fieldName (obrigatório)	String	Nome do campo indexado a consultar. Consultas de intervalo aceitam campos `Long`, `Double`, `Boolean`, `Keyword`, `Text`, `Date` e `IP`, além de subcampos de `JSON Object`. Em campos `Text`, a linha corresponde se qualquer token estiver dentro do intervalo.
from (opcional)	ColumnValue	Limite inferior. É obrigatório definir pelo menos um entre `from` e `to`. Chame `greaterThan` ou `greaterThanOrEqual` para definir o limite inferior e indicar sua inclusão.
to (opcional)	ColumnValue	Limite superior. É obrigatório definir pelo menos um entre `from` e `to`. Chame `lessThan` ou `lessThanOrEqual` para definir o limite superior e indicar sua inclusão.
includeLower (opcional)	boolean	Indica se `from` deve ser incluído. O valor padrão é `false`. O método `greaterThan` define este parâmetro como `false`, enquanto `greaterThanOrEqual` o define como `true`.
includeUpper (opcional)	boolean	Indica se `to` deve ser incluído. O valor padrão é `false`. O método `lessThan` define este parâmetro como `false`, enquanto `lessThanOrEqual` o define como `true`.

Colunas retornadas

O objeto request.columnsToGet é do tipo SearchRequest.ColumnsToGet e contém os seguintes parâmetros:

Nome	Tipo	Descrição
columns (opcional)	`List<String>`	Colunas de atributo a retornar. Configure este parâmetro apenas se `returnAll` e `returnAllFromIndex` forem `false`. Se omitido, apenas as colunas de chave primária serão retornadas.
returnAll (opcional)	boolean	Indica se todas as colunas de atributo da tabela de dados devem ser retornadas. O valor padrão é `false`.
returnAllFromIndex (opcional)	boolean	Indica se todas as colunas de atributo indexadas devem ser retornadas. O valor padrão é `false`. Não defina `returnAll` e `returnAllFromIndex` como `true` simultaneamente.

Valores de retorno

O método search retorna um objeto SearchResponse. A tabela a seguir descreve os campos principais:

Nome	Tipo	Descrição
totalCount	long	Número de linhas correspondentes. Chame `getTotalCount()` para obter esse valor. O resultado depende da configuração `trackTotalCount`.
rows	`List<Row>`	Linhas retornadas pela consulta. Chame `getRows()` para obter esse valor. O número de linhas não excede `limit`.
searchHits	`List<SearchHit>`	Acertos da consulta. Chame `getSearchHits()` para obter esse valor. Se `highlight` estiver configurado, este campo conterá os dados da linha, além dos resultados de resumo e destaque.
nextToken	byte[]	Token da próxima página. Chame `getNextToken()` para obter esse valor. Se o valor não for `null`, defina-o como `token` na próxima solicitação para continuar a leitura das linhas.
isAllSuccess	boolean	Indica se todas as partições do índice foram consultadas com êxito. Chame `isAllSuccess()` para obter esse valor. Se for `false`, a resposta contém resultados parciais e `totalCount` pode ser menor que o número real de linhas correspondentes.

Exemplos de cenários

Consultar datas em formato personalizado

Se date_string for um campo String na tabela de dados mapeado para um campo Date no índice de busca com o formato yyyy-MM-dd HH:mm:ss, use strings no mesmo formato como limites da consulta. O exemplo a seguir consulta o intervalo [2021-01-01 00:00:00, 2023-01-01 00:00:00):

RangeQuery rangeQuery = new RangeQuery();
rangeQuery.setFieldName("date_string");
rangeQuery.greaterThanOrEqual(ColumnValue.fromString("2021-01-01 00:00:00"));
rangeQuery.lessThan(ColumnValue.fromString("2023-01-01 00:00:00"));

Consultar timestamps epoch-second

Se date_epoch for um campo Integer na tabela de dados mapeado para um campo Date no índice de busca com o formato epoch_second, use timestamps epoch-second como limites da consulta. O exemplo a seguir consulta valores maiores que 1609459200:

RangeQuery rangeQuery = new RangeQuery();
rangeQuery.setFieldName("date_epoch");
rangeQuery.greaterThan(ColumnValue.fromLong(1609459200L));