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

Use o Tablestore SDK for Python para controlar a ordem dos resultados do índice de pesquisa e paginá-los com offset ou next_token.

Pré-requisitos

Instale o Tablestore SDK for Python e inicialize um cliente.

Descrição

Os índices de pesquisa oferecem pré-ordenação de índice e ordenação no momento da consulta. Ao criar um índice de pesquisa, use index_sort para especificar a ordem padrão. Se index_sort não for especificado, as linhas serão ordenadas pela chave primária. A pré-ordenação de índice aceita apenas PrimaryKeySort e FieldSort, e não é compatível com índices que contêm um campo Nested. Após a criação, atualize dinamicamente o esquema para alterar a pré-ordenação do índice. Durante a consulta, utilize SearchQuery.sort para definir ScoreSort, PrimaryKeySort, FieldSort ou GeoDistanceSort. Também é possível combinar vários ordenadores seguindo a ordem da lista. Exceto para chaves primárias, os campos de ordenação devem ter a ordenação e a agregação ativadas durante a criação do índice.

Método de paginação	Descrição
limit e offset	Use quando os resultados não excederem 100.000 linhas e for necessário saltar para uma posição específica. A soma de `limit + offset` não pode ultrapassar `100000`.
next_token	Use para paginação profunda ou leitura sequencial de todos os resultados. A profundidade da paginação não está sujeita ao limite de 100.000 linhas, mas as páginas só podem ser lidas sequencialmente.

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

sort = Sort([
    FieldSort("score", SortOrder.DESC),
    PrimaryKeySort(SortOrder.ASC),
])
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(MatchAllQuery(), sort=sort, limit=10),
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.rows)

Parâmetros

Solicitação de pesquisa

O método search contém os seguintes parâmetros.

Nome	Tipo	Descrição
table_name (obrigatório)	`str`	Nome da tabela de dados.
index_name (obrigatório)	`str`	Nome do índice de pesquisa.
search_query (obrigatório)	`SearchQuery`	Condição de consulta e configurações comuns de consulta.
columns_to_get (opcional)	`ColumnsToGet`	Configuração de colunas de retorno. Se este parâmetro não for especificado, apenas as colunas de chave primária serão retornadas.
routing_keys (opcional)	`list`	Valores de chave primária dos campos de roteamento personalizados. Este parâmetro não é necessário se o roteamento personalizado não estiver configurado.
timeout_s (opcional)	`int`	Tempo limite da solicitação em segundos. Caso não seja especificado, o tempo limite no nível do cliente será utilizado.

Configuração de consulta

search_query é do tipo SearchQuery e contém os seguintes parâmetros de ordenação e paginação.

Nome	Tipo	Descrição
query (obrigatório)	`Query`	Condição de consulta.
sort (opcional)	`Sort`	Configuração de ordenação no momento da consulta. Se omitido, a pré-ordenação do índice será usada. Não especifique este parâmetro ao utilizar `next_token`.
offset (opcional)	`int`	Deslocamento. Valor padrão: `0`. Não especifique este parâmetro ao utilizar `next_token`.
limit (opcional)	`int`	Número máximo de linhas a retornar. Valor padrão: `10`. O máximo é `100` se alguma coluna de retorno precisar ser lida da tabela, e `1000` se todas as colunas de retorno forem lidas do índice de pesquisa.
next_token (opcional)	`bytes`	Token de paginação. Omita-o na primeira solicitação e use o `next_token` da resposta anterior nas solicitações subsequentes.
get_total_count (opcional)	`bool`	Define se o número total de linhas correspondentes deve ser retornado. Valor padrão: `False`.

Configuração de ordenação

search_query.sort é do tipo Sort e contém o seguinte parâmetro.

Nome	Tipo	Descrição
sorters (obrigatório)	`list[Sorter]`	Lista de ordenadores. A ordem da lista determina a prioridade da ordenação multinível. Os tipos de ordenador aceitos são `ScoreSort`, `PrimaryKeySort`, `FieldSort` e `GeoDistanceSort`.

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

Se search_query.sort.sorters[] for do tipo ScoreSort, as linhas serão ordenadas pela pontuação de relevância. ScoreSort contém o seguinte parâmetro.

Nome	Tipo	Descrição
sort_order (opcional)	`SortOrder`	Ordem de ordenação. Valor padrão: `DESC`. Configure explicitamente `ScoreSort` para ordenar por pontuação de relevância.

Ordenação por chave primária

Quando search_query.sort.sorters[] é do tipo PrimaryKeySort, a ordenação das linhas segue a chave primária. PrimaryKeySort contém o seguinte parâmetro.

Nome	Tipo	Descrição
sort_order (opcional)	`SortOrder`	Ordem de ordenação. Valor padrão: `ASC`.

Ordenação por campo

Caso search_query.sort.sorters[] seja do tipo FieldSort, as linhas são classificadas pelo valor do campo. FieldSort contém os seguintes parâmetros.

