Funções geográficas

O GoogleSQL para BigQuery é compatível com funções geográficas. As funções geográficas operam nos valores GEOGRAPHY do Google SQL ou geram esses valores. A assinatura da maioria das funções geográficas começa com ST_. O GoogleSQL para 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.

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

Categorias

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

Categoria	Funções	Descrição
Construtores	ST_GEOGPOINT ST_MAKELINE ST_MAKEPOLYGON ST_MAKEPOLYGONORIENTED	Funções que criam novos valores geográficos a partir de coordenadas ou geografias existentes.
Analisadores	ST_GEOGFROM ST_GEOGFROMGEOJSON ST_GEOGFROMTEXT ST_GEOGFROMWKB ST_GEOGPOINTFROMGEOHASH	Funções que criam geografias a partir de um formato externo, como WKT e GeoJSON.
Formatadores	ST_ASBINARY ST_ASGEOJSON ST_ASTEXT ST_GEOHASH	Funções que exportam geografias para um formato externo, como WKT.
Transformações	ST_BOUNDARY ST_BUFFER ST_BUFFERWITHTOLERANCE ST_CENTROID ST_CENTROID_AGG (Agregado) ST_CLOSESTPOINT ST_CONVEXHULL ST_DIFFERENCE ST_EXTERIORRING ST_INTERIORRINGS ST_INTERSECTION ST_SIMPLIFY ST_SNAPTOGRID ST_UNION ST_UNION_AGG (Agregado)	Funções que geram uma nova geografia com base na entrada.
Acessores	ST_DIMENSION ST_DUMP ST_ENDPOINT ST_GEOMETRYTYPE ST_ISCLOSED ST_ISCOLLECTION ST_ISEMPTY ST_ISRING ST_NPOINTS ST_NUMGEOMETRIES ST_NUMPOINTS ST_POINTN ST_STARTPOINT ST_X ST_Y	Funções que dão acesso a propriedades de uma geografia sem efeitos colaterais.
Predicados	ST_CONTAINS ST_COVEREDBY ST_COVERS ST_DISJOINT ST_DWITHIN ST_EQUALS ST_INTERSECTS ST_INTERSECTSBOX ST_TOUCHES ST_WITHIN	Funções que retornam TRUE ou FALSE para uma relação espacial entre duas geografias ou alguma propriedade de uma geografia. Essas funções são muito usadas em cláusulas de filtro.
Medidas	ST_ANGLE ST_AREA ST_AZIMUTH ST_BOUNDINGBOX ST_DISTANCE ST_EXTENT (Agregar) ST_LENGTH ST_MAXDISTANCE ST_PERIMETER	Funções que calculam as medidas de uma ou mais geografias.
Cluster	ST_CLUSTERDBSCAN	Funções que executam o clustering em geografias.
Funções S2	S2_CELLIDFROMPOINT S2_COVERINGCELLIDS	Funções para trabalhar com coberturas de células S2 de GEOGRAPHY.

S2_CELLIDFROMPOINT

S2_CELLIDFROMPOINT(point_geography[, level => cell_level])

Descrição

Retorna o ID de célula S2 que abrange um ponto GEOGRAPHY.

• O parâmetro INT64 opcional level especifica o nível de célula S2 para a célula retornada. A nomeação desse argumento é opcional.

Essa é uma funcionalidade avançada para a interoperabilidade com sistemas, usando a biblioteca de geometria S2.

Restrições

• Retorna o ID da célula como um bit INT64 equivalente assinado para representação não assinada de números inteiros de 64 bits.
• Pode retornar IDs de células negativos.
• Os níveis válidos de células S2 são de 0 a 30.
• level terá 30 como padrão se não for especificado explicitamente.
• A função é compatível apenas com um GEOGRAPHY de ponto único. Use o prefixo SAFE se a entrada puder ser multiponto, LineString, polígono ou um GEOGRAPHY vazio.
• Para calcular a cobertura de um GEOGRAPHY complexo, use S2_COVERINGCELLIDS.

Tipo de retorno

INT64

Exemplo

WITH data AS (
  SELECT 1 AS id, ST_GEOGPOINT(-122, 47) AS geo
  UNION ALL
  -- empty geography is not supported
  SELECT 2 AS id, ST_GEOGFROMTEXT('POINT EMPTY') AS geo
  UNION ALL
  -- only points are supported
  SELECT 3 AS id, ST_GEOGFROMTEXT('LINESTRING(1 2, 3 4)') AS geo
)
SELECT id,
       SAFE.S2_CELLIDFROMPOINT(geo) cell30,
       SAFE.S2_CELLIDFROMPOINT(geo, level => 10) cell10
FROM data;

+----+---------------------+---------------------+
| id | cell30              | cell10              |
+----+---------------------+---------------------+
| 1  | 6093613931972369317 | 6093613287902019584 |
| 2  | NULL                | NULL                |
| 3  | NULL                | NULL                |
+----+---------------------+---------------------+

S2_COVERINGCELLIDS

S2_COVERINGCELLIDS(
    geography
    [, min_level => cell_level]
    [, max_level => cell_level]
    [, max_cells => max_cells]
    [, buffer => buffer])

Descrição

Retorna uma matriz de IDs de células S2 que abrangem o GEOGRAPHY da entrada. A função retorna no máximo max_cells células. Os argumentos opcionais min_level e max_level especificam os níveis mínimo e máximo das células S2 retornadas. O tamanho da matriz é limitado pelo argumento max_cells opcional. O argumento opcional buffer especifica um fator de armazenamento em buffer em metros. A região coberta será expandida no alcance da região geográfica de entrada por esse valor.

Essa é uma funcionalidade avançada para a interoperabilidade com sistemas, usando a biblioteca de geometria S2.

Restrições

• Retorna o ID da célula como um bit INT64 equivalente assinado para representação não assinada de números inteiros de 64 bits.
• Pode retornar IDs de células negativos.
• Os níveis válidos de células S2 são de 0 a 30.
• max_cells será definido como 8 se não for especificado explicitamente.
• buffer não pode ser negativo. Se não for especificado explicitamente, o padrão será 0,0 metro.

