Funções geográficas

As funções geográficas operam em valores de GEOGRAPHY 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.

Todas as funções geográficas do BigQuery retornarão 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_DUMP
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_ISCOLLECTION
ST_ISEMPTY
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 BigQuery GEOGRAPHY tem bordas geodésicas esféricas, enquanto um objeto GeoJSON Geometry explicitamente tem bordas 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 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) geo1, st_geogpoint(0, 0) 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) geo1, st_geogpoint(0, 0) geo2 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 ver a versão agregada de ST_BOUNDINGBOX.

ST_BUFFER

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

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

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

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

ST_CENTROID(geography_expression)

Descrição

Retorna o centroide da entrada GEOGRAPHY como um ponto GEOGRAPHY ú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_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 sobre o conjunto de entradas GEOGRAPHYs é a média ponderada do centroide de cada indivíduo GEOGRAPHY. Apenas os 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 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.

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 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 é 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 dimensão mais alta 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_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 um dos GEOGRAPHYs de entrada estiver vazio, 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

GEOGRAPHY

ST_CLUSTERDBSCAN

ST_CLUSTERDBSCAN(geography_column, epsilon, minimum_geographies) OVER (...)

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.

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.
  • OVER: especifica uma janela. Consulte Funções analíticas. O uso da cláusula OVER com ST_CLUSTERDBSCAN é compatível com o seguinte:

    • PARTITION BY: opcional.
    • ORDER BY: opcional.
    • window_frame_clause: não permitido

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 é o menor GEOGRAPHY que cobre a entrada. Uma GEOGRAPHY será convexa se para cada par de pontos na GEOGRAPHY, a extremidade 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 BigQuery 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

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 ver 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 leva 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 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 BigQuery GEOGRAPHY tem bordas geodésicas esféricas, enquanto um objeto GeoJSON Geometry explicitamente tem bordas 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 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

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 usarão a semântica de mapa plana em vez da semântica padrão de geodésicas esféricas do BigQuery. 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çã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.
  • oriented e planar não podem ser iguais a TRUE ao mesmo tempo.
  • oriented e make_valid não podem ser iguais a TRUE ao mesmo tempo.

Exemplo

A consulta a seguir lê a string WKT POLYGON((0 0, 0 2, 2 2, 0 2, 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, oriented => FALSE), ST_GEOGPOINT(1, 1)) AS non_oriented,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, oriented => TRUE),  ST_GEOGPOINT(1, 1)) AS oriented
FROM polygon;

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

A consulta a seguir converte uma string WKT com um polígono inválido em GEOGRAPHY. A string WKT viola duas propriedades de um polígono válido: o loop que descreve o polígono não é fechado e contém autointerseção. Com a opção make_valid, ST_GeogFromText o converte em um formato de vários polígonos.

WITH data AS (
  SELECT 'polygon((0 -1, 2 1, 2 -1, 0 1))' wkt)
SELECT
  SAFE.ST_GeogFromText(wkt) as geom,
  SAFE.ST_GeogFromText(wkt, make_valid => TRUE) as valid_geom
FROM data

+------+-----------------------------------------------------------------+
| geom | valid_geom                                                      |
+------+-----------------------------------------------------------------+
| NULL | MULTIPOLYGON(((0 -1, 1 0, 0 1, 0 -1)), ((1 0, 2 -1, 2 1, 1 0))) |
+------+-----------------------------------------------------------------+

ST_GEOGFROMWKB

ST_GEOGFROMWKB(wkb_bytes_expression)
ST_GEOGFROMWKB(wkb_hex_string_expression)

Descrição

Converte uma expressão para um valor de texto hexadecimal STRING ou BYTES em um valor GEOGRAPHY. A expressão precisa estar no formato WKB.

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 ler dados em uma projeção plana, considere usar ST_GEOGFROMGEOJSON.

Tipo de retorno

GEOGRAPHY

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_GEOGPOINTFROMGEOHASH

ST_GEOGPOINTFROMGEOHASH(geohash)

Descrição

Retorna um valor GEOGRAPHY que corresponde a um ponto no meio de uma caixa delimitadora definida no GeoHash.

Tipo de retorno

GEOGRAPHY

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.

Tipo de retorno

STRING

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   |
+--------------+

ST_GEOMETRYTYPE