Nome	Tipo	Descrição
field_name (obrigatório)	`str`	Nome do campo de ordenação. A ordenação e a agregação devem estar habilitadas para o campo.
sort_order (opcional)	`SortOrder`	Ordem de ordenação. Valor padrão: `ASC`.
sort_mode (opcional)	`SortMode`	Modo de seleção de valor para um campo com múltiplos valores: `MIN`, `MAX` ou `AVG`.
nested_filter (opcional)	`NestedFilter`	Configuração de ordenação de subcampos Nested, incluindo o caminho Nested e uma consulta que seleciona as linhas filhas usadas para a ordenação.

Ordenação por distância geográfica

Se search_query.sort.sorters[] for do tipo GeoDistanceSort, as linhas serão ordenadas pela distância entre um ponto geográfico e os pontos de destino. GeoDistanceSort contém os seguintes parâmetros.

Nome	Tipo	Descrição
field_name (obrigatório)	`str`	Nome do campo de ordenação GeoPoint.
points (obrigatório)	`list[str]`	Pontos de destino no formato `latitude,longitude`.
sort_order (opcional)	`SortOrder`	`ASC` ordena do mais próximo para o mais distante, e `DESC` ordena do mais distante para o mais próximo.
sort_mode (opcional)	`SortMode`	Modo de seleção de valor quando existem múltiplas distâncias: `MIN`, `MAX` ou `AVG`.
geo_distance_type (opcional)	`GeoDistanceType`	Método de cálculo de distância. `ARC` (padrão) usa um modelo esférico, e `PLANE` usa um modelo planar.
nested_filter (opcional)	`NestedFilter`	Configuração de ordenação de subcampos Nested.

Colunas de retorno

columns_to_get é do tipo ColumnsToGet e contém os seguintes parâmetros.

Nome	Tipo	Descrição
column_names (opcional)	`list[str]`	Nomes das colunas de atributo a serem retornadas. Especifique este parâmetro apenas quando `return_type` for `SPECIFIED`.
return_type (opcional)	`ColumnReturnType`	Modo de coluna de retorno. `NONE` (padrão) retorna apenas colunas de chave primária; `SPECIFIED` retorna colunas de atributo especificadas; `ALL` retorna todas as colunas de atributo da tabela; e `ALL_FROM_INDEX` retorna todos os campos armazenados no índice.

Resposta

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

Campo	Tipo	Descrição
rows	`list[Row]`	Linhas retornadas pela consulta. A quantidade não excede `limit`.
next_token	`bytes`	Token para a próxima página. Um valor vazio indica que não há mais dados disponíveis.
total_count	`int`	Número de linhas correspondentes. O valor depende de `get_total_count`.
is_all_succeed	`bool`	Indica se todas as partições do índice foram consultadas. Se o valor for `False`, resultados parciais serão retornados.
agg_results	`list[AggResult]`	Resultados da agregação de métricas. Este campo estará vazio se `aggs` não estiver configurado.
group_by_results	`list[GroupByResult]`	Resultados de agrupamento. Este campo estará vazio se `group_bys` não estiver configurado.
search_hits	`list[SearchHit]`	Acertos da pesquisa, incluindo informações estendidas como linhas, pontuações de relevância e destaques.

Um next_token vazio também pode indicar que a consulta não possui uma ordem de ordenação determinística. total_count representa o número total de linhas correspondentes, e não a contagem de linhas da página atual.

Resposta compatível com tupla

A partir do Tablestore SDK for Python 5.2.0, as APIs de pesquisa retornam objetos de resposta em vez de tuplas. A versão 5.1.0 e anteriores retornam tuplas diretamente. Na versão 5.2.1 e posteriores, chame SearchResponse.v1_response() para obter uma tupla compatível com versões anteriores. Para novos códigos, acesse os atributos de SearchResponse diretamente para evitar erros de desempacotamento caso os campos de resposta sejam estendidos.

(
    rows,
    next_token,
    total_count,
    is_all_succeed,
    agg_results,
    group_by_results,
    search_hits,
) = response.v1_response()

Exemplos

Ordenar por distância geográfica

O exemplo abaixo retorna resultados do mais próximo ao mais distante com base na distância esférica entre location e 30.25,120.16.

sort = Sort([
    GeoDistanceSort(
        "location",
        ["30.25,120.16"],
        sort_order=SortOrder.ASC,
        sort_mode=SortMode.MIN,
        geo_distance_type=GeoDistanceType.ARC,
    )
])
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(MatchAllQuery(), sort=sort, limit=10),
)
print(response.rows)

Paginar usando next_token

Especifique a ordem de ordenação na primeira solicitação. Nas solicitações subsequentes, passe apenas o next_token da resposta anterior e a mesma condição de consulta até que o token esteja vazio.

query = MatchAllQuery()
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, sort=Sort([PrimaryKeySort()]), limit=100),
)
all_rows = list(response.rows)

while response.next_token:
    response = client.search(
        "example_table",
        "example_index",
        SearchQuery(query, next_token=response.next_token, limit=100),
    )
    all_rows.extend(response.rows)

print(len(all_rows))

Importante

Ao paginar usando next_token, não especifique offset, pois não é possível pular páginas diretamente. Para retroceder, armazene em cache o token usado para cada página e consulte novamente com o token da página de destino. Um índice de pesquisa que contém um campo Nested não possui pré-ordenação de índice. Especifique explicitamente sort na primeira solicitação, caso contrário, o servidor não retornará next_token.

Tablestore:Sort and paginate results