Funções geográficas no SQL padrão

As funções geográficas operam nos valores GEOGRAPHY do BigQuery ou os geram. A assinatura de qualquer função geográfica começa com ST_. O BigQuery aceita as funções a seguir que podem ser usadas para analisar dados geográficos, determinar relações espaciais entre características geográficas e criar ou manipular GEOGRAPHYs.

As funções geográficas são agrupadas nas categorias a seguir com base no comportamento delas:

  • Construtores: funções que criam novos valores GEOGRAPHY de coordenadas ou GEOGRAPHYs atuais, como ST_GEOGPOINT.
  • Analisadores: funções que criam GEOGRAPHYs de um formato externo, como WKT e GeoJSON. Por exemplo, ST_GEOGFROMTEXT cria um GEOGRAPHY de WKT.
  • Formatadores: funções que exportam GEOGRAPHYs para um formato externo, como WKT e GeoJSON. Por exemplo, ST_ASTEXT formata um GEOGRAPHY para WKT.
  • Transformações: funções que geram um novo GEOGRAPHY de outros que aderem a alguma propriedade. Exemplos incluem ST_INTERSECTION e ST_BOUNDARY.
  • Predicados: funções que retornam TRUE ou FALSE para uma relação espacial entre dois GEOGRAPHYs ou para alguma propriedade de uma região geográfica. Essas funções são muito usadas em cláusulas de filtro. Por exemplo, ST_DWITHIN é um predicado.
  • Acessadores: funções que concedem acesso a propriedades de um GEOGRAPHY sem efeitos colaterais, como ST_NUMPOINTS.
  • Medidas: funções que calculam medições de um ou mais GEOGRAPHYs. Por exemplo, ST_DISTANCE.
  • Funções agregadas: funções agregadas específicas de regiões geográficas, como ST_UNION_AGG.

Todas as funções geográficas do BigQuery retornam NULL se algum argumento de entrada é NULL.

ST_GEOGPOINT

ST_GEOGPOINT(longitude, latitude)

Descrição

Cria um GEOGRAPHY com um único ponto. ST_GEOGPOINT cria um ponto com base nos parâmetros de longitude e latitude FLOAT64 especificados e retorna esse ponto em um valor de GEOGRAPHY.

Restrições

  • As latitudes precisam estar no intervalo [-90, 90]. Latitudes fora desse intervalo resultarão em um erro.
  • Longitudes fora do intervalo [-180, 180] são permitidas. ST_GEOGPOINT usa o módulo de longitude de entrada 360 para conseguir uma longitude dentro de [-180, 180].

Tipo de retorno

GEOGRAPHY

ST_MAKELINE

ST_MAKELINE(geography_1, geography_2)
ST_MAKELINE(array_of_geography)

Descrição

Cria um GEOGRAPHY com uma cadeia de linhas única, concatenando os vértices de ponto ou linha de cada GEOGRAPHY de entrada na ordem em que são inseridos.

A entrada pode ser dois GEOGRAPHYs ou um ARRAY do tipo GEOGRAPHY. Cada GEOGRAPHY de entrada precisa consistir em um dos valores a seguir:

  • Exatamente um ponto
  • Exatamente uma cadeia de linhas

Restrições

Cada aresta precisa abranger estritamente menos de 180 graus.

OBSERVAÇÃO: o processo de ajuste do BigQuery pode descartar arestas suficientemente curtas e ajustar os dois pontos de extremidade juntos. Por exemplo, se cada GEOGRAPHY de entrada contiver um ponto e os dois pontos estiverem separados por uma distância menor que o raio de ajuste, os pontos serão ajustados juntos. Nesse caso, o resultado será um GEOGRAPHY com exatamente um ponto.

Tipo de retorno

GEOGRAPHY

ST_MAKEPOLYGON

ST_MAKEPOLYGON(geography_expression)
ST_MAKEPOLYGON(geography_expression, array_of_geography)

Descrição

Cria um GEOGRAPHY que contém um único polígono de entradas de cadeia de linhas, em que cada cadeia é usada para construir um anel poligonal.

A entrada da cadeia de linhas é fornecida por um único GEOGRAPHY que contém exatamente uma cadeia de linhas ou por um único GEOGRAPHY e uma matriz de GEOGRAPHYs, cada um contendo exatamente uma cadeia de linhas. O primeiro GEOGRAPHY sempre será usado para criar a concha poligonal. Qualquer outro GEOGRAPHY além do primeiro na matriz especifica um buraco poligonal. Para cada GEOGRAPHY de entrada contendo exatamente uma cadeia de linha, os itens a seguir precisam ser verdadeiros:

  • A cadeia de linhas precisa consistir em pelo menos três vértices distintos.
  • A cadeia de linhas precisa ser fechada, ou seja, o primeiro e o último vértices precisam ser os mesmos. Se o primeiro e o último vértices forem diferentes, a função criará uma aresta final do primeiro vértice ao último.

