Funciones de geografía en SQL estándar

Las funciones de geografía operan en valores GEOGRAPHY de BigQuery o los generan. La firma de cualquier función de geografía comienza con ST_. BigQuery admite las siguientes funciones que se pueden usar para analizar datos geográficos, determinar relaciones espaciales entre atributos geográficos y construir o manipular objetos GEOGRAPHY.

Todas las funciones de geografía de BigQuery muestran NULL si algún argumento de entrada es NULL.

Categorías

Las funciones de geografía se agrupan en las siguientes categorías, según su comportamiento:

Categoría Funciones Descripción
Constructores ST_GEOGPOINT
ST_MAKELINE
ST_MAKEPOLYGON
ST_MAKEPOLYGONORIENTED 		Funciones que crean valores geográficos nuevos a partir de coordenadas o ubicaciones geográficas existentes.
Analizadores ST_GEOGFROM
ST_GEOGFROMGEOJSON
ST_GEOGFROMTEXT
ST_GEOGFROMWKB
ST_GEOGPOINTFROMGEOHASH
 Funciones que crean geografías a partir de un formato externo como WKT y GeoJSON.
Formateadores ST_ASBINARY
ST_ASGEOJSON
ST_ASTEXT
ST_GEOHASH 		Funciones que exportan geografías a un formato externo, como WKT.
Transformaciones ST_BOUNDARY
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)
 Funciones que generan una geografía nueva según la entrada.
Descriptores de acceso ST_DIMENSION
ST_DUMP
ST_ENDPOINT
ST_ISCOLLECTION
ST_ISEMPTY
ST_NPOINTS
ST_NUMGEOMETRIES
ST_NUMPOINTS
ST_POINTN
ST_STARTPOINT
ST_X
ST_Y
 Funciones que proporcionan acceso a las propiedades de una geografía sin efectos secundarios.
Predicados ST_CONTAINS
ST_COVEREDBY
ST_COVERS
ST_DISJOINT
ST_DWITHIN
ST_EQUALS
ST_INTERSECTS
ST_INTERSECTSBOX
ST_TOUCHES
ST_WITHIN
 Funciones que muestran TRUE o FALSE para alguna relación espacial entre dos geografías o alguna propiedad de una geografía. Por lo general, estas funciones se usan en cláusulas de filtro.
Medidas ST_ANGLE
ST_AREA
ST_AZIMUTH
ST_DISTANCE
ST_LENGTH
ST_MAXDISTANCE
ST_PERIMETER
 Funciones que calculan mediciones de una o más geografías.
Agrupamiento en clústeres ST_CLUSTERDBSCAN Funciones que realizan agrupamiento en clústeres en geografías.

ST_ANGLE

ST_ANGLE(point_geography_1, point_geography_2, point_geography_3)

Description

Toma tres valores GEOGRAPHY de punto, que representan dos líneas de intersección. Muestra el ángulo entre estas líneas. Los puntos 2 y 1 representan la primera línea y el punto 2 y el punto 3 representan la segunda línea. El ángulo entre estas líneas está en radianes, en el rango [0, 2pi). El ángulo se mide en el sentido de las agujas del reloj desde la primera línea hasta la segunda.

ST_ANGLE tiene los siguientes casos extremos:

  • Si los puntos 2 y 3 son iguales, muestra NULL.
  • Si los puntos 2 y 1 son iguales, muestra NULL.
  • Si los puntos 2 y 3 son exactamente antipodales, muestra NULL.
  • Si los puntos 2 y 1 son exactamente antipodales, muestra NULL.
  • Si alguna de las geografías de entrada no es un punto único o si está vacía, arroja un error.

Tipo de datos que se muestra

FLOAT64

Ejemplo

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])

Descripción

Muestra el área en metros cuadrados que cubren los polígonos en el objeto GEOGRAPHY de entrada.

Si geography_expression es un punto o una línea, muestra cero. Si geography_expression es una colección, muestra el área de los polígonos en la colección; si la colección no contiene polígonos, muestra cero.

El parámetro opcional use_spheroid determina cómo esta función mide la distancia. Si use_spheroid es FALSE, la función mide la distancia en la superficie de una esfera perfecta.

En la actualidad, el parámetro use_spheroid solo admite el valor FALSE. El valor predeterminado de use_spheroid es FALSE.

Tipo de datos que se muestra

FLOAT64

ST_AZIMUTH

ST_AZIMUTH(point_geography_1, point_geography_2)

Description

Toma dos valores GEOGRAPHY de puntos y muestra la azimuth del segmento de línea formado por los puntos 1 y 2. La azimuth es el ángulo en radianes medidos entre la línea del punto 1 orientado hacia norte geográfico al segmento de línea del punto 1 al punto 2.

El ángulo positivo se mide en sentido horario en la superficie de una esfera. Por ejemplo, la azimuth de un segmento de línea:

  • Si apunta al norte es 0
  • Si apunta al este es PI/2
  • Si apunta al sur es PI
  • Si apunta al oeste es 3PI/2

ST_AZIMUTH tiene los siguientes casos extremos:

  • Si los dos puntos de entrada son iguales, muestra NULL.
  • Si los dos puntos de entrada son exactamente antipodales, muestra NULL.
  • Si cualquiera de las geografías de entrada no son puntos únicos o la geografía vacía, muestra un error.

Tipo de datos que se muestra

FLOAT64

Ejemplo


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_ASBINARY

ST_ASBINARY(geography_expression)

Description

Muestra la representación WKB de un GEOGRAPHY de entrada.

Consulta ST_GEOGFROMWKB para construir un objeto GEOGRAPHY a partir de WKB.

Tipo de datos que se muestra

BYTES

ST_ASGEOJSON

ST_ASGEOJSON(geography_expression)

Description

Muestra la representación GeoJSON que cumple con RFC 7946 del objeto GEOGRAPHY de entrada.

Un objeto GEOGRAPHY de BigQuery tiene bordes geodésicos esféricos, mientras que un objeto Geometry de GeoJSON tiene de forma explícita bordes planos. Para generar una conversión entre estos dos tipos de bordes, BigQuery agrega puntos adicionales a la línea cuando sea necesario para que la secuencia resultante de bordes permanezca dentro de los 10 metros del borde original.

Consulta ST_GEOGFROMGEOJSON para construir un objeto GEOGRAPHY a partir de GeoJSON.

Tipo de datos que se muestra

STRING

ST_ASTEXT

ST_ASTEXT(geography_expression)

Description

Muestra la representación WKT de un GEOGRAPHY de entrada.

Consulta ST_GEOGFROMTEXT para construir un objeto GEOGRAPHY a partir de WKT.

Tipo de datos que se muestra

STRING

