Geo queries - Tablestore SDK for Python - Tablestore: Central de Documentação do Alibaba Cloud

Use o Tablestore SDK for Python para filtrar dados por distância de um ponto central, caixa delimitadora ou polígono.

Pré-requisitos

Instale o Tablestore SDK for Python e inicialize um cliente.

Descrição

Consultas geográficas filtram dados com base na localização geográfica em um campo GeoPoint. Você pode consultar por distância, caixa delimitadora ou polígono. Ao chamar o método search, defina o tipo de consulta como GeoDistanceQuery, GeoBoundingBoxQuery ou GeoPolygonQuery, conforme o intervalo geográfico necessário.

GeoDistanceQuery(field_name, center_point, distance)
GeoBoundingBoxQuery(field_name, top_left, bottom_right)
GeoPolygonQuery(field_name, points)

O exemplo a seguir consulta linhas em que o campo location está a no máximo 200.000 metros de 30.25,120.16. A consulta retorna até 10 linhas e o total de linhas correspondentes.

query = GeoDistanceQuery("location", "30.25,120.16", 200000)
search_query = SearchQuery(
    query,
    limit=10,
    get_total_count=True,
)
response = client.search(
    "example_table",
    "example_index",
    search_query,
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.total_count)
for row in response.rows:
    print(row)

Parâmetros

Solicitação de busca

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 busca.
search_query (obrigatório)	`SearchQuery`	Condição de consulta e configurações comuns de pesquisa.
columns_to_get (opcional)	`ColumnsToGet`	Configuração das colunas de retorno. Se você não especificar este parâmetro, o sistema retornará apenas as colunas de chave primária.
routing_keys (opcional)	`list`	Lista de valores de chave primária para campos de roteamento personalizado. Não é necessário especificar este parâmetro se o roteamento personalizado não estiver configurado.
timeout_s (opcional)	`int`	Tempo limite da solicitação em segundos. Caso você não especifique este parâmetro, o sistema usará o tempo limite no nível do cliente.

Configuração de consulta

O parâmetro search_query é do tipo SearchQuery e contém os seguintes parâmetros.

Nome	Tipo	Descrição
query (obrigatório)	`Query`	Condição da consulta. Defina este parâmetro como `GeoDistanceQuery`.
sort (opcional)	`Sort`	Ordem de classificação dos resultados da consulta. Para mais informações, consulte Sort and paginate results.
get_total_count (opcional)	`bool`	Indica se deve retornar o número total de linhas correspondentes. Valor padrão: `False`. Definir este parâmetro como `True` aumenta a sobrecarga da consulta.
next_token (opcional)	`bytes`	Token de paginação. Defina este parâmetro com o valor `next_token` da resposta anterior para recuperar a próxima página. Para mais informações, consulte Sort and paginate results.
offset (opcional)	`int`	Deslocamento inicial da consulta atual. Use este parâmetro para paginação superficial.
limit (opcional)	`int`	Número máximo de linhas a retornar. Se definido como `0`, nenhum dado de linha será retornado.
aggs (opcional)	`list[Agg]`	Configurações de agregação. Para mais informações, consulte Aggregation.
group_bys (opcional)	`list[BaseGroupBy]`	Configurações de agrupamento. Para mais informações, consulte Aggregation.
collapse_field (opcional)	`Collapse`	Configuração de colapso de resultados. Este recurso remove duplicatas com base em um campo especificado. Para mais informações, consulte Collapse query results.

As coordenadas nos três tipos de consulta usam o formato latitude,longitude. A latitude precede a longitude. O intervalo de latitude é [-90,+90] e o de longitude é [-180,+180]. Exemplo: 35.8,-45.91.

Condição de distância geográfica

O parâmetro search_query.query é do tipo GeoDistanceQuery e contém os seguintes parâmetros.

Nome	Tipo	Descrição
field_name (obrigatório)	`str`	Nome do campo `GeoPoint` a consultar.
center_point (obrigatório)	`str`	Coordenadas do ponto central.
distance (obrigatório)	`float`	Distância máxima do ponto central. Unidade: metros.

Condição de caixa delimitadora geográfica

O parâmetro search_query.query é do tipo GeoBoundingBoxQuery e contém os seguintes parâmetros.

Nome	Tipo	Descrição
field_name (obrigatório)	`str`	Nome do campo `GeoPoint` a consultar.
top_left (obrigatório)	`str`	Coordenadas do canto superior esquerdo.
bottom_right (obrigatório)	`str`	Coordenadas do canto inferior direito.

Condição de polígono geográfico

O parâmetro search_query.query é do tipo GeoPolygonQuery e contém os seguintes parâmetros.

Nome	Tipo	Descrição
field_name (obrigatório)	`str`	Nome do campo `GeoPoint` a consultar.
points (obrigatório)	`list[str]`	Lista de coordenadas que formam o polígono. Especifique as coordenadas na ordem do perímetro.

Colunas de retorno

O parâmetro 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 retornar. Especifique este parâmetro apenas quando `return_type` for `SPECIFIED`.
return_type (opcional)	`ColumnReturnType`	Modo de retorno das colunas. `NONE` (padrão) retorna apenas colunas de chave primária; `SPECIFIED` retorna as colunas de atributo listadas em `column_names`; `ALL` retorna todas as colunas de atributo da tabela; e `ALL_FROM_INDEX` retorna todas as colunas de atributo indexadas.

Resposta

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

Campo	Tipo	Descrição
rows	`list[Row]`	Linhas retornadas pela consulta atual. A quantidade não excede o valor de `limit`.
next_token	`bytes`	Token para a próxima página. Se este campo não estiver vazio, passe-o para a próxima solicitação e continue a leitura.
total_count	`int`	Número de linhas correspondentes. O valor depende da configuração `get_total_count`.
is_all_succeed	`bool`	Indica se todas as partições do índice foram consultadas. Se o valor for `False`, o sistema retornará resultados parciais e `total_count` poderá ser menor que o número real de linhas correspondentes.
agg_results	`list[AggResult]`	Resultados da agregação. Este campo fica vazio se `aggs` não estiver configurado.
group_by_results	`list[GroupByResult]`	Resultados do agrupamento. Este campo fica vazio se `group_bys` não estiver configurado.
search_hits	`list[SearchHit]`	Resultados da busca, incluindo informações estendidas como pontuações de relevância, destaques e linhas filhas correspondentes.

Resposta compatível com tupla

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

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

Exemplos

Consultar dados em uma caixa delimitadora

O exemplo abaixo consulta dados dentro da caixa delimitadora definida pelo canto superior esquerdo 32.0,119.0 e canto inferior direito 29.0,122.0.

query = GeoBoundingBoxQuery(
    "location",
    "32.0,119.0",
    "29.0,122.0",
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10),
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.rows)

Consultar dados em um polígono

Este exemplo consulta dados dentro do polígono formado por quatro coordenadas.

query = GeoPolygonQuery(
    "location",
    [
        "29.0,119.0",
        "32.0,119.0",
        "32.0,122.0",
        "29.0,122.0",
    ],
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10),
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.rows)