OBSERVAÇÃO: ST_MAKEPOLYGON aceita um GEOGRAPHY vazio como entrada. ST_MAKEPOLYGON interpreta um GEOGRAPHY vazio como tendo uma cadeia de linhas vazia, o que criará um ciclo completo, ou seja, um polígono que abrange toda a Terra.

Restrições

Juntos, os anéis de entrada precisam formar um polígono válido:

  • A concha poligonal precisa cobrir cada um dos buracos poligonais.
  • Só pode haver uma concha poligonal (que precisa ser o primeiro anel de entrada). Isso significa que os buracos poligonais não podem ser aninhados.
  • Anéis poligonais só podem se cruzar em um vértice no limite de ambos os anéis.

Cada aresta precisa abranger estritamente menos de 180 graus.

Cada anel poligonal divide a esfera em duas regiões. A primeira cadeia de linhas de entrada para ST_MAKEPOLYGON forma a concha poligonal, e a parte interna é escolhida para ser a menor das duas regiões. Cada cadeia de linhas de entrada subsequente especifica um buraco poligonal, portanto, o interior do polígono já está bem definido. Para definir uma concha poligonal de maneira que o interior do polígono seja a maior das duas regiões, consulte ST_MAKEPOLYGONORIENTED.

OBSERVAÇÃO: o processo de ajuste do BigQuery pode descartar arestas suficientemente curtas e ajustar os dois pontos de extremidade juntos. Portanto, quando os vértices são ajustados juntos, é possível que um buraco poligonal que seja suficientemente pequeno possa desaparecer ou que o GEOGRAPHY de saída possa conter apenas uma linha ou um ponto.

Tipo de retorno

GEOGRAPHY

ST_MAKEPOLYGONORIENTED

ST_MAKEPOLYGONORIENTED(array_of_geography)

Descrição

Similar a ST_MAKEPOLYGON, mas a ordem dos vértices de cada cadeia de linhas de entrada determina a orientação de cada anel poligonal. A orientação de um anel poligonal define o interior do polígono da seguinte maneira: se alguém caminha ao longo do limite do polígono na ordem dos vértices de entrada, o interior do polígono fica à esquerda. Isso se aplica a cada anel poligonal fornecido.

Essa variante do construtor de polígonos é mais flexível, porque ST_MAKEPOLYGONORIENTED pode criar um polígono de maneira que o interior fique em cada lado do anel poligonal. No entanto, a orientação adequada dos anéis poligonais é fundamental para a criação do polígono desejado.

OBSERVAÇÃO: o argumento de entrada de ST_MAKEPOLYGONORIENTED pode conter um GEOGRAPHY vazio. ST_MAKEPOLYGONORIENTED interpreta um GEOGRAPHY vazio como tendo uma cadeia de linhas vazia, o que criará um ciclo completo, ou seja, um polígono que abrange toda a Terra.

Restrições

Juntos, os anéis de entrada precisam formar um polígono válido:

  • A concha poligonal precisa cobrir cada um dos buracos poligonais.
  • Só pode haver uma concha poligonal, que precisa ser o primeiro anel de entrada. Isso significa que os buracos poligonais não podem ser aninhados.
  • Anéis poligonais só podem se cruzar em um vértice no limite de ambos os anéis.

Cada aresta precisa abranger estritamente menos de 180 graus.

ST_MAKEPOLYGONORIENTED depende da ordenação dos vértices de entrada de cada cadeia de linhas para determinar a orientação do polígono. Isso se aplica à concha poligonal e a qualquer buraco poligonal. ST_MAKEPOLYGONORIENTED espera que todos os buracos poligonais tenham a orientação oposta da concha. Consulte ST_MAKEPOLYGON para ver um construtor de polígonos alternativo e outras restrições na criação de um polígono válido.

OBSERVAÇÃO: por causa do processo de ajuste do BigQuery, as arestas com comprimento suficientemente curto serão descartadas e os dois pontos de extremidade serão ajustados em um único ponto. Portanto, é possível que os vértices em uma cadeia de linhas sejam ajustados de modo que uma ou mais arestas desapareçam. Assim, é possível que um buraco poligonal que seja suficientemente pequeno possa desaparecer ou que o GEOGRAPHY resultante possa conter apenas uma linha ou um ponto.

Tipo de retorno

GEOGRAPHY

ST_GEOGFROMGEOJSON

ST_GEOGFROMGEOJSON(geojson_string)

Descrição

Retorna um valor GEOGRAPHY que corresponde à representação GeoJSON de entrada.