ST_BOUNDARY

ST_BOUNDARY(geography_expression)

Descripción

Muestra un único objeto GEOGRAPHY que contiene la unión de los límites de cada componente en el objeto GEOGRAPHY de entrada proporcionado.

El límite de cada componente de un objeto GEOGRAPHY se define de la siguiente manera:

  • El límite de un punto está vacío.
  • El límite de una LineString consiste en los extremos de la LineString.
  • El límite de un polígono consiste en las LineString que forman el perímetro del polígono y cada uno de los agujeros del polígono.

Tipo de datos que se muestra

GEOGRAPHY

ST_CENTROID

ST_CENTROID(geography_expression)

Descripción

Muestra el centroide del objeto GEOGRAPHY de entrada como un GEOGRAPHY de un solo punto.

El centroide de un objeto GEOGRAPHY es el promedio ponderado de los centroides de los componentes de mayor dimensión en el GEOGRAPHY. El centroide para componentes en cada dimensión se define de la siguiente manera:

  • El centroide de puntos es la media aritmética de las coordenadas de entrada.
  • El centroide de las LineString es el centroide de todos los bordes ponderados por la longitud. El centroide de cada borde es el punto medio geodésico del borde.
  • El centroide de un polígono es su centro de masa.

Si el GEOGRAPHY de entrada está vacío, se muestra un objeto GEOGRAPHY vacío.

Limitaciones

En el improbable caso de que el centroide de un GEOGRAPHY no pueda definirse por un solo punto en la superficie de la Tierra, se muestra un punto determinista, pero arbitrario. Esto solo puede suceder si el centroide está exactamente en el centro de la Tierra, como el centroide de un par de puntos antipodales, y la probabilidad de que esto ocurra es muy pequeña.

Tipo de datos que se muestra

GEOGRAPHY

ST_CENTROID_AGG

ST_CENTROID_AGG(geography)

Descripción

Calcula el centroide del conjunto de objetos GEOGRAPHY de entrada como un GEOGRAPHY de un solo punto.

El centroide sobre el conjunto de objetos GEOGRAPHY de entrada es el promedio ponderado del centroide de cada objeto GEOGRAPHY individual. Solo los objetos GEOGRAPHY con la dimensión más alta presentes en la entrada contribuyen al centroide de todo el conjunto. Por ejemplo, si la entrada contiene objetos GEOGRAPHY con líneas y objetos GEOGRAPHY con solo puntos, ST_CENTROID_AGG muestra el promedio ponderado de los objetos GEOGRAPHY con líneas, ya que esos tienen una dimensión máxima. En este ejemplo, ST_CENTROID_AGG ignora los objetos GEOGRAPHY con solo puntos cuando se calcula el centroide agregado.

ST_CENTROID_AGG ignora los valores GEOGRAPHY de entrada NULL.

Consulta ST_CENTROID a fin de ver la versión no agregada de ST_CENTROID_AGG y la definición de centroide para un valor GEOGRAPHY individual.

Tipo de datos que se muestra

GEOGRAPHY

Ejemplo

Las siguientes consultas calculan el centroide agregado sobre un conjunto de valores de GEOGRAPHY. La entrada a la primera consulta contiene solo puntos y, por lo tanto, cada valor contribuye al centroide agregado. Observa también que ST_CENTROID_AGG no es equivalente a llamar a ST_CENTROID en el resultado de ST_UNION_AGG; la unión quita los duplicados, a diferencia de ST_CENTROID_AGG. La entrada a la segunda consulta tiene dimensiones mixtas, y solo los valores con la dimensión más alta del conjunto, las líneas, afectan al 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])

Descripción

Muestra un GEOGRAPHY que contiene un punto en geography_1 con la menor distancia posible a geography_2. Esto implica que la distancia entre el punto que muestra ST_CLOSESTPOINT y geography_2 es menor o igual que la distancia entre cualquier otro punto en geography_1 y geography_2.

Si cualquiera de los objetos GEOGRAPHY de entrada está vacío, ST_CLOSESTPOINT muestra NULL.

El parámetro opcional use_spheroid determina cómo esta función mide la distancia. Si use_spheroid es FALSE, la función mide la distancia en la superficie de una esfera perfecta.

En la actualidad, el parámetro use_spheroid solo admite el valor FALSE. El valor predeterminado de use_spheroid es FALSE.

Tipo de datos que se muestra

GEOGRAPHY

ST_CLUSTERDBSCAN

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

Realiza el agrupamiento en clústeres DBSCAN en una columna de geografías. Muestra un número de clúster basado en 0.

Parámetros de entrada

  • geography_column: Una columna de GEOGRAPHY que está agrupada en clústeres.
  • epsilon: La épsilon que especifica el radio, medido en metros, alrededor de un valor principal. Valor FLOAT64 no negativo.
  • minimum_geographies: Especifica la cantidad mínima de geografías en un solo clúster. Solo las entradas densas forman un clúster; de lo contrario, se clasifica como ruido. Valor INT64 no negativo.

  • OVER: Especifica una ventana. Consulta Funciones analíticas. El uso de la cláusula OVER con ST_CLUSTERDBSCAN es compatible con los siguientes elementos:

    • PARTITION BY: Opcional
    • ORDER BY: Opcional
    • window_frame_clause: No permitido

Tipos geográficos y el algoritmo DBSCAN

El algoritmo DBSCAN identifica clústeres de datos de alta densidad y marca valores atípicos en áreas con ruido de baja densidad. Las geografías que se pasan a través de geography_column se clasifican en una de las tres formas siguientes mediante el algoritmo DBSCAN:

  • Valor principal: una geografía es un valor principal si se encuentra a una distancia epsilon de geografías minimum_geographies, incluida la misma. El valor principal inicia un clúster nuevo o se agrega al mismo clúster que un valor principal dentro de la distancia epsilon. Los valores principales se agrupan en un clúster junto con todos los demás valores principales y los valores del borde que se encuentran a una distancia epsilon.
  • Valor del borde: una geografía es un valor del borde si se encuentra a la distancia épsilon de un valor principal. Se agrega al mismo clúster que un valor principal dentro de la distancia epsilon. Un valor del borde puede estar a una distancia epsilon de más de un clúster. En este caso, se puede asignar de forma arbitraria a cualquier clúster, y la función producirá el mismo resultado en llamadas posteriores.
  • Ruido: una geografía es ruido si no es un valor principal ni un valor de borde. Los valores de ruido se asignan a un clúster NULL. Una GEOGRAPHY vacía siempre se clasifica como ruido.