Tipo de retorno

ARRAY<INT64>

Exemplo

WITH data AS (
  SELECT 1 AS id, ST_GEOGPOINT(-122, 47) AS geo
  UNION ALL
  SELECT 2 AS id, ST_GEOGFROMTEXT('POINT EMPTY') AS geo
  UNION ALL
  SELECT 3 AS id, ST_GEOGFROMTEXT('LINESTRING(-122.12 47.67, -122.19 47.69)') AS geo
)
SELECT id, S2_COVERINGCELLIDS(geo, min_level => 12) cells
FROM data;

+----+--------------------------------------------------------------------------------------+
| id | cells                                                                                |
+----+--------------------------------------------------------------------------------------+
| 1  | [6093613931972369317]                                                                |
| 2  | []                                                                                   |
| 3  | [6093384954555662336, 6093390709811838976, 6093390735581642752, 6093390740145045504, |
|    |  6093390791416217600, 6093390812891054080, 6093390817187069952, 6093496378892222464] |
+----+--------------------------------------------------------------------------------------+

ST_ANGLE

ST_ANGLE(point_geography_1, point_geography_2, point_geography_3)

Descrição

Toma três valores GEOGRAPHY de ponto, que representam duas linhas de interseção. Retorna o ângulo entre essas linhas. Os pontos 2 e 1 representam a primeira linha, e os pontos 2 e 3 representam a segunda. O ângulo entre essas linhas está em radianos, no intervalo [0, 2pi). O ângulo é medido no sentido horário a partir da primeira linha até a segunda linha.

ST_ANGLE tem os seguintes casos extremos:

• Se os pontos 2 e 3 forem os mesmos, retornará NULL.
• Se os pontos 2 e 1 forem os mesmos, retornará NULL.
• Se os pontos 2 e 3 forem exatamente antipodais, será retornado NULL.
• Se os pontos 2 e 1 forem exatamente antipodais, retornará NULL.
• Se alguma das regiões geográficas de entrada não for de pontos únicos ou for a região vazia, uma mensagem de erro será exibida.

Tipo de retorno

FLOAT64

Exemplo

WITH geos AS (
  SELECT 1 id, ST_GEOGPOINT(1, 0) geo1, ST_GEOGPOINT(0, 0) geo2, ST_GEOGPOINT(0, 1) geo3 UNION ALL
  SELECT 2 id, ST_GEOGPOINT(0, 0), ST_GEOGPOINT(1, 0), ST_GEOGPOINT(0, 1) UNION ALL
  SELECT 3 id, ST_GEOGPOINT(1, 0), ST_GEOGPOINT(0, 0), ST_GEOGPOINT(1, 0) UNION ALL
  SELECT 4 id, ST_GEOGPOINT(1, 0) geo1, ST_GEOGPOINT(0, 0) geo2, ST_GEOGPOINT(0, 0) geo3 UNION ALL
  SELECT 5 id, ST_GEOGPOINT(0, 0), ST_GEOGPOINT(-30, 0), ST_GEOGPOINT(150, 0) UNION ALL
  SELECT 6 id, ST_GEOGPOINT(0, 0), NULL, NULL UNION ALL
  SELECT 7 id, NULL, ST_GEOGPOINT(0, 0), NULL UNION ALL
  SELECT 8 id, NULL, NULL, ST_GEOGPOINT(0, 0))
SELECT ST_ANGLE(geo1,geo2,geo3) AS angle FROM geos ORDER BY id;

+---------------------+
| angle               |
+---------------------+
| 4.71238898038469    |
| 0.78547432161873854 |
| 0                   |
| NULL                |
| NULL                |
| NULL                |
| NULL                |
| NULL                |
+---------------------+

ST_AREA

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, retornará zero. Se geography_expression for uma coleção, retorna a área dos polígonos nela; se a coleção não contiver polígonos, retornará zero.

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

No momento, o parâmetro use_spheroid é compatível apenas com o valor FALSE. O valor padrão de use_spheroid é FALSE.

Tipo de retorno

FLOAT64

ST_ASBINARY

ST_ASBINARY(geography_expression)

Descrição

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

Consulte ST_GEOGFROMWKB para construir um GEOGRAPHY a partir de WKB.

Tipo de retorno

BYTES

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 GoogleSQL tem bordas geodésicas esféricas, enquanto um objeto Geometry GeoJSON explicitamente tem bordas planas. Para fazer uma conversão entre esses dois tipos de bordas, o GoogleSQL adiciona pontos à linha conforme necessário, de modo que a sequência de bordas resultante permaneça no máximo a 10 metros da borda original.

Consulte ST_GEOGFROMGEOJSON para construir um GEOGRAPHY a partir de GeoJSON.

Tipo de retorno

STRING

ST_ASTEXT

ST_ASTEXT(geography_expression)

Descrição

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

Consulte ST_GEOGFROMTEXT para construir um GEOGRAPHY a partir de WKT.

Tipo de retorno

STRING

ST_AZIMUTH

ST_AZIMUTH(point_geography_1, point_geography_2)

Descrição

Toma dois valores GEOGRAPHY de ponto e retorna o azimute do segmento de linha formado pelos pontos 1 e 2. O azimute é o ângulo em radianos medidos entre a linha desde o ponto 1 voltado para o norte verdadeiro até o segmento da linha do ponto 1 até o ponto 2.

O ângulo positivo é medido no sentido horário na superfície de uma esfera. Por exemplo, o azimute para um segmento de linha:

• Apontar para o norte é 0
• Apontar para o leste é PI/2
• Apontar para o sul é PI
• Apontar para o oeste é 3PI/2

ST_AZIMUTH tem os seguintes casos extremos:

• Se os dois pontos de entrada forem os mesmos, retorna NULL.
• Se os dois pontos de entrada forem exatamente antipodais, retornará NULL.
• Se uma das regiões geográficas de entrada não for de pontos únicos ou for a região vazia, uma mensagem de erro será exibida.

