Sort and paginate results - Tablestore SDK for Java - Tablestore: Central de Documentação do Alibaba Cloud

Ao consultar um índice de pesquisa com o Tablestore SDK for Java, use a ordenação de índice ou a ordenação no momento da consulta para controlar a ordem dos resultados. Para paginar os resultados, utilize offset ou token.

Pré-requisitos

Instale o Tablestore SDK for Java e inicialize um cliente.

Como funciona

Os índices de pesquisa oferecem suporte aos seguintes mecanismos de ordenação:

Ordenação de índice: ao criar um índice de pesquisa, configure IndexSchema.indexSort para definir a ordem padrão dos resultados. Se nenhuma ordenação de índice for configurada, os resultados serão ordenados pela chave primária. Esse mecanismo oferece suporte apenas a PrimaryKeySort e FieldSort. Índices de pesquisa que contêm um campo Nested não oferecem suporte à ordenação de índice.
Ordenação no momento da consulta: configure SearchQuery.sort para uma consulta específica. Os resultados podem ser ordenados por pontuação de relevância, chave primária, valor de campo ou distância geográfica. É possível combinar vários ordenadores para realizar uma ordenação multinível. Exceto pelos campos de chave primária, qualquer campo de ordenação deve ter enableSortAndAgg definido como true no esquema do índice de pesquisa.

Quando você especifica um ordenador no momento da consulta diferente do ordenador de chave primária, o servidor anexa automaticamente um ordenador de chave primária para garantir que as linhas com o mesmo valor de ordenação tenham uma ordem determinística. Para desativar esse comportamento, defina Sort.disableDefaultPkSorter como true.

Utilize um dos métodos de paginação a seguir para grandes conjuntos de resultados:

Método	Caso de uso	Características
limit e offset	O conjunto de resultados contém no máximo 100.000 linhas e é necessário acessar uma posição específica.	Oferece suporte a saltos de página. A soma de `limit` e `offset` não pode exceder 100.000.
token	Paginação profunda ou leitura sequencial de todos os resultados.	Não possui o limite de profundidade de 100.000 linhas, mas os resultados só podem ser lidos em sequência.

Chame o método search para consultar dados.

SearchResponse search(SearchRequest request)

O exemplo a seguir retorna as primeiras 10 linhas ordenadas pelo campo score em ordem decrescente e, em seguida, pela chave primária em ordem crescente.

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(new MatchAllQuery());
searchQuery.setLimit(10);
searchQuery.setSort(new Sort(Arrays.<Sort.Sorter>asList(
        new FieldSort("score", SortOrder.DESC),
        new PrimaryKeySort(SortOrder.ASC))));

SearchRequest request =
        new SearchRequest("example_table", "example_index", searchQuery);
SearchResponse response = client.search(request);

Parâmetros

Solicitação de consulta

O tipo de request é SearchRequest. A tabela a seguir descreve seus parâmetros.

Nome	Tipo	Descrição
tableName (obrigatório)	String	O nome da tabela de dados.
indexName (obrigatório)	String	O nome do índice de pesquisa.
searchQuery (obrigatório)	SearchQuery	A condição de consulta e as configurações de ordenação e paginação.
columnsToGet (opcional)	SearchRequest.ColumnsToGet	As colunas a serem retornadas. Se este parâmetro não for configurado, apenas as colunas de chave primária serão retornadas.

Configuração da consulta

O tipo de request.searchQuery é SearchQuery. A tabela a seguir descreve apenas os parâmetros relacionados à ordenação e paginação.

Nome	Tipo	Descrição
query (obrigatório)	Query	A condição de consulta.
sort (opcional)	Sort	A configuração de ordenação no momento da consulta. Se este parâmetro não for configurado, a ordenação de índice será usada. Não configure este parâmetro para paginação baseada em token. Após a chamada de `setToken`, o SDK limpa a configuração de ordenação existente.
offset (opcional)	Integer	A posição a partir da qual a consulta atual começa. Valor padrão: `0`. Este parâmetro não pode ser configurado para paginação baseada em token.
limit (opcional)	Integer	O número máximo de linhas a retornar. Valor padrão: `10`. O valor máximo é `1000` se todas as colunas retornadas forem lidas do índice de pesquisa, ou `100` se alguma coluna retornada precisar ser lida da tabela de dados.
token (opcional)	byte[]	O token de paginação. Defina este parâmetro com o valor `nextToken` da resposta anterior para ler a próxima página.
trackTotalCount (opcional)	int	O número máximo esperado de linhas correspondentes a contar. Valor padrão: `TRACK_TOTAL_COUNT_DISABLED`, que desativa a contagem. Defina o valor como `TRACK_TOTAL_COUNT` para contar todas as linhas correspondentes. Um valor menor proporciona melhor desempenho de consulta.

