Todos os produtos
Search
Central de documentação

Tablestore:Geo-bounding box query

Última atualização: Sep 20, 2026

Uma geo-bounding box query permite especificar uma área geográfica retangular como condição de consulta. O Tablestore retorna as linhas em que o valor do campo especificado está dentro dessa área geográfica retangular.

Operações de API

Defina o tipo de consulta como GeoBoundingBoxQuery na operação Search ou ParallelScan para executar geo-bounding box queries.

Parâmetros

Parâmetro

Descrição

fieldName

Nome da coluna a ser consultada. O valor deste parâmetro é do tipo de dados GEOPOINT.

topLeft

Par de coordenadas do canto superior esquerdo da área geográfica retangular.

bottomRight

Par de coordenadas do canto inferior direito da área geográfica retangular. Uma área geográfica retangular pode ser definida por meio de um canto superior esquerdo e um canto inferior direito.

O formato é latitude,longitude. Valores válidos de latitude: [-90,+90]. Valores válidos de longitude: [-180,+180]. Exemplo: 35,8,-45,91.

query

Instrução de consulta para o search index. Defina este parâmetro como GeoBoundingBoxQuery.

getTotalCount

Especifica se o número total de linhas que atendem às condições de consulta deve ser retornado. O valor padrão é false, indicando que o total não é retornado.

Definir este parâmetro como true reduz o desempenho da consulta.

tableName

Nome da tabela de dados.

indexName

Nome do search index.

columnsToGet

Especifica se todas as colunas de cada linha que atende às condições de consulta devem ser retornadas. Configure os campos returnAll e columns para este parâmetro.

O valor padrão do campo returnAll é false, indicando que nem todas as colunas são retornadas. Nesse caso, utilize o campo columns para especificar as colunas desejadas. Se nenhuma coluna for especificada, apenas as colunas de chave primária serão retornadas.

Definir o campo returnAll como true retorna todas as colunas.

Métodos

Execute geo-bounding box queries por meio do console do Tablestore, do Tablestore CLI ou dos SDKs do Tablestore. Antes de executar as consultas, verifique se os seguintes pré-requisitos foram atendidos:

Use the Tablestore console

  1. Acesse a aba Index Management.

    1. Faça login no Table Store console.

    2. Na barra de navegação superior, selecione um grupo de recursos e uma região.

    3. Na página Overview, clique no nome da instância ou clique em Instance Management na coluna Actions.

    4. Na aba Instance Details, na aba Data Table List, clique no nome da tabela de dados ou clique em Index Management na coluna Actions.

  2. Na aba Index Management, localize o Search Index de destino e clique em Search na coluna Actions.

  3. Na caixa de diálogo Search, configure a consulta.

    1. Por padrão, todas as colunas são retornadas. Para retornar colunas específicas, desative Retrieve All Columns e insira os nomes das colunas separados por vírgula.

      Nota

      Por padrão, o Table Store retorna as colunas de chave primária da tabela de dados.

    2. Selecione um operador lógico: And, Or ou Not.

      Se você selecionar And, a consulta retorna dados que atendem a todas as condições especificadas. Se selecionar Or, a consulta retorna dados que atendem a pelo menos uma das condições. Se selecionar Not, a consulta retorna dados que não atendem às condições especificadas.

    3. Selecione um campo de índice do tipo Geopoint e clique em Add.

    4. Defina o tipo de consulta do campo de índice como GeoBoundingBoxQuery e insira as coordenadas dos cantos superior esquerdo e inferior direito do retângulo.

    5. Por padrão, a ordenação está desativada. Para ordenar os resultados por um campo específico, ative Enable Sorting, adicione o campo de ordenação e configure a ordem desejada.

    6. Por padrão, a agregação está desativada. Para realizar agregação estatística em um campo específico, ative Enable Aggregation, adicione o campo de agregação e configure as definições correspondentes.

  4. Clique em OK.

    Os resultados da consulta são exibidos na aba Index Management.

Use the Tablestore CLI

Use o Tablestore CLI para executar o comando search e consultar dados por meio de search indexes. Para mais informações, consulte Search index.

  1. Execute o comando search para usar o search index search_index, consultar dados e retornar todas as colunas indexadas de cada linha que atende às condições de consulta.

    search -n search_index --return_all_indexed
  2. O exemplo a seguir mostra como inserir as condições de consulta conforme solicitado pelo sistema:

    {
        "Offset": -1,
        "Limit": 10,
        "Collapse": null,
        "Sort": null,
        "GetTotalCount": true,
        "Token": null,
        "Query": {
            "Name": "GeoBoundingBoxQuery",
            "Query": {
                "FieldName": "col_geopoint",
                "TopLeft": "10.0",
                "BottomRight": "0.10"
            }
        }
    }

Use Tablestore SDKs

Execute geo-bounding box queries por meio de Tablestore SDK for Java, Tablestore SDK for Go, Tablestore SDK for Python, Tablestore SDK for Node.js, Tablestore SDK for .NET e Tablestore SDK for PHP. No exemplo a seguir, o Tablestore SDK for Java é utilizado para demonstrar como executar geo-bounding box queries.

O exemplo a seguir consulta linhas em que o campo location está dentro da bounding box 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);

Faturamento

A consulta de dados por meio de um Search Index consome throughput de leitura. Para mais informações, consulte Search Index metering and billing.

Perguntas frequentes

Referências