ST_GEOGFROMGEOJSON aceita entradas compatíveis com RFC 7946.

Um GEOGRAPHY do BigQuery tem arestas geodésicas esféricas, enquanto um objeto Geometry do GeoJSON tem arestas claramente planas. Para fazer uma conversão entre esses dois tipos de arestas, o BigQuery adiciona pontos à linha conforme necessário, de modo que a sequência de arestas permaneça no máximo a dez metros da aresta original.

Consulte ST_ASGEOJSON para formatar um GEOGRAPHY como GeoJSON.

Restrições

A entrada está sujeita às restrições a seguir:

  • ST_GEOGFROMGEOJSON aceita somente fragmentos de geometria JSON e não pode ser usado para processar um documento JSON inteiro.
  • O fragmento JSON de entrada precisa consistir em um tipo de geometria GeoJSON, que inclui Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon e GeometryCollection. Qualquer outro tipo de GeoJSON, como Feature ou FeatureCollection, resultará em erro.
  • Uma posição no membro coordinates de um tipo de geometria GeoJSON precisa consistir exatamente em dois elementos. O primeiro é longitude e o segundo é latitude. Portanto, ST_GEOGFROMGEOJSON não aceita o terceiro elemento opcional para uma posição no membro coordinates.

Tipo de retorno

GEOGRAPHY

ST_GEOGFROMTEXT

ST_GEOGFROMTEXT(wkt_string)
ST_GEOGFROMTEXT(wkt_string, oriented)

Descrição

Retorna um valor GEOGRAPHY que corresponde à representação WKT de entrada.

Esta função aceita um parâmetro opcional do tipo BOOL, oriented. Se esse parâmetro for definido como TRUE, a orientação de todos os polígonos na entrada será pressuposta da seguinte maneira: se alguém caminha ao longo do limite do polígono na ordem dos vértices de entrada, o interior do polígono fica à esquerda. Isso permite que o WKT represente polígonos maiores que um hemisfério. Se oriented for FALSE ou omitido, essa função retornará o polígono com a área menor. Consulte também ST_MAKEPOLYGONORIENTED, que é semelhante a ST_GEOGFROMTEXT com oriented=TRUE.

Para formatar GEOGRAPHY como WKT, use ST_ASTEXT.

Restrições

Todas as arestas de entrada são consideradas geodésicas esféricas e não linhas retas planas. Para a leitura de dados em uma projeção planar, considere o uso de ST_GEOGFROMGEOJSON. Para mais informações sobre as diferenças entre linhas geodésicas esféricas e planas, consulte Arestas e sistemas de coordenadas.

Tipo de retorno

GEOGRAPHY

Exemplo

A consulta a seguir lê a string POLYGON((0 0, 0 2, 2 2, 0 2, 0 0)) do WKT como um polígono não orientado e como um polígono orientado, e verifica se cada resultado contém o ponto (1, 1).

WITH polygon AS (SELECT 'Polygon((0 0, 0 2, 2 2, 2 0, 0 0))' AS p)
SELECT
  ST_CONTAINS(ST_GEOGFROMTEXT(p), ST_GEOGPOINT(1, 1)) AS fromtext_default,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, FALSE), ST_GEOGPOINT(1, 1)) AS non_oriented,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, TRUE),  ST_GEOGPOINT(1, 1)) AS oriented
FROM polygon;

+-------------------+---------------+-----------+
| fromtext_default  | non_oriented  | oriented  |
+-------------------+---------------+-----------+
| true              | true          | false     |
+-------------------+---------------+-----------+

ST_GEOGFROMWKB

ST_GEOGFROMWKB(wkb_bytes)

Descrição

Retorna um valor GEOGRAPHY que corresponde à representação WKB de entrada.

Para formatar GEOGRAPHY como WKB, use ST_ASBINARY.

Restrições

Todas as arestas de entrada são consideradas geodésicas esféricas e não linhas retas planas. Para a leitura de dados em uma projeção planar, considere o uso de ST_GEOGFROMGEOJSON.

Tipo de retorno

GEOGRAPHY

ST_ASGEOJSON

ST_ASGEOJSON(geography_expression)

Descrição

Retorna a representação GeoJSON em conformidade com RFC 7946 do GEOGRAPHY de entrada.

Um GEOGRAPHY do BigQuery tem arestas geodésicas esféricas, enquanto um objeto Geometry do GeoJSON tem arestas claramente planas. Para fazer uma conversão entre esses dois tipos de arestas, o BigQuery adiciona pontos à linha conforme necessário, de modo que a sequência de arestas permaneça no máximo a dez metros da aresta original.

Consulte ST_GEOGFROMGEOJSON para criar um GEOGRAPHY no GeoJSON.

Tipo de retorno