Configuração de ordenação

O tipo de request.searchQuery.sort é Sort. A tabela a seguir descreve seus parâmetros.

Nome	Tipo	Descrição
sorters (obrigatório)	`List<Sort.Sorter>`	A lista de ordenadores. A ordem da lista determina a prioridade da ordenação multinível. Os ordenadores compatíveis são `ScoreSort`, `PrimaryKeySort`, `FieldSort` e `GeoDistanceSort`.
disableDefaultPkSorter (opcional)	Boolean	Especifica se o servidor deve ser impedido de anexar automaticamente um ordenador de chave primária. Valor padrão: `false`.

Ordenação por pontuação de relevância

ScoreSort ordena as linhas pela pontuação de relevância calculada com o algoritmo BM25. A tabela a seguir descreve seu parâmetro.

Nome	Tipo	Descrição
order (opcional)	SortOrder	A ordem de classificação. `ASC` especifica ordem crescente e `DESC` especifica ordem decrescente. Valor padrão: `DESC`.

Para ordenar por pontuação de relevância, configure explicitamente ScoreSort. Caso contrário, a ordenação de índice será utilizada.

Ordenação por chave primária

PrimaryKeySort ordena as linhas pela chave primária. A tabela a seguir descreve seu parâmetro.

Nome	Tipo	Descrição
order (opcional)	SortOrder	A ordem de classificação. Valor padrão: `ASC`.

Ordenação por campo

FieldSort ordena as linhas pelo valor do campo. A tabela a seguir descreve seus parâmetros.

Nome	Tipo	Descrição
fieldName (obrigatório)	String	O nome do campo de ordenação. A ordenação e a agregação devem estar habilitadas para o campo.
order (opcional)	SortOrder	A ordem de classificação. Valor padrão: `ASC`.
mode (opcional)	SortMode	O valor a ser usado ao ordenar um campo com múltiplos valores. `MIN`, `MAX` e `AVG` utilizam, respectivamente, os valores mínimo, máximo e médio.
missingFields (opcional)	`List<String>`	A lista de campos de fallback para ordenação. Se o campo de ordenação atual estiver ausente, o primeiro campo da lista que possuir um valor será utilizado. Um campo de fallback deve ter o mesmo tipo do campo de ordenação.
missingValue (opcional)	ColumnValue	O valor de ordenação a ser usado caso o campo de ordenação e todos os campos de fallback estejam ausentes. Defina este parâmetro como `FIRST_WHEN_MISSING` ou `LAST_WHEN_MISSING` para sempre posicionar as linhas ausentes no início ou no final. Também é possível usar um valor personalizado do mesmo tipo do campo. Se este parâmetro não for configurado, as linhas ausentes serão posicionadas por último.
nestedFilter (opcional)	NestedFilter	A configuração de ordenação Nested que especifica o caminho Nested e as linhas filhas que participam da ordenação. Configure este parâmetro apenas ao ordenar um subcampo Nested.

Filtro Nested

O tipo de FieldSort.nestedFilter é NestedFilter. A tabela a seguir descreve seus parâmetros.

Nome	Tipo	Descrição
path (obrigatório)	String	O caminho do campo Nested.
query (obrigatório)	Query	A condição de consulta que seleciona as linhas filhas Nested que participam da ordenação. Defina o parâmetro como `MatchAllQuery` para usar todas as linhas filhas.

Ordenação por distância geográfica

GeoDistanceSort ordena as linhas pela distância entre um campo de ponto geográfico e pontos alvo. A tabela a seguir descreve seus parâmetros.