Tipo de retorno

FLOAT64

Exemplo

WITH geos AS (
  SELECT 1 id, ST_GEOGPOINT(1, 0) AS geo1, ST_GEOGPOINT(0, 0) AS geo2 UNION ALL
  SELECT 2, ST_GEOGPOINT(0, 0), ST_GEOGPOINT(1, 0) UNION ALL
  SELECT 3, ST_GEOGPOINT(0, 0), ST_GEOGPOINT(0, 1) UNION ALL
  -- identical
  SELECT 4, ST_GEOGPOINT(0, 0), ST_GEOGPOINT(0, 0) UNION ALL
  -- antipode
  SELECT 5, ST_GEOGPOINT(-30, 0), ST_GEOGPOINT(150, 0) UNION ALL
  -- nulls
  SELECT 6, ST_GEOGPOINT(0, 0), NULL UNION ALL
  SELECT 7, NULL, ST_GEOGPOINT(0, 0))
SELECT ST_AZIMUTH(geo1, geo2) AS azimuth FROM geos ORDER BY id;

+--------------------+
| azimuth            |
+--------------------+
| 4.71238898038469   |
| 1.5707963267948966 |
| 0                  |
| NULL               |
| NULL               |
| NULL               |
| NULL               |
+--------------------+

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_BOUNDINGBOX

ST_BOUNDINGBOX(geography_expression)

Descrição

Retorna um STRUCT que representa a caixa delimitadora para a região geográfica especificada. A caixa delimitadora é o retângulo mínimo que delimita a região geográfica. As bordas do retângulo seguem linhas constantes de longitude e latitude.

Advertências:

• Retornará NULL se a entrada for NULL ou uma região geográfica vazia.
• A caixa delimitadora poderá cruzar o antimeridiano se isso permitir um retângulo menor. Nesse caso, a caixa delimitadora tem um dos limites longitudinais fora do intervalo [-180, 180], de modo que xmin é menor que o valor mais a leste xmax.

Tipo de retorno

STRUCT<xmin FLOAT64, ymin FLOAT64, xmax FLOAT64, ymax FLOAT64>

Partes da caixa delimitadora:

• xmin: a linha de longitude constante mais ocidental que delimita o retângulo.
• xmax: a linha de longitude constante mais oriental que delimita o retângulo.
• ymin: a linha de latitude constante mínima que delimita o retângulo.
• ymax: a linha de latitude constante máxima que delimita o retângulo.

Exemplo

WITH data AS (
  SELECT 1 id, ST_GEOGFROMTEXT('POLYGON((-125 48, -124 46, -117 46, -117 49, -125 48))') g
  UNION ALL
  SELECT 2 id, ST_GEOGFROMTEXT('POLYGON((172 53, -130 55, -141 70, 172 53))') g
  UNION ALL
  SELECT 3 id, ST_GEOGFROMTEXT('POINT EMPTY') g
  UNION ALL
  SELECT 4 id, ST_GEOGFROMTEXT('POLYGON((172 53, -141 70, -130 55, 172 53))', oriented => TRUE)
)
SELECT id, ST_BOUNDINGBOX(g) AS box
FROM data

+----+------------------------------------------+
| id | box                                      |
+----+------------------------------------------+
| 1  | {xmin:-125, ymin:46, xmax:-117, ymax:49} |
| 2  | {xmin:172, ymin:53, xmax:230, ymax:70}   |
| 3  | NULL                                     |
| 4  | {xmin:-180, ymin:-90, xmax:180, ymax:90} |
+----+------------------------------------------+

Consulte ST_EXTENT para a versão agregada de ST_BOUNDINGBOX.

ST_BUFFER

Visualizar

Este produto ou recurso é coberto pelos Termos de ofertas pré-GA dos Termos de Serviço do Google Cloud Platform. Os produtos e recursos pré-GA podem ter suporte limitado, e as mudanças realizadas neles podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as descrições da fase de lançamento.

ST_BUFFER(
    geography,
    buffer_radius
    [, num_seg_quarter_circle => num_segments]
    [, use_spheroid => boolean_expression]
    [, endcap => endcap_style]
    [, side => line_side])

Descrição

Retorna uma GEOGRAPHY que representa o buffer ao redor da GEOGRAPHY de entrada. Essa função é semelhante a ST_BUFFERWITHTOLERANCE, mas você especifica o número de segmentos em vez de fornecer tolerância para determinar o quanto a região geográfica resultante pode desviar do raio do buffer ideal.

• geography: a entrada GEOGRAPHY para circular com o raio do buffer.
• buffer_radius: DOUBLE que representa o raio do buffer em torno da região geográfica de entrada. O raio é em metros. Os polígonos contraem quando são armazenados em buffer com um buffer_radius negativo. Os shells de polígono e os buracos que são contratados para um ponto são descartados.
• num_seg_quarter_circle: (opcional) DOUBLE especifica o número de segmentos usados para aproximar um quarto de círculo. O valor padrão é 8.0. A nomeação desse argumento é opcional.
• endcap: (opcional) STRING permite especificar um dos dois estilos de extremidade: ROUND e FLAT. O valor padrão é ROUND. Essa opção afeta apenas as extremidades das cadeias de linha em buffer.
• side: (opcional) STRING permite especificar uma das três possibilidades de linhas: BOTH, LEFT e RIGHT. O padrão é BOTH. Essa opção afeta apenas o modo como as cadeias de linhas são armazenadas em buffer.
• use_spheroid: (opcional) BOOL determina como essa função mede a distância. Se use_spheroid for FALSE, a função mede a distância na superfície de uma esfera perfeita. No momento, o parâmetro use_spheroid é compatível apenas com o valor FALSE. O valor padrão de use_spheroid é FALSE.

Tipo de retorno

GEOGRAPHY do polígono

Exemplo