STRING

ST_ASTEXT

ST_ASTEXT(geography_expression)

Descrição

Retorna a representação WKT de um GEOGRAPHY de entrada.

Consulte ST_GEOGFROMTEXT para criar um GEOGRAPHY no WKT.

Tipo de retorno

STRING

ST_GEOHASH

ST_GEOHASH(geography_expression, maxchars)

Descrição

Retorna uma representação GeoHash de geography_expression. O GeoHash resultante conterá no máximo maxchars caracteres. Menos caracteres correspondem a uma precisão menor (ou, descrito de maneira diferente, a uma faixa delimitadora maior).

ST_GeoHash em um objeto GEOGRAPHY vazio retorna NULL.

Restrições

  • Apenas objetos GEOGRAPHY que representam pontos únicos são aceitos.
  • O valor máximo de maxchars é 20.

Exemplo

Retorna um GeoHash do Seattle Center com dez caracteres de precisão.

SELECT ST_GEOHASH(ST_GEOGPOINT(-122.35, 47.62), 10) geohash

+--------------+
| geohash      |
+--------------+
| c22yzugqw7   |
+--------------+

Tipo de retorno

STRING

ST_ASBINARY

ST_ASBINARY(geography_expression)

Descrição

Retorna a representação WKB de um GEOGRAPHY de entrada.

Consulte ST_GEOGFROMWKB para criar um GEOGRAPHY no WKB.

Tipo de retorno

BYTES

ST_BOUNDARY

ST_BOUNDARY(geography_expression)

Descrição

Retorna um único GEOGRAPHY que contém a união dos limites de cada componente no GEOGRAPHY de entrada fornecido.

O limite de cada componente de um GEOGRAPHY é definido da seguinte maneira:

  • O limite de um ponto fica vazio.
  • O limite de uma cadeia de linhas consiste nos pontos de extremidade da cadeia de linhas.
  • O limite de um polígono consiste nas cadeias de linhas que formam a concha poligonal e em cada um dos buracos poligonais.

Tipo de retorno

GEOGRAPHY

ST_CENTROID

ST_CENTROID(geography_expression)

Descrição

Retorna o centroide do GEOGRAPHY de entrada como um GEOGRAPHY de ponto único.

O centroide de um GEOGRAPHY é a média ponderada dos centroides dos componentes de maior dimensão do GEOGRAPHY. O centroide para componentes em cada dimensão é definido da seguinte maneira:

  • O centroide de pontos é a média aritmética das coordenadas de entrada.
  • O centroide das cadeias de linhas é o centroide de todas as arestas ponderadas pelo comprimento. O centroide de cada aresta é o ponto médio geodésico da aresta.
  • O centroide de um polígono é o centro de massa dele.

Se o GEOGRAPHY de entrada estiver vazio, um GEOGRAPHY vazio será retornado.

Restrições

No caso improvável de o centroide de um GEOGRAPHY não poder ser definido por um único ponto na superfície da Terra, um ponto determinístico arbitrário será retornado. Isso só pode acontecer se o centroide estiver exatamente no centro da Terra, como o centroide de um par de pontos antipodais, e a probabilidade de isso acontecer é muito pequena.

Tipo de retorno

GEOGRAPHY

ST_CLOSESTPOINT

ST_CLOSESTPOINT(geography_1, geography_2)
ST_CLOSESTPOINT(geography_1, geography_2, use_spheroid)

Descrição

Retorna um GEOGRAPHY que contém um ponto em geography_1 com a menor distância possível para geography_2. Isso significa que a distância entre o ponto retornado por ST_CLOSESTPOINT e geography_2 é menor ou igual à distância entre qualquer outro ponto em geography_1 e geography_2.

Se qualquer um dos GEOGRAPHYs de entrada estiver vazio, ST_CLOSESTPOINT retornará NULL.

O parâmetro opcional use_spheroid determina como essa função mede a distância. Se use_spheroid for FALSE, a função medirá a distância na superfície de uma esfera perfeita.

Atualmente, o parâmetro use_spheroid aceita apenas o valor FALSE. O valor padrão de use_spheroid é FALSE.

Tipo de retorno

GEOGRAPHY

ST_DIFFERENCE

ST_DIFFERENCE(geography_1, geography_2)

Descrição

Retorna um GEOGRAPHY que representa a diferença do conjunto de pontos entre geography_1 e geography_2.

Se geometry_1 estiver completamente contido em geometry_2, ST_DIFFERENCE retornará um GEOGRAPHY vazio.

Restrições

Os objetos geométricos subjacentes representados por um GEOGRAPHY do BigQuery correspondem a um conjunto de pontos fechados. Portanto, ST_DIFFERENCE é o encerramento da diferença do conjunto de pontos de geography_1 e geography_2. Isso significa que, caso geography_1 e geography_2 se cruzem, uma parte do limite de geography_2 poderá estar na diferença