ST_GEOMETRYTYPE(geography_expression)

Descrição

Retorna o tipo de geometria do Open Geospatial Consortium (OGC), que descreve a GEOGRAPHY de entrada como uma STRING. O tipo de geometria do OGC corresponde aos tipos usados nos formatos WKT e GeoJSON e impressos para ST_ASTEXT e ST_ASGEOJSON. ST_GEOMETRYTYPE retorna o tipo de geometria do OGC com o prefixo "ST_".

ST_GEOMETRYTYPE retorna o resultado a seguir, conforme o tipo na entrada:

  • Região geográfica de ponto único: retorna ST_Point.
  • Coleção de apenas pontos: retorna ST_MultiPoint.
  • Região geográfica de linestring única: retorna ST_LineString.
  • Coleção de apenas linestrings: retorna ST_MultiLineString.
  • Região geográfica de polígono único: retorna ST_Polygon.
  • Coleção de apenas polígonos: retorna ST_MultiPolygon.
  • Coleção com elementos de diferentes dimensões ou a entrada é a região geográfica vazia: retorna ST_GeometryCollection.

Tipo de retorno

STRING

Exemplo

O exemplo a seguir mostra como ST_GEOMETRYTYPE usa regiões geográficas e retorna os nomes dos tipos de geometria do OGC.

WITH example AS(
  SELECT ST_GeogFromText('POINT(0 1)') AS geography
  UNION ALL
  SELECT ST_GeogFromText('MULTILINESTRING((2 2, 3 4), (5 6, 7 7))')
  UNION ALL
  SELECT ST_GeogFromText('GEOMETRYCOLLECTION(MULTIPOINT(-1 2, 0 12), LINESTRING(-2 4, 0 6))')
  UNION ALL
  SELECT ST_GeogFromText('GEOMETRYCOLLECTION EMPTY'))
SELECT
  geography AS WKT,
  ST_GeometryType(geography) AS geometry_type_name
FROM example;

+-------------------------------------------------------------------+-----------------------+
| WKT                                                               | geometry_type_name    |
+-------------------------------------------------------------------+-----------------------+
| POINT(0 1)                                                        | ST_Point              |
| MULTILINESTRING((2 2, 3 4), (5 6, 7 7))                           | ST_MultiLineString    |
| GEOMETRYCOLLECTION(MULTIPOINT(-1 2, 0 12), LINESTRING(-2 4, 0 6)) | ST_GeometryCollection |
| GEOMETRYCOLLECTION EMPTY                                          | ST_GeometryCollection |
+-------------------------------------------------------------------+-----------------------+

ST_INTERIORRINGS

ST_INTERIORRINGS(polygon_geography)

Descrição

Retorna uma matriz de geografias de cadeia de linhas que corresponde aos anéis internos de uma geografia do polígono. Cada anel interno é a borda de um buraco dentro do polígono de entrada.

  • Se a geografia de entrada for um polígono, exclui o anel mais externo da geografia do polígono e retorna as cadeias de linhas correspondentes aos anéis internos.
  • Se a entrada for a GEOGRAPHY completa, retornará uma região geográfica vazia.
  • Se o polígono de entrada não tiver buracos, retornará uma matriz 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

ARRAY

Exemplos

WITH geo AS (
  SELECT ST_GEOGFROMTEXT('polygon((0 0, 1 1, 1 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))') UNION ALL
  SELECT ST_GEOGFROMTEXT('polygon((1 1, 1 10, 5 10, 5 1, 1 1), (2 2.5, 3.5 3, 2.5 2, 2 2.5), (3.5 7, 4 6, 3 3, 3.5 7))') UNION ALL
  SELECT ST_GEOGFROMTEXT('fullglobe') UNION ALL
  SELECT null)
SELECT ST_INTERIORRINGS(g) AS rings FROM geo;

+----------------------------------------------------------------------------+
| rings                                                                      |
+----------------------------------------------------------------------------+
| []                                                                         |
| [LINESTRING(2 2, 3 4, 2 4, 2 2)]                                           |
| [LINESTRING(2.5 2, 3.5 3, 2 2.5, 2.5 2), LINESTRING(3 3, 4 6, 3.5 7, 3 3)] |
| []                                                                         |
| NULL                                                                       |
+----------------------------------------------------------------------------+

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 são separados, isto é, não há pontos que apareçam na entrada geometry_1 e geometry_2, um espaço em branco GEOGRAPHY é retornado.

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