O exemplo a seguir mostra o resultado de ST_BUFFER em um ponto. Um ponto armazenado em buffer é um círculo aproximado. Quando num_seg_quarter_circle = 2, haverá dois segmentos de linhas em um quarto de círculo. Portanto, o círculo em buffer terá oito lados e ST_NUMPOINTS retornará nove vértices. Quando num_seg_quarter_circle = 8, haverá oito segmentos de linhas em um quarto de círculo. Portanto, o círculo em buffer terá 32 lados e ST_NUMPOINTS retornará 33 vértices.

SELECT
  -- num_seg_quarter_circle=2
  ST_NUMPOINTS(ST_BUFFER(ST_GEOGFROMTEXT('POINT(1 2)'), 50, 2)) AS eight_sides,
  -- num_seg_quarter_circle=8, since 8 is the default
  ST_NUMPOINTS(ST_BUFFER(ST_GEOGFROMTEXT('POINT(100 2)'), 50)) AS thirty_two_sides;

+-------------+------------------+
| eight_sides | thirty_two_sides |
+-------------+------------------+
| 9           | 33               |
+-------------+------------------+

ST_BUFFERWITHTOLERANCE

Visualizar

Este produto ou recurso é coberto pelos Termos de ofertas pré-GA dos Termos de Serviço do Google Cloud Platform. Os produtos e recursos pré-GA podem ter suporte limitado, e as mudanças realizadas neles podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as descrições da fase de lançamento.

ST_BUFFERWITHTOLERANCE(
    geography,
    buffer_radius,
    tolerance_meters => tolernace
    [, use_spheroid => boolean_expression]
    [, endcap => endcap_style]
    [, side => line_side])

Retorna uma GEOGRAPHY que representa o buffer ao redor da GEOGRAPHY de entrada. Essa função é semelhante a ST_BUFFER, mas você fornece tolerância em vez de segmentos para determinar o quanto a geografia resultante pode desviar do raio de buffer ideal.

• geography: a entrada GEOGRAPHY para circular com o raio do buffer.
• buffer_radius: DOUBLE que representa o raio do buffer em torno da região geográfica de entrada. O raio é em metros. Os polígonos contraem quando são armazenados em buffer com um buffer_radius negativo. Shells poligonais e buracos contraídos para um ponto são descartados.
• tolerance_meters: DOUBLE especifica uma tolerância em metros com a forma aproximada. A tolerância determina o quanto um polígono pode desviar do raio ideal. A nomeação desse argumento é opcional.
• endcap: (opcional) STRING permite especificar um dos dois estilos de extremidade: ROUND e FLAT. O valor padrão é ROUND. Essa opção afeta apenas as extremidades das cadeias de linha em buffer.
• side: (opcional) STRING permite especificar um dos três estilos de linha possíveis: BOTH, LEFT e RIGHT. O padrão é BOTH. Essa opção afeta apenas as extremidades das cadeias de linha em buffer.
• use_spheroid: (opcional) BOOL determina como essa função mede a distância. Se use_spheroid for FALSE, a função mede a distância na superfície de uma esfera perfeita. No momento, o parâmetro use_spheroid é compatível apenas com o valor FALSE. O valor padrão de use_spheroid é FALSE.

Tipo de retorno

GEOGRAPHY do polígono

Exemplo

O exemplo a seguir mostra os resultados de ST_BUFFERWITHTOLERANCE em um ponto, considerando dois valores diferentes de tolerância, mas com o mesmo raio de buffer de 100. Um ponto em buffer é um círculo aproximado. Quando tolerance_meters=25, a tolerância é uma grande porcentagem do raio do buffer. Portanto, apenas cinco segmentos são usados para aproximar um círculo em torno do ponto de entrada. Quando tolerance_meters=1, a tolerância é uma porcentagem muito menor do raio do buffer. Portanto, 24 bordas são usadas para aproximar um círculo em torno do ponto de entrada.

SELECT
  -- tolerance_meters=25, or 25% of the buffer radius.
  ST_NumPoints(ST_BUFFERWITHTOLERANCE(ST_GEOGFROMTEXT('POINT(1 2)'), 100, 25)) AS five_sides,
  -- tolerance_meters=1, or 1% of the buffer radius.
  st_NumPoints(ST_BUFFERWITHTOLERANCE(ST_GEOGFROMTEXT('POINT(100 2)'), 100, 1)) AS twenty_four_sides;

+------------+-------------------+
| five_sides | twenty_four_sides |
+------------+-------------------+
| 6          | 24                |
+------------+-------------------+

ST_CENTROID_AGG

ST_CENTROID_AGG(geography)

Descrição

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

O centroide sobre o conjunto de GEOGRAPHYs de entrada é a média ponderada do centroide de cada indivíduo GEOGRAPHY. Apenas as GEOGRAPHYs com a dimensão mais alta presente 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 das GEOGRAPHYs com linhas, desde que elas tenham dimensão máxima. Neste exemplo, ST_CENTROID_AGG ignora as GEOGRAPHYs apenas com pontos ao calcular o centroide agregado.

ST_CENTROID_AGG ignora valores GEOGRAPHY de entrada NULL.

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

Ponto 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 é equivalente 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)      |
+-----------------+

ST_CENTROID

ST_CENTROID(geography_expression)

Descrição

Retorna o centroide da entrada GEOGRAPHY como um ponto GEOGRAPHY único.

O centroide de uma GEOGRAPHY é a média ponderada dos centroides dos componentes de maior dimensão da GEOGRAPHY. O centroide dos 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 a GEOGRAPHY de entrada estiver vazia, uma GEOGRAPHY vazia será retornada.

Restrições

No caso improvável de o centroide de uma 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

Ponto GEOGRAPHY

ST_CLOSESTPOINT

ST_CLOSESTPOINT(geography_1, geography_2[, use_spheroid])

Descrição

Retorna um GEOGRAPHY contendo 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 uma das GEOGRAPHYs de entrada estiver vazia, ST_CLOSESTPOINT retornará NULL.

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

No momento, o parâmetro use_spheroid é compatível apenas com o valor FALSE. O valor padrão de use_spheroid é FALSE.