Tipo de retorno

GEOGRAPHY

ST_INTERSECTION

ST_INTERSECTION(geography_1, geography_2)

Descrição

Retorna um GEOGRAPHY que representa a interseção do conjunto de pontos dos dois GEOGRAPHYs de entrada. Assim, cada ponto na interseção aparece em geography_1 e geography_2.

Se os dois GEOGRAPHYs de entrada forem disjuntos, isto é, não houver pontos que apareçam em geometry_1 e geometry_2 de entrada, um GEOGRAPHY vazio será retornado.

Consulte ST_INTERSECTS, ST_DISJOINT para funções de predicado relacionadas.

Tipo de retorno

GEOGRAPHY

ST_SNAPTOGRID

ST_SNAPTOGRID(geography_expression, grid_size)

Descrição

Retorna o GEOGRAPHY de entrada, em que cada vértice foi ajustado em uma grade de longitude/latitude. O tamanho da grade é determinado pelo parâmetro grid_size, que é fornecido em graus.

Restrições

Tamanhos de grade arbitrários não são aceitos. O parâmetro grid_size é arredondado para que fique no formato \(10^n\), em que \(-10 < n < 0\).

Tipo de retorno

GEOGRAPHY

ST_UNION

ST_UNION(geography_1, geography_2)
ST_UNION(array_of_geography)

Descrição

Retorna um GEOGRAPHY que representa a união do conjunto de pontos de todos os GEOGRAPHYs de entrada.

A entrada pode ser dois GEOGRAPHYs ou um ARRAY do tipo GEOGRAPHY.

Consulte ST_UNION_AGG para a versão agregada de ST_UNION.

Tipo de retorno

GEOGRAPHY

ST_X

ST_X(geography_expression)

Descrição

Retorna a longitude em graus do GEOGRAPHY de entrada de ponto único.

Para qualquer GEOGRAPHY de entrada que não seja de ponto único, incluindo um GEOGRAPHY vazio, ST_X retornará um erro. Use o prefixo SAFE. para conseguir NULL.

Tipo de retorno

FLOAT64

Exemplo

O exemplo a seguir usa ST_X e ST_Y para extrair coordenadas de geografias de ponto único.

WITH points AS
   (SELECT ST_GEOGPOINT(i, i + 1) AS p FROM UNNEST([0, 5, 12]) AS i)
 SELECT
   p,
   ST_X(p) as longitude,
   ST_Y(p) as latitude
FROM points;

+--------------+-----------+----------+
| p            | longitude | latitude |
+--------------+-----------+----------+
| POINT(0 1)   | 0.0       | 1.0      |
| POINT(5 6)   | 5.0       | 6.0      |
| POINT(12 13) | 12.0      | 13.0     |
+--------------+-----------+----------+

ST_Y

ST_Y(geography_expression)

Descrição

Retorna a latitude em graus do GEOGRAPHY de entrada de ponto único.

Para qualquer GEOGRAPHY de entrada que não seja de ponto único, incluindo um GEOGRAPHY vazio, ST_Y retornará um erro. Use o prefixo SAFE. para retornar NULL.

Tipo de retorno

FLOAT64

Exemplo

Consulte ST_X para ver um exemplo de uso.

ST_CONTAINS

ST_CONTAINS(geography_1, geography_2)

Descrição

Retornará TRUE se nenhum ponto de geography_2 estiver fora de geography_1 e os interiores se cruzarem. Retornará FALSE se isso não acontecer.

OBSERVAÇÃO: um GEOGRAPHY não contém o próprio limite. Compare com ST_COVERS.

Tipo de retorno

BOOL

Exemplo

A consulta a seguir testa se o polígono POLYGON((1 1, 20 1, 10 20, 1 1)) contém os pontos (0, 0), (1, 1) e (10, 10), no exterior, no limite e no interior do polígono, respectivamente.

SELECT
  ST_GEOGPOINT(i, i) AS p,
  ST_CONTAINS(ST_GEOGFROMTEXT('POLYGON((1 1, 20 1, 10 20, 1 1))'),
              ST_GEOGPOINT(i, i)) AS `contains`
FROM UNNEST([0, 1, 10]) AS i;

+--------------+----------+
| p            | contains |
+--------------+----------+
| POINT(0 0)   | false    |
| POINT(1 1)   | false    |
| POINT(10 10) | true     |
+--------------+----------+

ST_COVEREDBY

ST_COVEREDBY(geography_1, geography_2)

Descrição

Retornará FALSE se geography_1 ou geography_2 estiver vazio. Retornará TRUE se nenhum ponto de geography_1 estiver na parte externa de geography_2.