Limitaciones

  • El argumento minimum_geographies es un INT64 no negativo, y epsilon es un FLOAT64 no negativo.
  • Una geografía vacía no puede unirse a ningún clúster.
  • Varias asignaciones de agrupamiento en clústeres pueden ser posibles para un valor de borde. Si una geografía es un valor de borde, ST_CLUSTERDBSCAN la asignará a un clúster válido arbitrario.

Tipo de datos que se muestra

INT64 para cada geografía en la columna de geografía.

Ejemplos

En este ejemplo, se realiza un agrupamiento en clústeres DBSCAN con un radio de 100,000 metros con un argumento minimum_geographies de 1. Las ubicaciones geográficas que se analizan son una mezcla de puntos, líneas y 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)

Descripción

Muestra TRUE si ningún punto de geography_2 está fuera de geography_1 y los interiores se cruzan; de lo contrario, muestra FALSE.

NOTA: Un objeto GEOGRAPHY no contiene su propio límite. Compara esto con ST_COVERS.

Tipo de datos que se muestra

BOOL

Ejemplo

En la siguiente consulta, se prueba si el polígono POLYGON((1 1, 20 1, 10 20, 1 1)) contiene cada uno de los tres puntos, (0, 0), (1, 1) y (10, 10), que se encuentran en el exterior, el límite y el interior del 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)

Descripción

Muestra la envolvente convexa para la entrada GEOGRAPHY. La envolvente convexa es la GEOGRAPHY convexa más pequeña que cubre la entrada. Una GEOGRAPHY es convexa si para cada par de puntos en GEOGRAPHY, el borde geodésico que conecta los puntos también se encuentra en la misma GEOGRAPHY.

En la mayoría de los casos, la envolvente convexa consiste en un único polígono. Entre los casos extremos destacados, se incluyen los siguientes:

  • La envolvente convexa de un solo punto también es un punto.
  • La envolvente convexa de dos o más puntos colineales es una LineString siempre que esa LineString sea convexa.
  • Si la entrada GEOGRAPHY abarca más que un hemisferio, la envolvente convexa es el globo terráqueo completo. Esto incluye cualquier entrada que contenga un par de puntos antipodales.
  • ST_CONVEXHULL muestra NULL si la entrada es NULL o la GEOGRAPHY vacía.

Tipo de datos que se muestra

GEOGRAPHY

Ejemplos

La envolvente convexa que muestra ST_CONVEXHULL puede ser un punto, un LineString o un polígono, según la 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)

Descripción

Muestra FALSE si geography_1 o geography_2 están vacíos. Muestra TRUE si ningún punto de geography_1 está en el exterior de geography_2.

Dados dos GEOGRAPHY, a y b, ST_COVEREDBY(a, b) muestra el mismo resultado que ST_COVERS(b, a). Ten en cuenta el orden opuesto de los argumentos.

Tipo de datos que se muestra

BOOL

ST_COVERS

ST_COVERS(geography_1, geography_2)

Descripción

Muestra FALSE si geography_1 o geography_2 están vacíos. Muestra TRUE si ningún punto de geography_2 está en el exterior de geography_1.

Tipo de datos que se muestra

BOOL

Ejemplo

En la siguiente consulta, se prueba si el polígono POLYGON((1 1, 20 1, 10 20, 1 1)) abarca cada uno de los tres puntos (0, 0), (1, 1) y (10, 10), que se encuentran en el exterior, el límite y el interior del 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)

Descripción

Muestra un GEOGRAPHY que representa la diferencia de conjunto de puntos de geography_1 y geography_2. Por lo tanto, el resultado consta de la parte de geography_1 que no se interseca con geography_2.

Si geometry_1 está contenido por completo en geometry_2, ST_DIFFERENCE muestra un GEOGRAPHY vacío.

Limitaciones

Los objetos geométricos subyacentes que representan un objeto GEOGRAPHY de BigQuery corresponden a un conjunto de puntos cerrado. Por lo tanto, ST_DIFFERENCE es el cierre de la diferencia de conjunto de puntos entre geography_1 y geography_2. Esto implica que, si geography_1 y geography_2 se intersecan, una parte del límite de geography_2 podría aparecer en la diferencia.

Tipo de datos que se muestra

GEOGRAPHY

Ejemplo

En la siguiente consulta, se ilustra la diferencia entre geog1, un polígono más grande POLYGON((0 0, 10 0, 10 10, 0 0)) y geog1, un polígono más pequeño POLYGON((4 2, 6 2, 8 6, 4 2)) que se interseca con geog1. El resultado es geog1 con un agujero en el que geog2 se interseca con él.

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)

Descripción

Muestra la dimensión del elemento de mayor dimensión en el objeto GEOGRAPHY de entrada.

La dimensión de cada elemento posible es la siguiente:

  • La dimensión de un punto es 0.
  • La dimensión de una LineString es 1.
  • La dimensión de un polígono es 2.

Si la entrada GEOGRAPHY está vacía, ST_DIMENSION muestra -1.

Tipo de datos que se muestra

INT64

ST_DISJOINT

ST_DISJOINT(geography_1, geography_2)

Descripción

Muestra TRUE si la intersección de geography_1 y geography_2 está vacía, es decir, ningún punto en geography_1 aparece en geography_2.

ST_DISJOINT es la negación lógica de ST_INTERSECTS.

Tipo de datos que se muestra

BOOL

ST_DISTANCE

ST_DISTANCE(geography_1, geography_2[, use_spheroid])

Descripción

Muestra la distancia más corta en metros entre dos objetos GEOGRAPHY no vacíos.

Si cualquiera de los objetos GEOGRAPHY de entrada está vacío, ST_DISTANCE muestra NULL.

El parámetro opcional use_spheroid determina cómo esta función mide la distancia. Si use_spheroid es FALSE, la función mide la distancia en la superficie de una esfera perfecta.

En la actualidad, el parámetro use_spheroid solo admite el valor FALSE. El valor predeterminado de use_spheroid es FALSE.

Tipo de datos que se muestra

FLOAT64

ST_DUMP

ST_DUMP(geography[, dimension])

Descripción

Muestra un ARRAY de GEOGRAPHY simples en el que cada elemento es un componente de la entrada GEOGRAPHY. Una GEOGRAPHY simple consiste en un único punto, LineString o polígono. Si la entrada GEOGRAPHY es simple, el resultado es un solo elemento. Cuando la entrada GEOGRAPHY es una colección, ST_DUMP muestra un ARRAY, con una GEOGRAPHY simple para cada componente de la colección.

Si se proporciona dimension, la función solo muestra GEOGRAPHY de la dimensión correspondiente. Una dimensión de -1 equivale a omitir dimension.

Tipo de datos que se muestra

ARRAY

Ejemplos

En el siguiente ejemplo, se ve cómo ST_DUMP muestra las geografías simples dentro de una geografía compleja.

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