Tipo de retorno

GEOGRAPHY

ST_INTERSECTS

ST_INTERSECTS(geography_1, geography_2)

Descrição

Retorna TRUE se o cruzamento de ponto de geography_1 e geography_2 não estiver vazio. Assim, esta função retornará TRUE se houver pelo menos um ponto que apareça nos dois GEOGRAPHYs de entrada.

Se ST_INTERSECTS retorna TRUE, isso significa que ST_DISJOINT retorna FALSE.

Tipo de retorno

BOOL

ST_INTERSECTSBOX

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

Descrição

Retorna TRUE se geography cruzar o retângulo entre [lng1, lng2] e [lat1, lat2]. As bordas do retângulo seguem linhas constantes de longitude e latitude. lng1 e lng2 especificam as linhas de longitude constantes mais a oeste e mais ao leste que ligam o retângulo, e lat1 e lat2 especificam as linhas de latitude constantes 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 seguir uma destas regras:
    • As duas longitudes estão no intervalo de [-180, 180] graus.
    • Uma das longitudes está no intervalo de [-180, 180] graus, e lng2 - lng1 está no intervalo de [0, 360].

Tipo de retorno

BOOL

Exemplo

SELECT p, st_intersectsbox(p, -90, 0, 90, 20) AS box1,
       st_intersectsbox(p, 90, 0, -90, 20) AS box2
FROM UNNEST([st_geogpoint(10, 10), st_geogpoint(170, 10),
             st_geogpoint(30, 30)]) p
+----------------+--------------+--------------+
| p              | box1         | box2         |
+----------------+--------------+--------------+
| POINT(10 10)   | true         | false        |
+----------------+--------------+--------------+
| POINT(170 10)  | false        | true         |
+----------------+--------------+--------------+
| POINT(30 30)   | false        | false        |
+----------------+--------------+--------------+

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_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_LENGTH

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, retornará zero. Se geography_expression for uma coleção, retorna o tamanho das linhas nela; se a coleção não contém linhas, retorna 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_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.

ST_MAKELINE vem em duas variantes. Para a primeira variante, a entrada precisa ser duas GEOGRAPHYs. Para o segundo, a entrada precisa ser um ARRAY do tipo GEOGRAPHY. Em cada variante, cada entrada GEOGRAPHY precisa consistir em um dos seguintes valores:

  • Exatamente um ponto
  • Exatamente uma cadeia de linhas

Para a primeira variante de ST_MAKELINE, se uma das entradas GEOGRAPHY é NULL, ST_MAKELINE retorna NULL. Para a segunda variante, se a entrada ARRAY ou qualquer elemento na entrada ARRAY é NULL, ST_MAKELINE retorna NULL.

Restrições

Cada borda precisa abranger estritamente menos de 180 graus.