Ao inserir dois GEOGRAPHYs a e b, ST_COVEREDBY(a, b) retorna o mesmo resultado que ST_COVERS(b, a). Observe a ordem oposta dos argumentos.

Tipo de retorno

BOOL

ST_COVERS

ST_COVERS(geography_1, geography_2)

Descrição

Retornará FALSE se geography_1 ou geography_2 estiver vazio. Retornará TRUE se nenhum ponto de geography_2 estiver na parte externa de geography_1.

Tipo de retorno

BOOL

Exemplo

A consulta a seguir testa se o polígono POLYGON((1 1, 20 1, 10 20, 1 1)) cobre cada um dos pontos (0, 0), (1, 1) e (10, 10), que estão no exterior, no limite e no interior do polígono, respectivamente.

SELECT
  ST_GEOGPOINT(i, i) AS p,
  ST_COVERS(ST_GEOGFROMTEXT('POLYGON((1 1, 20 1, 10 20, 1 1))'),
            ST_GEOGPOINT(i, i)) AS `covers`
FROM UNNEST([0, 1, 10]) AS i;

+--------------+--------+
| p            | covers |
+--------------+--------+
| POINT(0 0)   | false  |
| POINT(1 1)   | true   |
| POINT(10 10) | true   |
+--------------+--------+

ST_DISJOINT

ST_DISJOINT(geography_1, geography_2)

Descrição

Retornará TRUE se a interseção de geography_1 e geography_2 estiver vazia, ou seja, nenhum ponto em geography_1 também aparecer em geography_2.

ST_DISJOINT é a negação lógica de ST_INTERSECTS.

Tipo de retorno

GEOGRAPHY

ST_DWITHIN

ST_DWITHIN(geography_1, geography_2), distance)
ST_DWITHIN(geography_1, geography_2, distance, use_spheroid)

Descrição

Retornará TRUE se a distância entre pelo menos um ponto em geography_1 e um ponto em geography_2 for menor ou igual à distância indicada pelo argumento distance. Caso contrário, retornará FALSE. Se o GEOGRAPHY de entrada estiver vazio, ST_DWithin retornará FALSE. O valor de distance especificado é em metros na superfície da Terra.

O parâmetro opcional use_spheroid determina como essa função mede a distância. Se use_spheroid for FALSE, a função medirá a distância na superfície de uma esfera perfeita.

Atualmente, o parâmetro use_spheroid aceita apenas o valor FALSE. O valor padrão de use_spheroid é FALSE.

Tipo de retorno

BOOL

ST_EQUALS

ST_EQUALS(geography_1, geography_2)

Descrição

Retornará TRUE se geography_1 e geography_2 representarem o mesmo valor de GEOGRAPHY. Mais precisamente, isso significa que uma das condições a seguir é válida:

  • ST_COVERS(geography_1, geography_2) = TRUE e ST_COVERS(geography_2, geography_1) = TRUE
  • geography_1 e geography_2 estão vazios

Portanto, dois GEOGRAPHYs poderão ser iguais, mesmo se a ordenação de pontos ou vértices for diferente, desde que eles ainda representem a mesma estrutura geométrica.

Restrições

Não é garantido que ST_EQUALS seja uma função transitiva.

Tipo de retorno

BOOL

ST_INTERSECTS

ST_INTERSECTS(geography_1, geography_2)

Descrição

Retornará TRUE se a interseção do conjunto de pontos de geography_1 e geography_2 não estiver vazia. Assim, esta função retornará TRUE se houver pelo menos um ponto que apareça nos dois GEOGRAPHYs de entrada.

Se ST_INTERSECTS retornar TRUE, significa que ST_DISJOINT retornará FALSE.

Tipo de retorno

BOOL

ST_INTERSECTSBOX

ST_INTERSECTSBOX(geography, lng1, lat1, lng2, lat2)

Descrição

Retornará TRUE se o geography cruzar o retângulo entre [lng1, lng2] e [lat1, lat2]. As arestas do retângulo seguem linhas constantes de longitude e latitude. lng1 e lng2 especificam as linhas de longitude mínima e máxima que ligam o retângulo, e lat1 e lat2 especificam as linhas de latitude constante mínima e máxima que ligam o retângulo.

Especifique todos os argumentos de longitude e latitude em graus.

Restrições

Os argumentos de entrada estão sujeitos às restrições a seguir:

  • As latitudes precisam estar no intervalo de [-90, 90] graus.
  • As longitudes precisam estar no intervalo de [-180, 180] graus.

Tipo de retorno

BOOL

ST_TOUCHES

ST_TOUCHES(geography_1, geography_2)

Descrição