En el siguiente ejemplo, se indica cómo ST_DUMP con el argumento de dimensión solo muestra geografías simples de la dimensión determinada.

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])

Descripción

Muestra TRUE si la distancia entre al menos un punto en geography_1 y un punto en geography_2 es menor o igual que la distancia dada por el argumento distance; de lo contrario, muestra FALSE. Si alguna de las entradas GEOGRAPHY está vacía, ST_DWithin muestra FALSE. El distance dado está en metros sobre la superficie de la Tierra.

El parámetro opcional use_spheroid determina cómo esta función mide la distancia. Si use_spheroid es FALSE, la función mide la distancia en la superficie de una esfera perfecta.

En la actualidad, el parámetro use_spheroid solo admite el valor FALSE. El valor predeterminado de use_spheroid es FALSE.

Tipo de datos que se muestra

BOOL

ST_ENDPOINT

ST_ENDPOINT(linestring_geography)

Description

Muestra el último punto de una geografía de LineString como una geografía de puntos. Muestra un error si la entrada no es una LineString o si la entrada está vacía. Usa el prefijo SAFE a fin de obtener NULL para la entrada no válida en lugar de un error.

Tipo de datos que se muestra

Punto GEOGRAPHY

Ejemplo

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)

Descripción

Muestra TRUE si geography_1 y geography_2 representan el mismo

valor GEOGRAPHY. Para ser más precisos, esto significa que se cumple una de las siguientes condiciones: + ST_COVERS(geography_1, geography_2) = TRUE y ST_COVERS(geography_2, geography_1) = TRUE + geography_1 y geography_2 están vacíos.

Por lo tanto, dos objetos GEOGRAPHY pueden ser iguales, incluso si el orden de los puntos o vértices difiere, siempre que todavía representen la misma estructura geométrica.

Limitaciones

No se asegura que ST_EQUALS sea una función transitiva.

Tipo de datos que se muestra

BOOL

ST_EXTERIORRING

ST_EXTERIORRING(polygon_geography)

Description

Muestra una geografía de LineString que corresponde al anillo más externo de una geografía del polígono.

  • Si la geografía de entrada es un polígono, obtiene el anillo más externo de la geografía del polígono y muestra la LineString correspondiente.
  • Si la entrada es GEOGRAPHY completa, muestra una geografía vacía.
  • Muestra un error si la entrada no es un único polígono.

Usa el prefijo SAFE a fin de mostrar NULL para la entrada no válida en lugar de un error.

Tipo de datos que se muestra

  • LineString GEOGRAPHY
  • GEOGRAPHY está vacío

Ejemplos

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_INTERIORRINGS

ST_INTERIORRINGS(polygon_geography)

Description

Muestra un array de geografías de LineString que corresponde a los anillos del interior de una geografía del polígono. Cada anillo interior es el borde de un orificio dentro del polígono de entrada.

  • Si la geografía de entrada es un polígono, excluye el anillo externo de la geografía del polígono y muestra las LineString correspondientes a los anillos internos.
  • Si la entrada es la GEOGRAPHY completo, muestra un array vacío.
  • Si el polígono de entrada no tiene agujeros, muestra un array vacío.
  • Muestra un error si la entrada no es un único polígono.

Usa el prefijo SAFE a fin de mostrar NULL para la entrada no válida en lugar de un error.

Tipo de datos que se muestra

ARRAY

Ejemplos

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_EXTERIORRING(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_GEOGFROM

ST_GEOGFROM(expression)

Description

Convierte una expresión para un valor STRING o BYTES en un valor GEOGRAPHY.

Si expression representa un valor STRING, debe ser una representación válida de GEOGRAPHY en uno de los siguientes formatos:

  • Formato WKT. A fin de obtener más información sobre este formato y los requisitos para usarlo, consulta ST_GEOGFROMTEXT.
  • WKB en formato de texto hexadecimal. A fin de obtener más información sobre este formato y los requisitos para usarlo, consulta ST_GEOGFROMWKB.
  • Formato GeoJSON A fin de obtener más información sobre este formato y los requisitos para usarlo, consulta ST_GEOGFROMWKB.

Si expression representa un valor BYTES, debe ser una expresión binaria GEOGRAPHY válida en formato WKB. A fin de obtener más información sobre este formato y los requisitos para usarlo, consulta ST_GEOGFROMWKB.

Si expression es NULL, el resultado es NULL.

Tipo de datos que se muestra

GEOGRAPHY

Ejemplos

Esto toma una string con formato WKT y muestra un 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)) |
+------------------------------------+

Toma una string con codificación hexadecimal en formato WKB y muestra un punto GEOGRAPHY:

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

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

Esto toma bytes con formato WKB y muestra un punto GEOGRAPHY:

SELECT ST_GEOGFROM('010100000000000000000000400000000000001040')-AS WKB_format

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

Esto toma una string con formato GEOJSON y muestra un 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])

Description

Muestra un valor GEOGRAPHY que corresponde a la representación GeoJSON de entrada.

ST_GEOGFROMGEOJSON acepta entradas que cumplan con RFC 7946.

Si el parámetro make_valid se establece en TRUE, la función intenta reparar polígonos que no cumplan con la semántica de Open Geospatial Consortium. En este parámetro, se usa la sintaxis de argumentos con nombre y debe especificarse mediante la sintaxis make_valid => argument_value.

Un objeto GEOGRAPHY de BigQuery tiene bordes geodésicos esféricos, mientras que un objeto Geometry de GeoJSON tiene bordes planos de forma explícita. Para generar una conversión entre estos dos tipos de bordes, BigQuery agrega puntos adicionales a la línea cuando sea necesario para que la secuencia resultante de bordes permanezca dentro de los 10 metros del borde original.

Consulta ST_ASGEOJSON para formatear un objeto GEOGRAPHY como GeoJSON.

Limitaciones

La entrada está sujeta a las siguientes restricciones:

  • ST_GEOGFROMGEOJSON solo acepta fragmentos de geometría JSON y no se puede usar para transferir un documento JSON completo.
  • El fragmento JSON de entrada debe constar de un tipo de geometría GeoJSON, que incluye Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon y GeometryCollection. Cualquier otro tipo de GeoJSON, como Feature o FeatureCollection, generará un error.
  • Una posición en el miembro de coordinates de un tipo de geometría GeoJSON debe constar de exactamente dos elementos. El primero es la longitud y el segundo es la latitud. Por lo tanto, ST_GEOGFROMGEOJSON no admite el tercer elemento opcional para una posición en el miembro de coordinates.

Tipo de datos que se muestra

GEOGRAPHY

ST_GEOGFROMTEXT

Firma 1