Nome	Tipo	Descrição
fieldName (obrigatório)	String	O nome do campo Geopoint.
points (obrigatório)	`List<String>`	Os pontos geográficos alvo. Cada ponto usa o formato `latitude,longitude`.
order (opcional)	SortOrder	A ordem de classificação. `ASC` ordena do mais próximo ao mais distante, e `DESC` ordena do mais distante ao mais próximo.
mode (opcional)	SortMode	O valor a ser usado quando existirem múltiplas distâncias. Os valores compatíveis são `MIN`, `MAX` e `AVG`.
distanceType (opcional)	GeoDistanceType	O método de cálculo de distância. `ARC` realiza um cálculo esférico para maior precisão. `PLANE` realiza um cálculo planar com menos computação. Valor padrão: `ARC`.
nestedFilter (opcional)	NestedFilter	A configuração de ordenação Nested. Configure este parâmetro apenas ao ordenar um subcampo Nested.

Colunas a retornar

O tipo de request.columnsToGet é SearchRequest.ColumnsToGet. A necessidade de ler as colunas retornadas da tabela de dados afeta o valor máximo de limit.

Nome	Tipo	Descrição
columns (opcional)	`List<String>`	Os nomes das colunas de atributo a retornar. Os dados podem ser lidos diretamente do índice de pesquisa somente se todas as colunas de atributo especificadas estiverem indexadas e com o armazenamento habilitado.
returnAll (opcional)	boolean	Especifica se todas as colunas de atributo da tabela de dados devem ser retornadas. Valor padrão: `false`. Se este parâmetro for `true`, as colunas de atributo deverão ser lidas da tabela de dados e o valor máximo de limit será 100.
returnAllFromIndex (opcional)	boolean	Especifica se todas as colunas de atributo armazenadas no índice de pesquisa devem ser retornadas. Valor padrão: `false`. Se este parâmetro for `true`, o valor máximo de limit será 1000. Não defina este parâmetro e `returnAll` como `true` simultaneamente.

Resposta

O método search retorna SearchResponse. A tabela a seguir descreve os campos relacionados à ordenação e paginação.

Nome	Tipo	Descrição
rows	`List<Row>`	As linhas retornadas pela consulta atual. Chame `getRows()` para obter o valor. O número de linhas não excede o limit.
searchHits	`List<SearchHit>`	Os acertos da pesquisa. Chame `getSearchHits()` para obter o valor.
totalCount	long	O número de linhas correspondentes. Chame `getTotalCount()` para obter o valor. O valor depende de trackTotalCount e não representa o número de linhas na página atual.
nextToken	byte[]	O token para a próxima página. Chame `getNextToken()` para obter o valor. Um valor `null` indica que não há mais dados ou que a consulta atual não possui uma ordem de classificação determinística.
isAllSuccess	boolean	Indica se todas as partições do índice foram consultadas. Chame `isAllSuccess()` para obter o valor. Se este campo for `false`, a resposta conterá resultados parciais.

Exemplos

Configurar ordenação de índice

O exemplo a seguir configura o campo score como campo de ordenação de índice durante a criação de um índice de pesquisa. Se nenhuma ordenação for configurada para uma consulta, os resultados serão retornados em ordem crescente de score.

FieldSchema score = new FieldSchema("score", FieldType.LONG)
        .setEnableSortAndAgg(true);

IndexSchema indexSchema = new IndexSchema();
indexSchema.setFieldSchemas(Collections.singletonList(score));
indexSchema.setIndexSort(new Sort(
        Collections.<Sort.Sorter>singletonList(
                new FieldSort("score", SortOrder.ASC))));

Ordenar por pontuação de relevância

O exemplo a seguir retorna resultados em ordem decrescente de pontuação de relevância BM25.

TermQuery termQuery = new TermQuery();
termQuery.setFieldName("category");
termQuery.setTerm(ColumnValue.fromString("book"));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(termQuery);
searchQuery.setSort(new Sort(
        Collections.<Sort.Sorter>singletonList(new ScoreSort())));

Lidar com valores de campo ausentes

O exemplo a seguir ordena as linhas pelo campo score em ordem decrescente. Se uma linha não contiver o campo, o valor de score_backup será utilizado. Se ambos os campos estiverem ausentes, a linha será posicionada por último.