Retornará TRUE desde que as duas condições a seguir sejam satisfeitas:

  1. geography_1 cruza com geography_2.
  2. Os interiores de geography_1 e de geography_2 são disjuntos.

Tipo de retorno

BOOL

ST_WITHIN

ST_WITHIN(geography_1, geography_2)

Descrição

Retornará TRUE se nenhum ponto de geography_1 estiver fora de geography_2 e os interiores de geography_1 e geography_2 se cruzarem.

Ao inserir duas regiões geográficas a e b, ST_WITHIN(a, b) retorna o mesmo resultado que ST_CONTAINS(b, a). Observe a ordem oposta dos argumentos.

Tipo de retorno

BOOL

ST_ISEMPTY

ST_ISEMPTY(geography_expression)

Descrição

Retornará TRUE se o GEOGRAPHY inserido estiver vazio, ou seja, o GEOGRAPHY não contiver pontos, linhas ou polígonos.

OBSERVAÇÃO: um GEOGRAPHY do BigQuery vazio não está associado a uma forma geométrica específica. Por exemplo, os resultados das expressões ST_GEOGFROMTEXT('POINT EMPTY') e ST_GEOGFROMTEXT('GEOMETRYCOLLECTION EMPTY') são idênticos.

Tipo de retorno

BOOL

ST_ISCOLLECTION

ST_ISCOLLECTION(geography_expression)

Descrição

Retornará TRUE se o número total de pontos, cadeias de linhas e polígonos for maior que um.

Um GEOGRAPHY vazio não é uma coleção.

Tipo de retorno

BOOL

ST_DIMENSION

ST_DIMENSION(geography_expression)

Descrição

Retorna a dimensão do elemento de maior dimensão no GEOGRAPHY de entrada.

A dimensão de cada elemento possível é a seguinte:

  • A dimensão de um ponto é 0.
  • A dimensão de uma cadeia de linhas é 1.
  • A dimensão de um polígono é 2.

Se o GEOGRAPHY de entrada estiver vazio, ST_DIMENSION retornará -1.

Tipo de retorno

INT64

ST_NUMPOINTS

ST_NUMPOINTS(geography_expression)

Descrição

Retornará o número de vértices no GEOGRAPHY de entrada. Isso inclui o número de pontos, de vértices da cadeia de linhas e de vértices do polígono.

OBSERVAÇÃO: o primeiro e o último vértices de um anel poligonal são contados como vértices distintos.

Tipo de retorno

INT64

ST_AREA

ST_AREA(geography_expression)
ST_AREA(geography_expression, use_spheroid)

Descrição

Retorna a área em metros quadrados coberta pelos polígonos no GEOGRAPHY de entrada.

Se geography_expression for um ponto ou uma linha, será retornado zero. Se geography_expression for uma coleção, será retornada a área dos polígonos na coleção. Se a coleção não contiver polígonos, será retornado zero.

O parâmetro opcional use_spheroid determina como essa função mede a distância. Se use_spheroid for FALSE, a função medirá a distância na superfície de uma esfera perfeita.

Atualmente, o parâmetro use_spheroid aceita apenas o valor FALSE. O valor padrão de use_spheroid é FALSE.

Tipo de retorno

FLOAT64

ST_DISTANCE

ST_DISTANCE(geography_1, geography_2)
ST_DISTANCE(geography_1, geography_2, use_spheroid)

Descrição

Retorna a menor distância em metros entre dois GEOGRAPHYs não vazios.

Se qualquer um dos GEOGRAPHYs de entrada estiver vazio, ST_DISTANCE retornará NULL.

O parâmetro opcional use_spheroid determina como essa função mede a distância. Se use_spheroid for FALSE, a função medirá a distância na superfície de uma esfera perfeita.

Atualmente, o parâmetro use_spheroid aceita apenas o valor FALSE. O valor padrão de use_spheroid é FALSE.

Tipo de retorno

FLOAT64

ST_LENGTH

ST_LENGTH(geography_expression)
ST_LENGTH(geography_expression, use_spheroid)

Descrição

Retorna o comprimento total em metros das linhas no GEOGRAPHY de entrada.

Se geography_expression for um ponto ou um polígono, será retornado zero. Se geography_expression for uma coleção, será retornado o tamanho das linhas na coleção. Se a coleção não contiver linhas, será retornado zero.

O parâmetro opcional use_spheroid determina como essa função mede a distância. Se use_spheroid for FALSE, a função medirá a distância na superfície de uma esfera perfeita.

Atualmente, o parâmetro use_spheroid aceita apenas o valor FALSE. O valor padrão de use_spheroid é FALSE.

Tipo de retorno

FLOAT64

ST_MAXDISTANCE

ST_MAXDISTANCE(geography_1, geography_2)
ST_MAXDISTANCE(geography_1, geography_2, use_spheroid)

