Todos os produtos
Search

Este produto

    Tablestore:Geo query

    Central de documentação

    Tablestore:Geo query

    Última atualização: Aug 20, 2026

    Com o Tablestore SDK for Java, a consulta geográfica filtra dados por distância de um ponto central, retângulo delimitador ou polígono.

    Pré-requisitos

    Instale o Tablestore SDK for Java e inicialize um cliente.

    Descrição do recurso

    A consulta geográfica filtra dados com base nas localizações geográficas em um campo indexado do tipo GEO_POINT. Há suporte para os seguintes tipos de consulta:

    • Consulta por distância geográfica (GeoDistanceQuery): busca localizações cuja distância de um ponto central especificado seja menor ou igual a um valor definido.

    • Consulta por retângulo delimitador (GeoBoundingBoxQuery): busca localizações dentro de um retângulo delimitador definido pelas coordenadas dos cantos superior esquerdo e inferior direito.

    • Consulta por polígono (GeoPolygonQuery): busca localizações dentro de um polígono definido por vários pontos de coordenadas.

    Ao chamar search, defina o tipo de consulta como GeoDistanceQuery, GeoBoundingBoxQuery ou GeoPolygonQuery conforme a área geográfica a ser consultada.

    SearchResponse search(SearchRequest request)

    O exemplo a seguir consulta linhas em que o campo location está a até 120.000 metros do ponto central 0,0. A consulta retorna no máximo 10 linhas e a contagem total de correspondências.

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

GeoDistanceQuery geoDistanceQuery = new GeoDistanceQuery();
geoDistanceQuery.setFieldName("location");
geoDistanceQuery.setCenterPoint("0,0");
geoDistanceQuery.setDistanceInMeter(120000);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(geoDistanceQuery);
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

    request é um objeto SearchRequest que contém os parâmetros a seguir.

    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 da busca.

    columnsToGet (opcional)

    SearchRequest.ColumnsToGet

    Colunas a retornar. Sem essa configuração, apenas as colunas de chave primária sã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 define um tempo limite específico para a consulta.

    routingValues (opcional)

    List<PrimaryKey>

    Valores de chave primária correspondentes aos campos de roteamento personalizado. Não defina este parâmetro se o roteamento personalizado não estiver configurado.

    Configurações da consulta

    request.searchQuery é um objeto SearchQuery que contém os parâmetros a seguir.

    Nome

    Tipo

    Descrição

    query (obrigatório)

    Query

    Condição da consulta. Defina este parâmetro como um objeto GeoDistanceQuery, GeoBoundingBoxQuery ou GeoPolygonQuery conforme o tipo de consulta.

    offset (opcional)

    Integer

    Posição inicial da consulta.

    limit (opcional)

    Integer

    Número máximo de linhas a retornar. Defina este parâmetro como 0 para não retornar linhas.

    collapse (opcional)

    Collapse

    Configurações de colapso de campo para remover duplicatas dos resultados com base em um campo especificado. Para obter detalhes, consulte Collapse query results.

    sort (opcional)

    Sort

    Ordem de classificação dos resultados. Para obter detalhes, consulte Sort and paginate results.

    trackTotalCount (opcional)

    int

    Contagem máxima esperada de linhas correspondentes. O valor padrão é TRACK_TOTAL_COUNT_DISABLED, que desativa a contagem. Defina este parâmetro 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 obter detalhes, consulte Aggregation.

    groupByList (opcional)

    List<GroupBy>

    Configurações de agrupamento. Para obter detalhes, consulte Aggregation.

    token (opcional)

    byte[]

    Token de paginação. Defina este parâmetro com o valor de 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 ordenação.

    Para todos os três tipos de consulta geográfica, especifique as coordenadas no formato latitude,longitude, com a latitude antes da longitude. A faixa de latitude é [-90,+90] e a de longitude é [-180,+180]. Exemplo: 35.8,-45.91.

    Condição de distância geográfica

    Na consulta por distância geográfica, request.searchQuery.query é um objeto GeoDistanceQuery que contém os parâmetros a seguir.

    Nome

    Tipo

    Descrição

    fieldName (obrigatório)

    String

    Nome do campo indexado do tipo GEO_POINT a consultar.

    centerPoint (obrigatório)

    String

    Coordenadas do ponto central.

    distanceInMeter (obrigatório)

    double

    Distância máxima do ponto central, em metros.

    Condição de retângulo delimitador

    Na consulta por retângulo delimitador, request.searchQuery.query é um objeto GeoBoundingBoxQuery que contém os parâmetros a seguir.

    Nome

    Tipo

    Descrição

    fieldName (obrigatório)

    String

    Nome do campo indexado do tipo GEO_POINT a consultar.

    topLeft (obrigatório)

    String

    Coordenadas do canto superior esquerdo do retângulo delimitador.

    bottomRight (obrigatório)

    String

    Coordenadas do canto inferior direito do retângulo delimitador.

    Condição de polígono

    Na consulta por polígono, request.searchQuery.query é um objeto GeoPolygonQuery que contém os parâmetros a seguir.

    Nome

    Tipo

    Descrição

    fieldName (obrigatório)

    String

    Nome do campo indexado do tipo GEO_POINT a consultar.

    points (obrigatório)

    List<String>

    Pontos de coordenadas que definem o polígono.

    Colunas retornadas

    request.columnsToGet é um objeto SearchRequest.ColumnsToGet que contém os parâmetros a seguir.

    Nome

    Tipo

    Descrição

    columns (opcional)

    List<String>

    Colunas de atributo a retornar. Defina este parâmetro somente se returnAll e returnAllFromIndex forem ambos 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

    search retorna um objeto SearchResponse. A tabela a seguir descreve os campos principais.

    Nome

    Tipo

    Descrição

    totalCount

    long

    Quantidade de linhas correspondentes. Chame getTotalCount() para obter o valor. O resultado depende da configuração de trackTotalCount.

    rows

    List<Row>

    Linhas retornadas pela consulta. Chame getRows() para obter o valor. A quantidade de linhas não excede limit.

    searchHits

    List<SearchHit>

    Resultados da consulta. Chame getSearchHits() para obter o valor.

    nextToken

    byte[]

    Token da próxima página. Chame getNextToken() para obter o 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 sucesso. Chame isAllSuccess() para obter o valor. Se o valor for false, a resposta conterá resultados parciais e totalCount poderá ser menor que o número real de linhas correspondentes.

    Exemplos de cenários

    Consultar dados dentro de um retângulo delimitador

    O exemplo a seguir consulta linhas em que o campo location está dentro do retângulo delimitador cujas coordenadas do canto superior esquerdo são 2,-1 e do canto inferior direito são -1,2.

    GeoBoundingBoxQuery geoBoundingBoxQuery = new GeoBoundingBoxQuery();
geoBoundingBoxQuery.setFieldName("location");
geoBoundingBoxQuery.setTopLeft("2,-1");
geoBoundingBoxQuery.setBottomRight("-1,2");

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(geoBoundingBoxQuery);

    Consultar dados dentro de um polígono

    O exemplo a seguir consulta linhas em que o campo location está dentro do polígono definido pelos pontos de coordenadas -1,-1, -1,2, 2,2 e 2,-1.

    GeoPolygonQuery geoPolygonQuery = new GeoPolygonQuery();
geoPolygonQuery.setFieldName("location");
geoPolygonQuery.setPoints(
        Arrays.asList("-1,-1", "-1,2", "2,2", "2,-1"));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(geoPolygonQuery);