ST_GEOGFROMTEXT(wkt_string[, oriented])

Description

Muestra un valor GEOGRAPHY que corresponde a la representación WKT de entrada.

Esta función admite un parámetro opcional de tipo BOOL, oriented. Si este parámetro se establece en TRUE, se supone que cualquier polígono en la entrada está orientado de la siguiente manera: si alguien camina por el límite del polígono en el orden de los vértices de entrada, el interior del polígono está a la izquierda. Esto permite que WKT represente polígonos más grandes que un hemisferio. Si oriented es FALSE o se omite, esta función muestra el polígono con el área más pequeña. Consulta también ST_MAKEPOLYGONORIENTED, que es similar a ST_GEOGFROMTEXT con oriented=TRUE.

Para formatear GEOGRAPHY como WKT, usa ST_ASTEXT.

Limitaciones

  • Se supone que todos los bordes de entrada son geodésicos esféricos y no líneas rectas planas. Para leer datos en una proyección plana, considera usar ST_GEOGFROMGEOJSON. Para obtener más información sobre las diferencias entre las geodésicas esféricas y las líneas planas, consulta Bordes y sistemas de coordenadas.
  • La función no admite geometrías tridimensionales con un sufijo Z y tampoco admite geometrías de sistema de referencia lineal con un sufijo M.
  • La función solo admite primitivas geométricas y geometrías multipartes. En particular, solo admite Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon y GeometryCollection.

Tipo de datos que se muestra

GEOGRAPHY

Ejemplo

En la siguiente consulta, se lee la string WKT POLYGON((0 0, 0 2, 2 2, 2 0, 0 0)) como un polígono no orientado y como un polígono orientado, y comprueba si cada resultado contiene el punto (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     |
+-------------------+---------------+-----------+

Firma 2

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

Description

Muestra un valor GEOGRAPHY que corresponde a la representación WKT de entrada.

En esta función, se admiten tres parámetros opcionales de tipo BOOL: oriented, planar y make_valid. En esta firma, se usa la sintaxis de argumentos con nombre, y los parámetros se deben especificar mediante la sintaxis parameter_name => parameter_value en cualquier orden.

Si el parámetro oriented se establece en TRUE, se supone que cualquier polígono en la entrada está orientado de la siguiente manera: si alguien camina por el límite del polígono en el orden de los vértices de entrada, el interior del polígono está a la izquierda. Esto permite que WKT represente polígonos más grandes que un hemisferio. Si oriented es FALSE o se omite, esta función muestra el polígono con el área más pequeña. Consulta también ST_MAKEPOLYGONORIENTED, que es similar a ST_GEOGFROMTEXT con oriented=TRUE.

Si el parámetro planar se establece en TRUE, se supone que los bordes de las strings de línea y los polígonos se usan para la semántica de mapas planos, en lugar de la semántica predeterminada de geodésicas esféricas de BigQuery. Para obtener más información sobre las diferencias entre las geodésicas esféricas y las líneas planas, consulta Sistemas de coordenadas y bordes.

Si el parámetro make_valid se establece en TRUE, la función intenta reparar polígonos que no cumplan con la semántica de Open Geospatial Consortium.

Para formatear GEOGRAPHY como WKT, usa ST_ASTEXT.

Limitaciones

  • Se supone que todos los bordes de entrada son geodésicos esféricos de forma predeterminada y no líneas rectas planas. Para leer datos en una proyección plana, pasa el argumento planar => TRUE o considera usar ST_GEOGFROMGEOJSON. Para obtener más información sobre las diferencias entre las geodésicas esféricas y las líneas planas, consulta Sistemas de coordenadas y bordes.
  • La función no admite geometrías tridimensionales con un sufijo Z y tampoco admite geometrías de sistema de referencia lineal con un sufijo M.
  • La función solo admite primitivas geométricas y geometrías multipartes. En particular, solo admite Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon y GeometryCollection.
  • oriented y planar no pueden ser iguales a TRUE al mismo tiempo.
  • oriented y make_valid no pueden ser iguales a TRUE al mismo tiempo.

Ejemplo

En la siguiente consulta, se lee la string WKT POLYGON((0 0, 0 2, 2 2, 0 2, 0 0)) como un polígono no orientado y como un polígono orientado, y comprueba si cada resultado contiene el punto (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     |
+-------------------+---------------+-----------+

En la siguiente consulta, se convierte una string WKT con un polígono no válido en GEOGRAPHY. La string WKT infringe dos propiedades de un polígono válido: el bucle que describe que el polígono no está cerrado y contiene intersección automática. Con la opción make_valid, ST_GeogFromText se convierte de manera correcta en una forma de varios 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)

Description

Convierte una expresión para un valor STRING o BYTES de texto hexadecimal en un valor GEOGRAPHY. La expresión debe estar en formato WKB.

Para formatear GEOGRAPHY como WKB, usa ST_ASBINARY.

Limitaciones

Se supone que todos los bordes de entrada son geodésicos esféricos y no líneas rectas planas. Para leer datos en una proyección plana, considera usar ST_GEOGFROMGEOJSON.

Tipo de datos que se muestra

GEOGRAPHY

ST_GEOGPOINT

ST_GEOGPOINT(longitude, latitude)

Descripción

Crea un objeto GEOGRAPHY de un solo punto. ST_GEOGPOINT crea un punto a partir de los parámetros de longitud y latitud FLOAT64 especificados y muestra ese punto en un valor GEOGRAPHY.

Limitaciones

  • Las latitudes deben encontrarse en el rango [-90, 90]. Las latitudes fuera de este rango generarán un error.
  • Se permiten longitudes fuera del rango [-180, 180]; ST_GEOGPOINT utiliza el módulo de longitud de entrada 360 para obtener una longitud dentro de [-180, 180].

Tipo de datos que se muestra

GEOGRAPHY

ST_GEOGPOINTFROMGEOHASH

ST_GEOGPOINTFROMGEOHASH(geohash)

Description

Muestra un valor GEOGRAPHY que corresponde a un punto en el medio de un cuadro de límite definido en GeoHash.

Tipo de datos que se muestra

GEOGRAPHY

ST_GEOHASH

ST_GEOHASH(geography_expression, maxchars)

Description

Muestra una representación de GeoHash de geography_expression. El GeoHash resultante contendrá como máximo maxchars caracteres. Menos caracteres corresponden a una precisión menor (o, descrito de manera diferente, a un cuadro de límite más grande).

ST_GeoHash sobre un objeto GEOGRAPHY vacío muestra NULL.

Limitaciones

  • Solo se admiten objetos GEOGRAPHY que representan puntos únicos.
  • El valor máximo de maxchars es 20.

Tipo de datos que se muestra

STRING

Ejemplo

Muestra un GeoHash del Seattle Center con 10 caracteres de precisión.

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

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

ST_INTERSECTION

ST_INTERSECTION(geography_1, geography_2)

Descripción

Muestra un objeto GEOGRAPHY que representa la intersección del conjunto de puntos de los dos objetos GEOGRAPHY de entrada. Por lo tanto, cada punto en la intersección aparece en geography_1 y en geography_2.

Si los dos objetos GEOGRAPHY de entrada son inconexos, es decir, no hay puntos que aparezcan en geometry_1 y en geometry_2, se muestra un objeto GEOGRAPHY vacío.

Consulta ST_INTERSECTS, ST_DISJOINT para ver funciones de predicado relacionadas.

Tipo de datos que se muestra

GEOGRAPHY

ST_INTERSECTS

ST_INTERSECTS(geography_1, geography_2)

Descripción

Muestra TRUE si la intersección de conjunto de puntos de geography_1 y geography_2 no está vacía. Por lo tanto, esta función muestra TRUE si hay al menos un punto que aparece en ambos objetos GEOGRAPHY de entrada.

Si ST_INTERSECTS muestra TRUE, implica que ST_DISJOINT muestra FALSE.

Tipo de datos que se muestra

BOOL

ST_INTERSECTSBOX

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

Descripción

Muestra TRUE si geography interseca el rectángulo entre [lng1, lng2] y [lat1, lat2]. Los bordes del rectángulo siguen líneas constantes de longitud y latitud. lng1 y lng2 especifican las líneas de longitud constante al este y al oeste que delimitan el rectángulo, y lat1 y lat2 especifican las líneas de latitud constante mínima y máxima que delimitan el rectángulo.

Especifica todos los argumentos de longitud y latitud en grados.

Limitaciones

Los argumentos de entrada están sujetos a las siguientes restricciones:

  • Las latitudes deben estar en el rango de grados [-90, 90].
  • Las longitudes deben estar en el rango de grados [-180, 180].

Tipo de datos que se muestra

BOOL

Ejemplo

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)