Tipo de retorno

Ponto GEOGRAPHY

ST_CLUSTERDBSCAN

ST_CLUSTERDBSCAN(geography_column, epsilon, minimum_geographies)
OVER over_clause

over_clause:
  { named_window | ( [ window_specification ] ) }

window_specification:
  [ named_window ]
  [ PARTITION BY partition_expression [, ...] ]
  [ ORDER BY expression [ { ASC | DESC }  ] [, ...] ]

Executa o clustering DBSCAN (em inglês) em uma coluna de regiões geográficas. Retorna o número de um cluster baseado em zero.

Para saber mais sobre a cláusula OVER e como usá-la, consulte Chamadas de função Window.

Parâmetros de entrada

• geography_column: uma coluna de GEOGRAPHYs que é clusterizada.
• epsilon: o epsilon que especifica o raio, medido em metros, em torno de um valor principal. Valor FLOAT64 não negativo.
• minimum_geographies: especifica o número mínimo de regiões geográficas em um único cluster. Somente a entrada densa forma um cluster. Caso contrário, ela é classificada como ruído. Valor INT64 não negativo.

Tipos de geografia e algoritmo DBSCAN

O algoritmo DBSCAN identifica clusters de dados de alta densidade e marca outliers em áreas de ruído de baixa densidade. As regiões geográficas transmitidas por geography_column são classificadas em uma das três maneiras pelo algoritmo DBSCAN:

• Valor principal: uma região geográfica será um valor principal se estiver dentro de uma distância de epsilon das regiões minimum_geographies, incluindo ela mesma. O valor principal inicia um novo cluster ou é adicionado ao mesmo cluster como um valor principal dentro da distância de epsilon. Os valores principais são agrupados em um cluster com todos os outros valores principais e de borda que estão a uma distância de epsilon.
• Valor da borda: uma região geográfica é um valor de borda, se ele estiver a uma distância epsilon de um valor principal. Ela é adicionada ao mesmo cluster como um valor principal dentro de uma distância de epsilon. Um valor de borda pode estar dentro de uma distância de epsilon de mais de um cluster. Nesse caso, ela pode ser atribuída arbitrariamente a um cluster, e a função produzirá o mesmo resultado nas chamadas subsequentes.
• Ruído: uma geografia é um ruído se não for um valor principal nem de borda. Os valores de ruído são atribuídos a um cluster NULL. Um GEOGRAPHY vazio é sempre classificado como ruído.

Restrições

• O argumento minimum_geographies é um INT64 não negativo e epsilon é um FLOAT64 não negativo.
• Uma região geográfica vazia não pode participar de nenhum cluster.
• Várias atribuições de clustering podem ser possíveis para um valor de borda. Se uma região geográfica for um valor de borda, ST_CLUSTERDBSCAN o atribuirá a um cluster válido arbitrário.

Tipo de retorno

INT64 para cada região geográfica na coluna geográfica.

Exemplos

Este exemplo realiza o clustering DBSCAN com um raio de 100.000 metros com um argumento minimum_geographies de 1. As regiões geográficas que estão sendo analisadas são uma mistura de pontos, linhas e polígonos.

WITH Geos as
  (SELECT 1 as row_id, ST_GEOGFROMTEXT('POINT EMPTY') as geo UNION ALL
    SELECT 2, ST_GEOGFROMTEXT('MULTIPOINT(1 1, 2 2, 4 4, 5 2)') UNION ALL
    SELECT 3, ST_GEOGFROMTEXT('POINT(14 15)') UNION ALL
    SELECT 4, ST_GEOGFROMTEXT('LINESTRING(40 1, 42 34, 44 39)') UNION ALL
    SELECT 5, ST_GEOGFROMTEXT('POLYGON((40 2, 40 1, 41 2, 40 2))'))
SELECT row_id, geo, ST_CLUSTERDBSCAN(geo, 1e5, 1) OVER () AS cluster_num FROM
Geos ORDER BY row_id

+--------+-----------------------------------+-------------+
| row_id |                geo                | cluster_num |
+--------+-----------------------------------+-------------+
|1       | GEOMETRYCOLLECTION EMPTY          |NULL         |
|2       | MULTIPOINT(1 1, 2 2, 5 2, 4 4)    |0            |
|3       | POINT(14 15)                      |1            |
|4       | LINESTRING(40 1, 42 34, 44 39)    |2            |
|5       | POLYGON((40 2, 40 1, 41 2, 40 2)) |2            |
+--------+-----------------------------------+-------------+

ST_CONTAINS

ST_CONTAINS(geography_1, geography_2)

Descrição

Retorna TRUE se nenhum ponto de geography_2 está fora de geography_1, e os interiores se cruzam; retorna FALSE caso contrário.

OBSERVAÇÃO: um GEOGRAPHY não contém seu 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 cada um dos três 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_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_CONVEXHULL

ST_CONVEXHULL(geography_expression)

Descrição

Retorna o envoltório convexo da entrada GEOGRAPHY. O envoltório convexo é a menor GEOGRAPHY que cobre a entrada. Uma GEOGRAPHY será convexa se para cada par de pontos na GEOGRAPHY, a aresta geodésica que conecta os pontos também estiver contida na mesma GEOGRAPHY.

Na maioria dos casos, o envoltório convexo consiste em um único polígono. Os casos de borda notáveis incluem:

• O envoltório convexo de um único ponto também é um ponto.
• A envoltório convexo de dois ou mais pontos colineares é uma cadeia de linhas, desde que essa cadeia de linhas seja convexa.
• Se o GEOGRAPHY de entrada se estender por mais de um hemisfério, o envoltório convexo será o globo inteiro. Isso inclui qualquer entrada que contenha um par de pontos antipodais.
• ST_CONVEXHULL retornará NULL se a entrada for NULL ou a GEOGRAPHY vazia.

Tipo de retorno

GEOGRAPHY

Exemplos