OBSERVAÇÃO: o processo de ajuste do BigQuery pode descartar arestas suficientemente curtas e ajustar os dois endpoints 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[, 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.

ST_MAKEPOLYGON vem em duas variantes. Para a primeira variante, a entrada da cadeia de linhas é fornecida por um único GEOGRAPHY contendo exatamente uma cadeia de linhas. Para a segunda variante, a entrada consiste em um único GEOGRAPHY e uma matriz de GEOGRAPHYs, cada um contendo exatamente uma cadeia de linhas. O primeiro GEOGRAPHY em qualquer uma das variantes é usado para construir a concha poligonal. GEOGRAPHYs adicionais fornecidos na entrada ARRAY especificam 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.

Para a primeira variante de ST_MAKEPOLYGON, se uma das entradas GEOGRAPHY for NULL, ST_MAKEPOLYGON retorna NULL. Para a segunda variante, se a entrada ARRAY ou qualquer elemento na ARRAY for NULL, ST_MAKEPOLYGON retorna NULL.

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 deve 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 endpoints 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 todos os anéis poligonais fornecidos.

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.

Se a entrada ARRAY ou qualquer elemento em ARRAY for NULL, ST_MAKEPOLYGONORIENTED retornará NULL.

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 deve 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 borda 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 um construtor de polígono alternativo e outras restrições na construçã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 endpoints 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_MAXDISTANCE

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 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_NPOINTS

ST_NPOINTS(geography_expression)

Descrição

Um alias de ST_NUMPOINTS.

ST_NUMGEOMETRIES

ST_NUMGEOMETRIES(geography_expression)

Descrição

Retorna o número de linhas nas geometrias GEOGRAPHY. Para um único ponto, linestring ou polígono, ST_NUMGEOMETRIES retorna 1. Para qualquer coleção de geometrias, ST_NUMGEOMETRIES retorna o número de geometrias que compõem a coleção. ST_NUMGEOMETRIES retornará 0 se a entrada estiver vazia GEOGRAPHY.

Tipo de retorno

INT64

Exemplo

O exemplo a seguir calcula ST_NUMGEOMETRIES para uma região geográfica de ponto único, duas coleções e uma região geográfica vazia.

WITH example AS(
  SELECT ST_GeogFromText('POINT(5 0)') AS geography
  UNION ALL
  SELECT ST_GeogFromText('MULTIPOINT(0 1, 4 3, 2 6)') AS geography
  UNION ALL
  SELECT ST_GeogFromText('GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(1 2, 2 1))') AS geography
  UNION ALL
  SELECT ST_GeogFromText('GEOMETRYCOLLECTION EMPTY'))
SELECT
  geography,
  ST_NumGeometries(geography) AS num_geometries,
FROM example;

+------------------------------------------------------+----------------+
| geography                                            | num_geometries |
+------------------------------------------------------+----------------+
| POINT(5 0)                                           | 1              |
| MULTIPOINT(0 1, 4 3, 2 6)                            | 3              |
| GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(1 2, 2 1)) | 2              |
| GEOMETRYCOLLECTION EMPTY                             | 0              |
+------------------------------------------------------+----------------+

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_PERIMETER

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, retornará zero. Se geography_expression for uma coleção, retorna o perímetro 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_POINTN

ST_POINTN(linestring_geography, index)

Descrição

Retorna o ponto N de uma região geográfica de linestring como uma região geográfica de pontos, em que N é o índice. O índice é baseado em 1. Valores negativos são contados a partir do final da linestring, de modo que -1 seja o último ponto. Retorna um erro se a entrada não for uma linestring, se a entrada estiver vazia ou se não houver vértices no índice especificado. Use o prefixo SAFE para receber NULL para entrada inválida, em vez de um erro.

Tipo de retorno

Ponto GEOGRAPHY

Exemplo

O exemplo a seguir usa ST_POINTN, ST_STARTPOINT e ST_ENDPOINT para extrair pontos de uma linestring.

WITH linestring AS (
    SELECT ST_GeogFromText('linestring(1 1, 2 1, 3 2, 3 3)') g
)
SELECT ST_PointN(g, 1) AS first, ST_PointN(g, -1) AS last,
    ST_PointN(g, 2) AS second, ST_PointN(g, -2) AS second_to_last
FROM linestring;

+--------------+--------------+--------------+----------------+
| first        | last         | second       | second_to_last |
+--------------+--------------+--------------+----------------+
| POINT(1 1)   | POINT(3 3)   | POINT(2 1)   | POINT(3 2)     |
+--------------+--------------+--------------+----------------+

ST_SIMPLIFY

ST_SIMPLIFY(geography, tolerance_meters)

Descrição

Retorna uma versão simplificada de geography, a entrada fornecida GEOGRAPHY. A entrada GEOGRAPHY é simplificada pela substituição de cadeias quase retas de bordas curtas por uma única borda longa. A entrada geography não será alterada em mais do que a tolerância especificada por tolerance_meters. Assim, as bordas simplificadas têm a garantia de passar dentro de tolerance_meters das posições originais de todos os vértices que foram removidos dessa borda. O tolerance_meters especificado está em metros na superfície da Terra.

Observe que ST_SIMPLIFY preserva as relações topológicas, o que significa que nenhuma borda nova será criada e a saída será válida. Para uma tolerância grande o suficiente, as formas adjacentes podem ser recolhidas em um único objeto ou uma forma pode ser simplificada para uma forma com uma dimensão menor.

Restrições

Para que ST_SIMPLIFY tenha algum efeito, tolerance_meters precisa ser diferente de zero.