Descripción

Muestra TRUE si la cantidad total de puntos, LineString y polígonos es mayor que uno.

Un objeto GEOGRAPHY vacío no es una colección.

Tipo de datos que se muestra

BOOL

ST_ISEMPTY

ST_ISEMPTY(geography_expression)

Descripción

Muestra TRUE si el objeto GEOGRAPHY proporcionado está vacío; es decir, GEOGRAPHY no contiene puntos, líneas ni polígonos.

NOTA: Un objeto GEOGRAPHY vacío de BigQuery no está asociado con una forma geométrica particular. Por ejemplo, los resultados de las expresiones ST_GEOGFROMTEXT('POINT EMPTY') y ST_GEOGFROMTEXT('GEOMETRYCOLLECTION EMPTY') son idénticos.

Tipo de datos que se muestra

BOOL

ST_LENGTH

ST_LENGTH(geography_expression[, use_spheroid])

Descripción

Muestra la longitud total en metros de las líneas en el objeto GEOGRAPHY de entrada.

Si geography_expression es un punto o un polígono, muestra cero. Si geography_expression es una colección, muestra la longitud de las líneas en la colección; si la colección no contiene líneas, muestra cero.

El parámetro opcional use_spheroid determina cómo esta función mide la distancia. Si use_spheroid es FALSE, la función mide la distancia en la superficie de una esfera perfecta.

En la actualidad, el parámetro use_spheroid solo admite el valor FALSE. El valor predeterminado de use_spheroid es FALSE.

Tipo de datos que se muestra

FLOAT64

ST_MAKELINE

ST_MAKELINE(geography_1, geography_2)

ST_MAKELINE(array_of_geography)

Descripción

Crea un objeto GEOGRAPHY con una sola LineString mediante la concatenación de los vértices de punto o línea de cada uno de los objetos GEOGRAPHY de entrada en el orden en que se presentan.

ST_MAKELINE tiene dos variantes. Para la primera variante, la entrada debe ser de dos objetos GEOGRAPHY. Para la segunda, la entrada es un ARRAY de tipo GEOGRAPHY. En ambas variantes, cada GEOGRAPHY de entrada debe ser uno de los siguientes valores:

  • Exactamente un punto
  • Exactamente una LineString

Para la primera variante de ST_MAKELINE, si alguna de las entradas GEOGRAPHY es NULL, ST_MAKELINE muestra NULL. Para la segunda variante, si el ARRAY de entrada o cualquier elemento de este ARRAY es NULL, ST_MAKELINE muestra NULL.

Limitaciones

Cada borde debe abarcar estrictamente menos de 180 grados.

NOTA: El proceso de ajuste de BigQuery puede descartar bordes lo bastante cortos y juntar los dos extremos. Por ejemplo, si dos objetos GEOGRAPHY de entrada contienen cada uno un punto, y los dos puntos están separados por una distancia menor que el radio de ajuste, los puntos se unirán. En tal caso, el resultado será un objeto GEOGRAPHY con exactamente un punto.

Tipo de datos que se muestra

GEOGRAPHY

ST_MAKEPOLYGON

ST_MAKEPOLYGON(geography_expression[, array_of_geography])

Descripción

Crea un objeto GEOGRAPHY que contiene un único polígono a partir de entradas de LineString, en el que cada LineString de entrada se usa para construir un anillo de polígono.

ST_MAKEPOLYGON tiene dos variantes. Para la primera variante, un único objeto GEOGRAPHY que contiene exactamente una LineString proporciona la LineString de entrada. Para la segunda variante, la entrada consiste en un único objeto GEOGRAPHY y un arreglo de objetos GEOGRAPHY, cada uno de los cuales contiene exactamente una LineString. El primer objeto GEOGRAPHY en cualquiera de las variantes se usa para construir el perímetro del polígono. Los objetos GEOGRAPHY adicionales proporcionados en el ARRAY de entrada especifican un agujero del polígono. Para cada objeto GEOGRAPHY de entrada que contenga exactamente una LineString, los siguientes enunciados deben ser ciertos:

  • La LineString debe constar de al menos tres vértices distintos.
  • La LineString debe estar cerrada; es decir, el primer y último vértice deben ser iguales. Si el primer y último vértice difieren, la función construye una arista final desde el primer vértice hasta el último.

Para la primera variante de ST_MAKEPOLYGON, si alguna de las entradas GEOGRAPHY es NULL, ST_MAKEPOLYGON muestra NULL. Para la segunda variante, si el ARRAY de entrada o cualquier elemento de este ARRAY es NULL, ST_MAKEPOLYGON muestra NULL.