O envoltório convexo retornado por ST_CONVEXHULL pode ser um ponto, uma cadeia de linhas ou um polígono, dependendo da entrada.

WITH Geographies AS
 (SELECT ST_GEOGFROMTEXT('POINT(1 1)') AS g UNION ALL
  SELECT ST_GEOGFROMTEXT('LINESTRING(1 1, 2 2)') AS g UNION ALL
  SELECT ST_GEOGFROMTEXT('MULTIPOINT(2 11, 4 12, 0 15, 1 9, 1 12)') AS g)
SELECT
  g AS input_geography,
  ST_CONVEXHULL(g) AS convex_hull
FROM Geographies;

+-----------------------------------------+--------------------------------------------------------+
|             input_geography             |                      convex_hull                       |
+-----------------------------------------+--------------------------------------------------------+
| POINT(1 1)                              | POINT(0.999999999999943 1)                             |
| LINESTRING(1 1, 2 2)                    | LINESTRING(2 2, 1.49988573656168 1.5000570914792, 1 1) |
| MULTIPOINT(1 9, 4 12, 2 11, 1 12, 0 15) | POLYGON((1 9, 4 12, 0 15, 1 9))                        |
+-----------------------------------------+--------------------------------------------------------+

ST_COVEREDBY

ST_COVEREDBY(geography_1, geography_2)

Descrição

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

Dado 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

Retorna FALSE se geography_1 ou geography_2 estiver vazio. Retorna 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)) abrange cada um dos três pontos (0, 0), (1, 1) e (10, 10), que ficam 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_DIFFERENCE

ST_DIFFERENCE(geography_1, geography_2)

Descrição

Retorna um GEOGRAPHY que representa a diferença do conjunto de pontos de geography_1 e geography_2. Portanto, o resultado consiste na parte de geography_1 que não se cruza com geography_2.

Se geometry_1 for completamente contido em geometry_2, então ST_DIFFERENCE retornará um GEOGRAPHY vazio.

Restrições

Os objetos geométricos subjacentes representados por um GEOGRAPHY do GoogleSQL correspondem a um conjunto de pontos fechados. Portanto, ST_DIFFERENCE é a interdição da diferença do conjunto de pontos de geography_1 e geography_2. Isso significa que se geography_1 e geography_2 se cruzam, uma parte do limite de geography_2 pode estar na diferença.

Tipo de retorno

GEOGRAPHY

Exemplo

A consulta a seguir ilustra a diferença entre geog1, um polígono maior POLYGON((0 0, 10 0, 10 10, 0 0)) e geog1, um polígono menor POLYGON((4 2, 6 2, 8 6, 4 2)) que cruza com geog1. O resultado é geog1 com um buraco onde geog2 se cruza com ele.

SELECT
  ST_DIFFERENCE(
      ST_GEOGFROMTEXT('POLYGON((0 0, 10 0, 10 10, 0 0))'),
      ST_GEOGFROMTEXT('POLYGON((4 2, 6 2, 8 6, 4 2))')
  );

+--------------------------------------------------------+
| difference_of_geog1_and_geog2                          |
+--------------------------------------------------------+
| POLYGON((0 0, 10 0, 10 10, 0 0), (8 6, 6 2, 4 2, 8 6)) |
+--------------------------------------------------------+

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 a entrada GEOGRAPHY estiver vazia, ST_DIMENSION retornará -1.

Tipo de retorno

INT64

ST_DISJOINT

ST_DISJOINT(geography_1, geography_2)

Descrição

Retorna TRUE se o cruzamento de geography_1 e geography_2 estiver vazio, ou seja, nenhum ponto em geography_1 também aparece em geography_2.

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

Tipo de retorno

BOOL

ST_DISTANCE

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 use_spheroid opcional determina como esta função mede a distância. Se use_spheroid for FALSE, a função mede a distância na superfície de uma esfera perfeita.

No momento, o parâmetro use_spheroid é compatível apenas com o valor FALSE. O valor padrão de use_spheroid é FALSE.

Tipo de retorno

FLOAT64

ST_DUMP

ST_DUMP(geography[, dimension])

Descrição

Retorna um ARRAY de GEOGRAPHYs simples, em que cada elemento é um componente da entrada GEOGRAPHY. Um GEOGRAPHY simples consiste em um único ponto, uma cadeia de linhas ou um polígono. Se a entrada GEOGRAPHY for simples, o resultado será um único elemento. Quando a entrada GEOGRAPHY for uma coleção, ST_DUMP retorna uma ARRAY com uma GEOGRAPHY simples para cada componente da coleção.

Se dimension for fornecida, a função só retornará GEOGRAPHYs da dimensão correspondente. Uma dimensão de -1 equivale a omitir dimension.

Tipo de retorno

ARRAY<GEOGRAPHY>

Exemplos

O exemplo a seguir mostra como ST_DUMP retorna as regiões geográficas simples dentro de uma região geográfica complexa.

WITH example AS (
  SELECT ST_GEOGFROMTEXT('POINT(0 0)') AS geography
  UNION ALL
  SELECT ST_GEOGFROMTEXT('MULTIPOINT(0 0, 1 1)') AS geography
  UNION ALL
  SELECT ST_GEOGFROMTEXT('GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(1 2, 2 1))'))
SELECT
  geography AS original_geography,
  ST_DUMP(geography) AS dumped_geographies
FROM example

+-------------------------------------+------------------------------------+
|         original_geographies        |      dumped_geographies            |
+-------------------------------------+------------------------------------+
| POINT(0 0)                          | [POINT(0 0)]                       |
| MULTIPOINT(0 0, 1 1)                | [POINT(0 0), POINT(1 1)]           |
| GEOMETRYCOLLECTION(POINT(0 0),      | [POINT(0 0), LINESTRING(1 2, 2 1)] |
|   LINESTRING(1 2, 2 1))             |                                    |
+-------------------------------------+------------------------------------+

O exemplo a seguir mostra como ST_DUMP com o argumento de dimensão retorna apenas regiões geográficas simples da dimensão especificada.