ST_SIMPLIFY retornará um erro se a tolerância especificada por tolerance_meters for uma das seguintes:

  • Uma tolerância negativa.
  • Maior que cerca de 7.800 quilômetros.

Tipo de retorno

GEOGRAPHY

Exemplos

O exemplo a seguir mostra como ST_SIMPLIFY simplifica a linha de entrada GEOGRAPHY removendo vértices intermediários.

WITH example AS
 (SELECT ST_GEOGFROMTEXT('LINESTRING(0 0, 0.05 0, 0.1 0, 0.15 0, 2 0)') AS line)
SELECT
   line AS original_line,
   ST_SIMPLIFY(line, 1) AS simplified_line
FROM example;

+---------------------------------------------+----------------------+
|                original_line                |   simplified_line    |
+---------------------------------------------+----------------------+
| LINESTRING(0 0, 0.05 0, 0.1 0, 0.15 0, 2 0) | LINESTRING(0 0, 2 0) |
+---------------------------------------------+----------------------+

O exemplo a seguir ilustra como o resultado de ST_SIMPLIFY pode ter uma dimensão menor do que a forma original.

WITH example AS
 (SELECT
    ST_GEOGFROMTEXT('POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0))') AS polygon,
    t AS tolerance
  FROM UNNEST([1000, 10000, 100000]) AS t)
SELECT
  polygon AS original_triangle,
  tolerance AS tolerance_meters,
  ST_SIMPLIFY(polygon, tolerance) AS simplified_result
FROM example

+-------------------------------------+------------------+-------------------------------------+
|          original_triangle          | tolerance_meters |          simplified_result          |
+-------------------------------------+------------------+-------------------------------------+
| POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |             1000 | POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |
| POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |            10000 |            LINESTRING(0 0, 0.1 0.1) |
| POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |           100000 |                          POINT(0 0) |
+-------------------------------------+------------------+-------------------------------------+

ST_SNAPTOGRID

ST_SNAPTOGRID(geography_expression, grid_size)

Descrição

Retorna o GEOGRAPHY de entrada, em que cada vértice foi alinhada a 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_STARTPOINT

ST_STARTPOINT(linestring_geography)

Descrição

Retorna o primeiro ponto de uma geografia de linestring como uma geografia de ponto. 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_StartPoint(ST_GeogFromText('linestring(1 1, 2 1, 3 2, 3 3)')) first

+--------------+
| first        |
+--------------+
| POINT(1 1)   |
+--------------+

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 geography_2.
  2. O interior de geography_1 e o interior de geography_2 são separados.

Tipo de retorno

BOOL

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.

ST_UNION vem em duas variantes. Para a primeira variante, a entrada precisa ser duas GEOGRAPHYs. Para a segunda, a entrada é um ARRAY do tipo GEOGRAPHY.

Para a primeira variante de ST_UNION, se uma entrada GEOGRAPHY for NULL, ST_UNION retorna NULL. Para a segunda variante, se o valor da entrada ARRAY é NULL, ST_UNION retorna NULL. Para uma entrada ARRAY que não seja NULL, a união é calculada e elementos NULL são ignorados para que não afetem a saída.

Consulte ST_UNION_AGG para a versão agregada de ST_UNION.

Tipo de retorno

GEOGRAPHY

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.

ST_UNION_AGG ignora valores GEOGRAPHY de entrada NULL.

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

Tipo de retorno

GEOGRAPHY

ST_WITHIN

ST_WITHIN(geography_1, geography_2)

Descrição

Retorna TRUE se nenhum ponto de geography_1 está fora de geography_2 e os interiores de geography_1 e geography_2 se cruzam.

Dados dois locais geográficos a e b, ST_WITHIN(a, b) retorna o mesmo resultado de ST_CONTAINS(b, a). Observe a ordem oposta dos argumentos.

Tipo de retorno

BOOL

ST_X

ST_X(geography_expression)

Descrição

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

Para qualquer entrada GEOGRAPHY que não seja de ponto único, incluindo um GEOGRAPHY vazio, ST_X retornará um erro. Use o prefixo SAFE. para receber 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 da entrada GEOGRAPHY de ponto único.

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

Tipo de retorno

FLOAT64

Exemplo

Consulte ST_X para exemplos de uso.