NOTA: ST_MAKEPOLYGON acepta un objeto GEOGRAPHY vacío como entrada. ST_MAKEPOLYGON interpreta que un objeto GEOGRAPHY vacío tiene una LineString vacía, lo que creará un bucle completo; es decir, un polígono que cubre toda la Tierra.

Limitaciones

Juntos, los anillos de entrada deben formar un polígono válido:

  • El perímetro del polígono debe cubrir cada uno de los agujeros del polígono.
  • Solo puede haber un perímetro del polígono (que debe ser el primer anillo de entrada). Esto implica que los agujeros del polígono no se pueden anidar.
  • Los anillos del polígono solo pueden cruzarse en un vértice en el límite de ambos anillos.

Cada borde debe abarcar estrictamente menos de 180 grados.

Cada anillo del polígono divide la esfera en dos regiones. La primera LineString de entrada a ST_MAKEPOLYGON forma el perímetro del polígono, y el interior se elige como la más pequeña de las dos regiones. Cada LineString de entrada posterior especifica un agujero del polígono, por lo que el interior del polígono ya está bien definido. Para definir un perímetro del polígono de modo que el interior del polígono sea la mayor de las dos regiones, consulta ST_MAKEPOLYGONORIENTED.

NOTA: El proceso de ajuste de BigQuery puede descartar bordes lo bastante cortos y juntar los dos extremos. Por lo tanto, cuando los vértices se juntan, es posible que un agujero del polígono que sea lo suficientemente pequeño pueda desaparecer, o que el objeto GEOGRAPHY de salida pueda contener solo una línea o un punto.

Tipo de datos que se muestra

GEOGRAPHY

ST_MAKEPOLYGONORIENTED

ST_MAKEPOLYGONORIENTED(array_of_geography)

Descripción

Es igual que ST_MAKEPOLYGON, pero el orden de vértices de cada LineString de entrada determina la orientación de cada anillo del polígono. La orientación de un anillo del polígono define el interior del polígono de la siguiente manera: si alguien camina a lo largo del límite del polígono en el orden de los vértices de entrada, el interior del polígono está a la izquierda. Esto se aplica a cada anillo del polígono proporcionado.

Esta variante del constructor de polígonos es más flexible, ya que ST_MAKEPOLYGONORIENTED puede construir un polígono de modo que el interior esté a cualquiera de los lados del anillo del polígono. Sin embargo, la orientación adecuada de los anillos del polígono es crítica para construir el polígono deseado.

Si el ARRAY de entrada o cualquier elemento en el ARRAY es NULL, ST_MAKEPOLYGONORIENTED muestra NULL.

NOTA: El argumento de entrada para ST_MAKEPOLYGONORIENTED puede contener un objeto GEOGRAPHY vacío. ST_MAKEPOLYGONORIENTED interpreta que un objeto GEOGRAPHY vacío tiene una LineString vacía, lo que creará un bucle completo; es decir, un polígono que cubre toda la Tierra.

Limitaciones

Juntos, los anillos de entrada deben formar un polígono válido:

  • El perímetro del polígono debe cubrir cada uno de los agujeros del polígono.
  • Debe haber solo un perímetro del polígono, que debe ser el primer anillo de entrada. Esto implica que los agujeros del polígono no se pueden anidar.
  • Los anillos del polígono solo pueden cruzarse en un vértice en el límite de ambos anillos.

Cada borde debe abarcar estrictamente menos de 180 grados.

ST_MAKEPOLYGONORIENTED se basa en el orden de los vértices de entrada de cada LineString para determinar la orientación del polígono. Esto se aplica al perímetro del polígono y a los agujeros del polígono. ST_MAKEPOLYGONORIENTED espera que todos los agujeros del polígono tengan la orientación opuesta al perímetro. Consulta ST_MAKEPOLYGON con el fin de obtener más información sobre un constructor de polígonos alternativo y otras restricciones para compilar un polígono válido.

NOTA: Debido al proceso de ajuste de BigQuery, los bordes con una longitud lo bastante corta se descartarán y los dos extremos se unirán en un solo punto. Por lo tanto, es posible que los vértices en una LineString se junten de manera tal que una o más aristas desaparezcan. Entonces, es posible que un agujero del polígono que sea lo bastante pequeño pueda desaparecer, o que el objeto GEOGRAPHY resultante pueda contener solo una línea o un punto.

Tipo de datos que se muestra

GEOGRAPHY

ST_MAXDISTANCE

ST_MAXDISTANCE(geography_1, geography_2[, use_spheroid])

Muestra la distancia más larga en metros entre dos objetos GEOGRAPHY no vacíos; es decir, la distancia entre dos vértices donde el primer vértice está en el primer GEOGRAPHY y el segundo vértice está en el segundo GEOGRAPHY. Si geography_1 y geography_2 son el mismo objeto GEOGRAPHY, la función muestra la distancia entre los dos vértices más distantes en ese GEOGRAPHY.

Si cualquiera de los objetos GEOGRAPHY de entrada está vacío, ST_MAXDISTANCE muestra NULL.

El parámetro opcional use_spheroid determina cómo esta función mide la distancia. Si use_spheroid es FALSE, la función mide la distancia en la superficie de una esfera perfecta.

En la actualidad, el parámetro use_spheroid solo admite el valor FALSE. El valor predeterminado de use_spheroid es FALSE.

Tipo de datos que se muestra

FLOAT64

ST_NPOINTS

ST_NPOINTS(geography_expression)

Description

Un alias de ST_NUMPOINTS.

ST_NUMGEOMETRIES

ST_NUMGEOMETRIES(geography_expression)

Description

Muestra la cantidad de geometrías en la entrada GEOGRAPHY. Para un solo punto, LineString o polígono, ST_NUMGEOMETRIES muestra 1. Para cualquier colección de geometrías, ST_NUMGEOMETRIES muestra la cantidad de geometrías que conforman la colección. ST_NUMGEOMETRIES muestra 0 si la entrada es la GEOGRAPHY vacía.

Tipo de datos que se muestra

INT64

Ejemplo

En el siguiente ejemplo, se calcula ST_NUMGEOMETRIES para una geografía de un solo punto, dos colecciones y una geografía vacía.

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)

Descripción

Muestra la cantidad de vértices del objeto GEOGRAPHY de entrada. Esto incluye la cantidad de puntos, vértices de LineString y vértices del polígono.

NOTA: El primer y último vértice de un anillo del polígono se cuentan como vértices distintos.

Tipo de datos que se muestra

INT64

ST_PERIMETER

ST_PERIMETER(geography_expression[, use_spheroid])

Descripción

Muestra la longitud en metros del límite de los polígonos en el objeto GEOGRAPHY de entrada.