WITH example AS (
  SELECT ST_GEOGFROMTEXT('GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(1 2, 2 1))') AS geography)
SELECT
  geography AS original_geography,
  ST_DUMP(geography, 1) AS dumped_geographies
FROM example

+-------------------------------------+------------------------------+
|         original_geographies        |      dumped_geographies      |
+-------------------------------------+------------------------------+
| GEOMETRYCOLLECTION(POINT(0 0),      | [LINESTRING(1 2, 2 1)]       |
|   LINESTRING(1 2, 2 1))             |                              |
+-------------------------------------+------------------------------+

ST_DWITHIN

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

Descrição

Retorna TRUE se a distância entre pelo menos um ponto geography_1 e um ponto em geography_2 é menor ou igual à distância fornecida pelo argumento distance; caso contrário, retorna FALSE. Se a entrada GEOGRAPHY estiver vazia, ST_DWithin retornará FALSE. O distance especificado está em metros na superfície da Terra.

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

No momento, o parâmetro use_spheroid é compatível apenas com o valor FALSE. O valor padrão de use_spheroid é FALSE.

Tipo de retorno

BOOL

ST_ENDPOINT

ST_ENDPOINT(linestring_geography)

Descrição

Retorna o último ponto de uma região geográfica de linestring como uma região geográfica de pontos. Retorna um erro se a entrada não for uma linestring ou se estiver vazia. Use o prefixo SAFE para receber NULL para entrada inválida em vez de um erro.

Tipo de retorno

Ponto GEOGRAPHY

Exemplo

SELECT ST_ENDPOINT(ST_GEOGFROMTEXT('LINESTRING(1 1, 2 1, 3 2, 3 3)')) last

+--------------+
| last         |
+--------------+
| POINT(3 3)   |
+--------------+

ST_EQUALS

ST_EQUALS(geography_1, geography_2)

Descrição

Retorna TRUE se geography_1 e geography_2 representarem o mesmo

valor 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_EXTENT

ST_EXTENT(geography_expression)

Descrição

Retorna um STRUCT que representa a caixa delimitadora para o conjunto de valores de entrada GEOGRAPHY. A caixa delimitadora é o retângulo mínimo que delimita a região geográfica. As bordas do retângulo seguem linhas constantes de longitude e latitude.

Advertências:

• Retorna NULL se todas as entradas forem NULL ou regiões geográficas vazias.
• A caixa delimitadora poderá cruzar o antimeridiano se isso permitir um retângulo menor. Nesse caso, a caixa delimitadora tem um dos limites longitudinais fora do intervalo [-180, 180], de modo que xmin é menor que o valor mais a leste xmax.
• Se o período de longitude da caixa delimitadora for maior ou igual a 180 graus, a função retornará a caixa delimitadora com o intervalo de longitude de [-180, 180].

Tipo de retorno

STRUCT<xmin FLOAT64, ymin FLOAT64, xmax FLOAT64, ymax FLOAT64>

Partes da caixa delimitadora:

• xmin: a linha de longitude constante mais ocidental que delimita o retângulo.
• xmax: a linha de longitude constante mais oriental que delimita o retângulo.
• ymin: a linha de latitude constante mínima que delimita o retângulo.
• ymax: a linha de latitude constante máxima que delimita o retângulo.

Exemplo

WITH data AS (
  SELECT 1 id, ST_GEOGFROMTEXT('POLYGON((-125 48, -124 46, -117 46, -117 49, -125 48))') g
  UNION ALL
  SELECT 2 id, ST_GEOGFROMTEXT('POLYGON((172 53, -130 55, -141 70, 172 53))') g
  UNION ALL
  SELECT 3 id, ST_GEOGFROMTEXT('POINT EMPTY') g
)
SELECT ST_EXTENT(g) AS box
FROM data

+----------------------------------------------+
| box                                          |
+----------------------------------------------+
| {xmin:172, ymin:46, xmax:243, ymax:70}       |
+----------------------------------------------+

Consulte ST_BOUNDINGBOX para a versão não agregada de ST_EXTENT.

ST_EXTERIORRING

ST_EXTERIORRING(polygon_geography)

Descrição

Retorna uma geografia de cadeia de linha que corresponde ao anel mais externo de uma região geográfica poligonal.

• Se a geografia de entrada for um polígono, receberá o anel mais externo da geografia do polígono e retornará a cadeia de linhas correspondente.
• Se a entrada for a GEOGRAPHY completa, retornará uma região geográfica vazia.
• Retorna um erro se a entrada não for um único polígono.

Use o prefixo SAFE para receber NULL para entrada inválida, em vez de um erro.

Tipo de retorno

• GEOGRAPHY de cadeia de linhas
• Esvaziar GEOGRAPHY

Exemplos

WITH geo as
 (SELECT ST_GEOGFROMTEXT('POLYGON((0 0, 1 4, 2 2, 0 0))') AS g UNION ALL
  SELECT ST_GEOGFROMTEXT('''POLYGON((1 1, 1 10, 5 10, 5 1, 1 1),
                                  (2 2, 3 4, 2 4, 2 2))''') as g)
SELECT ST_EXTERIORRING(g) AS ring FROM geo;

+---------------------------------------+
| ring                                  |
+---------------------------------------+
| LINESTRING(2 2, 1 4, 0 0, 2 2)        |
| LINESTRING(5 1, 5 10, 1 10, 1 1, 5 1) |
+---------------------------------------+

ST_GEOGFROM

ST_GEOGFROM(expression)

Descrição

Converte uma expressão de um valor STRING ou BYTES em um valor GEOGRAPHY.

Se expression representar um valor STRING, ele precisará ser uma representação GEOGRAPHY válida em um dos seguintes formatos:

• Formato WKT. Para saber mais sobre esse formato e os requisitos para usá-lo, consulte ST_GEOGFROMTEXT.
• WKB em formato de texto hexadecimal. Para saber mais sobre esse formato e os requisitos para usá-lo, consulte ST_GEOGFROMWKB.
• Formato GeoJSON. Para saber mais sobre esse formato e os requisitos para usá-lo, consulte ST_GEOGFROMGEOJSON.

