Tablestore:Consulta geográfica

Pré-requisitos

• Uma instância OTSClient foi inicializada. Para mais informações, consulte Inicializar um cliente do Tablestore.

• Uma tabela de dados foi criada e os dados foram gravados nela. Para mais informações, consulte Criar uma tabela de dados e Gravar dados.

• Um índice de pesquisa foi criado para a tabela de dados. Para mais informações, consulte Criar um índice de pesquisa.

Consulta por distância geográfica

Para executar uma consulta por distância geográfica, especifique uma área geográfica circular definindo um ponto central e um raio. O Tablestore retorna as linhas em que o valor de uma coluna específica está dentro dessa área circular.

• Parâmetros

  Parâmetro	Descrição
  field_name	Nome da coluna a ser consultada. O valor deste parâmetro deve ser do tipo de dados GEOPOINT.
  center_point	Par de coordenadas do ponto central, composto por valores de latitude e longitude. O formato é latitude,longitude. Valores válidos para latitude: [-90,+90]. Valores válidos para longitude: [-180,+180]. Exemplo: 35.8,-45.91.
  distance	Raio da área geográfica circular. O valor deste parâmetro é do tipo de dados DOUBLE. Unidade: metros.
  query	Instrução de consulta para o índice de pesquisa. Defina este parâmetro como GeoDistanceQuery.
  table_name	Nome da tabela de dados.
  index_name	Nome do índice de pesquisa.

• Exemplo

  O código de exemplo abaixo demonstra como consultar linhas cujos valores na coluna Col_GeoPoint estejam dentro de uma área geográfica circular com ponto central em '32.5,116.5' e raio de até 300.000 metros:

  query = GeoDistanceQuery('Col_GeoPoint', '32.5,116.5', 300000)
  rows, next_token, total_count, is_all_succeed, agg_results, group_by_results = client.search(
      '<TABLE_NAME>', '<SEARCH_INDEX_NAME>', 
      SearchQuery(query, limit=100, get_total_count=True), 
      ColumnsToGet(return_type=ColumnReturnType.ALL)
  ).v1_response()

Consulta por caixa delimitadora geográfica

Na consulta por caixa delimitadora geográfica, você define uma área retangular informando o canto superior esquerdo e o canto inferior direito. O Tablestore retorna as linhas em que o valor de uma coluna específica se encontra dentro dessa área retangular.

• Parâmetros

  Parâmetro	Descrição
  field_name	Nome da coluna a ser consultada. O valor deste parâmetro deve ser do tipo de dados GEOPOINT.
  top_left	Par de coordenadas do canto superior esquerdo da área geográfica retangular.
  bottom_right	Par de coordenadas do canto inferior direito da área geográfica retangular. Um retângulo pode ser definido pelo canto superior esquerdo e pelo canto inferior direito. O formato é latitude,longitude. Valores válidos para latitude: [-90,+90]. Valores válidos para longitude: [-180,+180]. Exemplo: 35.8,-45.91.
  query	Instrução de consulta para o índice de pesquisa. Defina este parâmetro como GeoBoundingBoxQuery.
  table_name	Nome da tabela de dados.
  index_name	Nome do índice de pesquisa.

• Exemplo

  O trecho de código a seguir ilustra como buscar linhas onde os valores da coluna Col_GeoPoint estejam contidos em uma área retangular cujo canto superior esquerdo é '30.9,112.0' e o canto inferior direito é '30.2,119.0':

  query = GeoBoundingBoxQuery('Col_GeoPoint', '30.9,112.0', '30.2,119.0')
  rows, next_token, total_count, is_all_succeed, agg_results, group_by_results = client.search(
      '<TABLE_NAME>', '<SEARCH_INDEX_NAME>',  
      SearchQuery(query, limit=100, get_total_count=True), 
      ColumnsToGet(return_type=ColumnReturnType.ALL)
  ).v1_response()

Consulta por polígono geográfico

Para realizar uma consulta por polígono geográfico, defina uma área poligonal utilizando pares de coordenadas de múltiplos pontos. O Tablestore devolve as linhas cujo valor em uma coluna específica esteja situado dentro dessa área poligonal.

• Parâmetros

  Parâmetro	Descrição
  field_name	Nome da coluna alvo da consulta. O valor deste parâmetro deve ser do tipo de dados GEOPOINT.
  points	Pares de coordenadas dos pontos que formam o polígono. É possível definir um polígono usando vários pares de coordenadas. O formato é latitude,longitude. Valores válidos para latitude: [-90,+90]. Valores válidos para longitude: [-180,+180]. Exemplo: 35.8,-45.91.
  query	Instrução de consulta para o índice de pesquisa. Defina este parâmetro como GeoPolygonQuery.
  table_name	Nome da tabela de dados.
  index_name	Nome do índice de pesquisa.

• Exemplo

  Veja no código abaixo como consultar linhas com valores na coluna Col_Geopoint que estejam dentro de uma área poligonal formada pelas coordenadas '30.9,112.0', '30.5,115.0', '30.3, 117.0' e '30.2,119.0':

  query = GeoPolygonQuery('Col_GeoPoint', ['30.9,112.0', '30.5,115.0', '30.3, 117.0', '30.2,119.0'])
  rows, next_token, total_count, is_all_succeed, agg_results, group_by_results = client.search(
      '<TABLE_NAME>', '<SEARCH_INDEX_NAME>', 
      SearchQuery(query, limit=100, get_total_count=True), 
      ColumnsToGet(return_type=ColumnReturnType.ALL)
  ).v1_response()

Perguntas frequentes

• O que fazer se nenhuma informação for encontrada ao chamar a operação Search?

• Por que o token perde a validade durante a paginação em consultas baseadas em índice de pesquisa?

Referências

• Ao utilizar um índice de pesquisa para consultar dados, você tem à disposição os seguintes métodos: consulta por termo, consulta por termos, consulta match all, consulta match, consulta match phrase, consulta por prefixo, consulta por intervalo, consulta por curinga, consulta geográfica, consulta booleana, consulta vetorial KNN, consulta aninhada e consulta exists. Esses métodos permitem extrair dados sob diversas perspectivas, conforme a necessidade do seu negócio.

  Utilize os recursos de ordenação e paginação para classificar ou paginar as linhas que atendem aos critérios da consulta. Para mais detalhes, veja Ordenação e paginação.

  Aplique o recurso de colapso (distinct) para agrupar o conjunto de resultados com base em uma coluna específica. Assim, cada tipo de dado especificado aparece apenas uma vez nos resultados. Saiba mais em Colapso (distinct).

• Caso precise analisar dados de uma tabela, utilize o recurso de agregação da operação Search ou execute instruções SQL. Isso permite obter valores mínimos, máximos, somas e contagem total de linhas, entre outros. Consulte Agregação e Consulta SQL para mais informações.

• Se o objetivo for recuperar todas as linhas correspondentes aos critérios sem precisar ordená-las, chame as operações ParallelScan e ComputeSplits para usar a varredura paralela. Veja mais em Varredura paralela.