Si geography_expression es un punto o una línea, muestra cero. Si geography_expression es una colección, muestra el perímetro de los polígonos en la colección; si la colección no contiene polígonos, muestra cero.

El parámetro opcional use_spheroid determina cómo esta función mide la distancia. Si use_spheroid es FALSE, la función mide la distancia en la superficie de una esfera perfecta.

En la actualidad, el parámetro use_spheroid solo admite el valor FALSE. El valor predeterminado de use_spheroid es FALSE.

Tipo de datos que se muestra

FLOAT64

ST_POINTN

ST_POINTN(linestring_geography, index)

Description

Muestra el punto N de una geografía de LineString como la geografía de un punto, en la que N es el índice. El índice se basa en 1. Los valores negativos se cuentan hacia atrás desde el final de la LineString, de modo que -1 es el último punto. Muestra un error si la entrada no es una LineString, si la entrada está vacía o si no hay vértices en el índice especificado. Usa el prefijo SAFE a fin de obtener NULL para la entrada no válida en lugar de un error.

Tipo de datos que se muestra

Punto GEOGRAPHY

Ejemplo

En el siguiente ejemplo, se usan ST_POINTN, ST_STARTPOINT y ST_ENDPOINT para extraer puntos de una 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)

Descripción

Muestra una versión simplificada de geography, la entrada GEOGRAPHY determinada. La entrada GEOGRAPHY se simplifica mediante el reemplazo de cadenas casi rectas de aristas cortas con una sola arista larga. La entrada geography no será mayor que la tolerancia especificada por tolerance_meters. Por lo tanto, se garantiza que las aristas simplificadas pasarán dentro de los tolerance_meters de las posiciones originales de todos los vértices que se quitaron de esa arista. El objeto tolerance_meters está en metros sobre la superficie de la Tierra.

Ten en cuenta que ST_SIMPLIFY conserva las relaciones topológicas, lo que significa que no se crearán aristas cruzadas nuevas y el resultado será válido. Para obtener una tolerancia lo suficientemente grande, las formas adyacentes pueden contraerse en un solo objeto, o una forma podría simplificarse a una forma con una dimensión más pequeña.

Limitaciones

Para que ST_SIMPLIFY tenga algún efecto, tolerance_meters no debe ser cero.

ST_SIMPLIFY muestra un error si la tolerancia especificada por tolerance_meters es una de las siguientes:

  • Una tolerancia negativa.
  • Una tolerancia superior a ~7,800 kilómetros

Tipo de datos que se muestra

GEOGRAPHY

Ejemplos

En el siguiente ejemplo se muestra cómo ST_SIMPLIFY simplifica la línea de entrada GEOGRAPHY cuando quita vértices intermedios.

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

En el siguiente ejemplo, se ilustra cómo el resultado de ST_SIMPLIFY puede tener una dimensión menor que la 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)

Descripción

Muestra el objeto GEOGRAPHY de entrada, en el que cada vértice se ajustó a una cuadrícula de longitud/latitud. El tamaño de la cuadrícula está determinado por el parámetro grid_size, que se presenta en grados.

Limitaciones

No se admiten los tamaños de cuadrícula arbitrarios. El parámetro grid_size se redondea para que tenga la forma \(10^n\), donde \(-10 < n < 0\).

Tipo de datos que se muestra

GEOGRAPHY

ST_STARTPOINT

ST_STARTPOINT(linestring_geography)

Description

Muestra el primer punto de una geografía de LineString como una geografía de puntos. Muestra un error si la entrada no es una LineString o si la entrada está vacía. Usa el prefijo SAFE a fin de obtener NULL para la entrada no válida en lugar de un error.

Tipo de datos que se muestra

Punto GEOGRAPHY

Ejemplo

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)

Descripción

Muestra TRUE siempre que se cumplan las dos condiciones siguientes:

  1. geography_1 y geography_2 se intersecan.
  2. El interior de geography_1 y el interior de geography_2 son inconexos.

Tipo de datos que se muestra

BOOL

ST_UNION

ST_UNION(geography_1, geography_2)

ST_UNION(array_of_geography)

Descripción

Muestra un objeto GEOGRAPHY que representa la unión del conjunto de puntos de todos los objetos GEOGRAPHY de entrada.

ST_UNION tiene dos variantes. Para la primera variante, la entrada debe ser de dos objetos GEOGRAPHY. Para la segunda, la entrada es un ARRAY de tipo GEOGRAPHY.

Para la primera variante de ST_UNION, si una de las entradas GEOGRAPHY es NULL, ST_UNION muestra NULL. Para la segunda variante, si el valor de ARRAY de entrada es NULL, ST_UNION muestra NULL. Para un ARRAY de entrada que no sea NULL, la unión se calcula y los elementos de NULL se ignoran para que no afecten el resultado.

Consulta ST_UNION_AGG para ver la versión agregada de ST_UNION.

Tipo de datos que se muestra

GEOGRAPHY

ST_UNION_AGG

ST_UNION_AGG(geography)

Descripción

Muestra un objeto GEOGRAPHY que representa la unión del conjunto de puntos de todos los objetos GEOGRAPHY de entrada.

ST_UNION_AGG ignora los valores GEOGRAPHY de entrada NULL.

Consulta ST_UNION para ver la versión no agregada de ST_UNION_AGG.

Tipo de datos que se muestra

GEOGRAPHY

ST_WITHIN

ST_WITHIN(geography_1, geography_2)

Descripción

Muestra TRUE si ningún punto de geography_1 está fuera de geography_2 y los interiores de geography_1 y geography_2 se intersecan.

Dadas dos geografías a y b, ST_WITHIN(a, b) muestra el mismo resultado que ST_CONTAINS(b, a). Ten en cuenta el orden opuesto de los argumentos.

Tipo de datos que se muestra

BOOL

ST_X

ST_X(geography_expression)

Descripción

Muestra la longitud en grados del objeto GEOGRAPHY de entrada de un solo punto.

Para cualquier objeto GEOGRAPHY de entrada que no sea un punto único, incluido un GEOGRAPHY vacío, ST_X muestra un error. Usa el prefijo SAFE. para obtener NULL.

Tipo de datos que se muestra

FLOAT64

Ejemplo

En el siguiente ejemplo, se usan ST_X y ST_Y para extraer coordenadas de geografías de un solo punto.

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)

Descripción

Muestra la latitud en grados del objeto GEOGRAPHY de entrada de un solo punto.

Para cualquier objeto GEOGRAPHY de entrada que no sea un punto único, incluido un GEOGRAPHY vacío, ST_Y muestra un error. Usa el prefijo SAFE. para mostrar NULL en su lugar.

Tipo de datos que se muestra

FLOAT64

Ejemplo

Consulta ST_X para ver un ejemplo de uso.