Se expression representar um valor BYTES, ele precisará ser uma expressão binária GEOGRAPHY válida no formato WKB. Para saber mais sobre esse formato e os requisitos para usá-lo, consulte ST_GEOGFROMWKB.

Se expression for NULL, a saída será NULL.

Tipo de retorno

GEOGRAPHY

Exemplos

Isso usa uma string formatada em WKT e retorna um polígono GEOGRAPHY:

SELECT ST_GEOGFROM('POLYGON((0 0, 0 2, 2 2, 2 0, 0 0))') AS WKT_format

+------------------------------------+
| WKT_format                         |
+------------------------------------+
| POLYGON((2 0, 2 2, 0 2, 0 0, 2 0)) |
+------------------------------------+

Isso usa uma string codificada em hexadecimal WKB e retorna um ponto GEOGRAPHY:

SELECT ST_GEOGFROM(FROM_HEX('010100000000000000000000400000000000001040')) AS WKB_format

+----------------+
| WKB_format     |
+----------------+
| POINT(2 4)     |
+----------------+

Isso usa bytes formatados em WKB e retorna um ponto GEOGRAPHY:

SELECT ST_GEOGFROM('010100000000000000000000400000000000001040')-AS WKB_format

+----------------+
| WKB_format     |
+----------------+
| POINT(2 4)     |
+----------------+

Ele usa uma string formatada em GEOJSON e retorna um polígono de GEOGRAPHY:

SELECT ST_GEOGFROM(
  '{ "type": "Polygon", "coordinates": [ [ [2, 0], [2, 2], [1, 2], [0, 2], [0, 0], [2, 0] ] ] }'
) AS GEOJSON_format

+-----------------------------------------+
| GEOJSON_format                          |
+-----------------------------------------+
| POLYGON((2 0, 2 2, 1 2, 0 2, 0 0, 2 0)) |
+-----------------------------------------+

ST_GEOGFROMGEOJSON

ST_GEOGFROMGEOJSON(geojson_string [, make_valid => constant_expression])

Descrição

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

ST_GEOGFROMGEOJSON aceita entrada em conformidade com o RFC 7946.

Se o parâmetro make_valid estiver definido como TRUE, a função tentará reparar polígonos que não estejam em conformidade com a semântica de Open Geospatial Consortium. Este parâmetro usa a sintaxe de argumento nomeada e deve ser especificado com a sintaxe make_valid => argument_value.

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

Consulte ST_ASGEOJSON para formatar um GEOGRAPHY como GeoJSON.

Restrições

A entrada JSON 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 de 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 um erro.
• Uma posição no membro coordinates de um tipo de geometria GeoJSON precisa consistir em exatamente dois elementos. O primeiro é longitude e o segundo é latitude. Portanto, ST_GEOGFROMGEOJSON não é compatível com o terceiro elemento opcional para uma posição no membro coordinates.

Tipo de retorno

GEOGRAPHY

ST_GEOGFROMTEXT

• Assinatura 1
• Assinatura 2

Assinatura 1

ST_GEOGFROMTEXT(wkt_string[, oriented])

Descrição

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

Esta função é compatível com um parâmetro opcional do tipo BOOL, oriented. Se esse parâmetro for definido como TRUE, todos os polígonos na entrada serão orientados da seguinte maneira: se alguém caminhar ao longo do limite do polígono na ordem dos vértices de entrada, o interior do polígono estará à esquerda. Isso permite que 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 ler dados em uma projeção plana, considere usar ST_GEOGFROMGEOJSON. Para mais informações sobre as diferenças entre geodésicas esféricas e linhas planas, consulte Limites e sistemas coordenados.
• A função não é compatível com geometrias tridimensionais que têm um sufixo Z, nem são compatíveis com geometrias do sistema de referência linear com um sufixo M.
• A função suporta apenas primitivas geométricas e geometrias de várias partes. Especificamente, ela é compatível apenas com Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon e GeometryCollection.

Tipo de retorno

GEOGRAPHY

Exemplo

A consulta a seguir lê a string WKT POLYGON((0 0, 0 2, 2 2, 2 0, 0 0)) 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     |
+-------------------+---------------+-----------+

Assinatura 2

ST_GEOGFROMTEXT(wkt_string[, oriented => boolean_constant_1]
    [, planar => boolean_constant_2] [, make_valid => boolean_constant_3])

Descrição

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

Esta função é compatível com três parâmetros opcionais do tipo BOOL: oriented, planar e make_valid. Essa assinatura usa a sintaxe de argumentos nomeados, e os parâmetros precisam ser especificados usando a sintaxe parameter_name => parameter_value, em qualquer ordem.

Se o parâmetro oriented estiver definido como TRUE, todos os polígonos na entrada serão orientados da seguinte maneira: se alguém caminhar ao longo do limite do polígono na ordem dos vértices de entrada, o interior do polígono ficará à esquerda. Isso permite que 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.

Se o parâmetro planar estiver definido como TRUE, as bordas das strings de linha e dos polígonos usam a semântica de mapa plana em vez da semântica padrão de geodésicas esféricas do GoogleSQL. Para mais informações sobre as diferenças entre geodésicas esféricas e linhas planas, consulte Bordas e sistemas coordenados.

Se o parâmetro make_valid estiver definido como TRUE, a função tentará reparar polígonos que não estejam em conformidade com a semântica de Open Geospatial Consortium.

Para formatar GEOGRAPHY como WKT, use ST_ASTEXT.

Restrições

• Todas as bordas de entrada são consideradas geodésicas esféricas por padrão e não linhas retas planas. Para ler dados em uma projeção plana, transmita o argumento planar => TRUE ou considere usar ST_GEOGFROMGEOJSON. Para mais informações sobre as diferenças entre geodésicas esféricas e linhas planas, consulte Bordas e sistemas coordenados.
• A funç