FieldSort fieldSort = new FieldSort("score", SortOrder.DESC);
fieldSort.setMissingFields(Collections.singletonList("score_backup"));
fieldSort.setMissingValue(FieldSort.LAST_WHEN_MISSING);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(new MatchAllQuery());
searchQuery.setSort(new Sort(
        Collections.<Sort.Sorter>singletonList(fieldSort)));

Ordenar campos com múltiplos valores e Nested

Ao ordenar um array ou outro campo com múltiplos valores, use mode para especificar o valor que participa da ordenação. O exemplo a seguir ordena as linhas em ordem decrescente pelo valor máximo no array scores.

FieldSort fieldSort = new FieldSort("scores", SortOrder.DESC);
fieldSort.setMode(SortMode.MAX);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(new MatchAllQuery());
searchQuery.setSort(new Sort(
        Collections.<Sort.Sorter>singletonList(fieldSort)));

Ao ordenar um subcampo Nested, configure também o caminho Nested e selecione as linhas filhas que participarão da ordenação. O exemplo a seguir utiliza apenas as linhas filhas onde items.age é 1 e ordena as linhas em ordem crescente pelo valor mínimo de items.name.

TermQuery ageQuery = new TermQuery();
ageQuery.setFieldName("items.age");
ageQuery.setTerm(ColumnValue.fromLong(1));

FieldSort fieldSort = new FieldSort("items.name", SortOrder.ASC);
fieldSort.setMode(SortMode.MIN);
fieldSort.setNestedFilter(new NestedFilter("items", ageQuery));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(new MatchAllQuery());
searchQuery.setSort(new Sort(
        Collections.<Sort.Sorter>singletonList(fieldSort)));

Ordenar por distância geográfica

O exemplo a seguir retorna as linhas do ponto mais próximo ao mais distante com base na distância esférica entre o campo location e 30.23,120.19.

GeoDistanceSort geoSort = new GeoDistanceSort(
        "location", Collections.singletonList("30.23,120.19"));
geoSort.setOrder(SortOrder.ASC);
geoSort.setDistanceType(GeoDistanceType.ARC);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(new MatchAllQuery());
searchQuery.setSort(new Sort(
        Collections.<Sort.Sorter>singletonList(geoSort)));

Paginar usando limit e offset

O exemplo a seguir ignora as primeiras 100 linhas e retorna as próximas 100 linhas. Ao usar este método, a soma de limit e offset não pode exceder 100.000.

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(new MatchAllQuery());
searchQuery.setLimit(100);
searchQuery.setOffset(100);

Paginar usando token

O exemplo a seguir lê todos os resultados em um loop. O token é null na primeira consulta. Cada consulta subsequente usa diretamente o nextToken da resposta anterior. Após a chamada de setToken, o SDK limpa a ordenação porque o token contém as condições de ordenação da página anterior.

List<Row> rows = new ArrayList<Row>();
byte[] nextToken = null;
do {
    SearchQuery searchQuery = new SearchQuery();
    searchQuery.setQuery(new MatchAllQuery());
    searchQuery.setLimit(100);
    searchQuery.setToken(nextToken);

    SearchRequest request =
            new SearchRequest("example_table", "example_index", searchQuery);
    SearchResponse response = client.search(request);
    rows.addAll(response.getRows());
    nextToken = response.getNextToken();
} while (nextToken != null);

Importante

Não é possível configurar offset nem pular páginas durante a paginação baseada em token. Para retornar a uma página anterior, armazene em cache o token usado para solicitar cada página e emita outra consulta utilizando o token da página desejada.
Um índice de pesquisa que contém um campo Nested não possui ordenação de índice. Para usar paginação baseada em token com esse tipo de índice, configure explicitamente a ordenação na primeira consulta. Caso contrário, o servidor não retornará nextToken.

Para consultas sequenciais no mesmo processo, passe nextToken diretamente como um array de bytes. Use codificação Base64 apenas quando o token precisar ser persistido ou transferido entre processos ou entre frontend e backend. Não converta o token usando new String(nextToken), pois isso corrompe o token.

String encodedToken = Base64.getEncoder().encodeToString(nextToken);
byte[] decodedToken = Base64.getDecoder().decode(encodedToken);