Retorna a maior distância em metros entre dois GEOGRAPHYs não vazios, ou seja, a distância entre dois vértices em que o primeiro está no primeiro GEOGRAPHY e o segundo está no segundo GEOGRAPHY. Se geography_1 e geography_2 forem o mesmo GEOGRAPHY, a função retornará a distância entre os dois vértices mais distantes naquele GEOGRAPHY.

Se qualquer um dos GEOGRAPHYs de entrada estiver vazio, ST_MAXDISTANCE retornará NULL.

O parâmetro opcional use_spheroid determina como essa função mede a distância. Se use_spheroid for FALSE, a função medirá a distância na superfície de uma esfera perfeita.

Atualmente, o parâmetro use_spheroid aceita apenas o valor FALSE. O valor padrão de use_spheroid é FALSE.

Tipo de retorno

FLOAT64

ST_PERIMETER

ST_PERIMETER(geography_expression)
ST_PERIMETER(geography_expression, use_spheroid)

Descrição

Retorna o comprimento em metros do limite dos polígonos no GEOGRAPHY de entrada.

Se geography_expression for um ponto ou uma linha, será retornado zero. Se geography_expression for uma coleção, será retornado o perímetro dos polígonos na coleção. Se a coleção não contiver polígonos, será retornado zero.

O parâmetro opcional use_spheroid determina como essa função mede a distância. Se use_spheroid for FALSE, a função medirá a distância na superfície de uma esfera perfeita.

Atualmente, o parâmetro use_spheroid aceita apenas o valor FALSE. O valor padrão de use_spheroid é FALSE.

Tipo de retorno

FLOAT64

ST_UNION_AGG

ST_UNION_AGG(geography)

Descrição

Retorna um GEOGRAPHY que representa a união do conjunto de pontos de todos os GEOGRAPHYs de entrada.

Consulte ST_UNION para a versão não agregada de ST_UNION_AGG.

Tipo de retorno

GEOGRAPHY

ST_CENTROID_AGG

ST_CENTROID_AGG(geography)

Descrição

Calcula o centroide do conjunto de GEOGRAPHYs de entrada como um GEOGRAPHY de único ponto.

O centroide do conjunto de GEOGRAPHYs de entrada é a média ponderada do centroide de cada GEOGRAPHY individual. Apenas os GEOGRAPHYs com a maior dimensão presentes na entrada contribuem para o centroide de todo o conjunto. Por exemplo, se a entrada contiver GEOGRAPHYs com linhas e GEOGRAPHYs apenas com pontos, ST_CENTROID_AGG retornará a média ponderada dos GEOGRAPHYs com linhas, desde que eles tenham dimensão máxima. Neste exemplo, ST_CENTROID_AGG ignora GEOGRAPHYs apenas com pontos ao calcular o centroide agregado.

Consulte ST_CENTROID para a versão não agregada de ST_CENTROID_AGG e a definição de centroide para um valor de GEOGRAPHY individual.

Tipo de retorno

GEOGRAPHY

Exemplo

As consultas a seguir calculam o centroide agregado sobre um conjunto de valores de GEOGRAPHY. A entrada para a primeira consulta contém apenas pontos e, portanto, cada valor contribui para o centroide agregado. Observe também que ST_CENTROID_AGG não equivale a chamar ST_CENTROID no resultado de ST_UNION_AGG. As duplicatas são removidas pela união, ao contrário de ST_CENTROID_AGG. A entrada para a segunda consulta tem dimensões mistas, e apenas os valores com a maior dimensão no conjunto, as linhas, afetam o centroide agregado.

SELECT ST_CENTROID_AGG(points) AS st_centroid_agg,
ST_CENTROID(ST_UNION_AGG(points)) AS centroid_of_union
FROM UNNEST([ST_GEOGPOINT(1, 5),
             ST_GEOGPOINT(1, 2),
             ST_GEOGPOINT(1, -1),
             ST_GEOGPOINT(1, -1)]) points;

+---------------------------+-------------------+
| st_centroid_agg           | centroid_of_union |
+---------------------------+-------------------+
| POINT(1 1.24961422620969) | POINT(1 2)        |
+---------------------------+-------------------+

SELECT ST_CENTROID_AGG(points) AS st_centroid_agg
FROM UNNEST([ST_GEOGPOINT(50, 26),
             ST_GEOGPOINT(34, 33.3),
             ST_GEOGFROMTEXT('LINESTRING(0 -1, 0 1)')
             ST_GEOGFROMTEXT('LINESTRING(0 1, 0 3)')]) points;

+-----------------+
| st_centroid_agg |
+-----------------+
| POINT(0 1)      |
+-----------------+
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.