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 accidentes geográficos y construir o manipular objetos GEOGRAPHY.

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

Constructores: funciones que crean nuevos valores GEOGRAPHY a partir de coordenadas o de objetos GEOGRAPHY existentes, como ST_GEOGPOINT.
Analizadores: funciones que crean objetos GEOGRAPHY a partir de un formato externo como WKT y GeoJSON. Por ejemplo, con ST_GEOGFROMTEXT, se crea un GEOGRAPHY a partir de WKT.
Formateadores: funciones que exportan GEOGRAPHY a un formato externo como WKT y GeoJSON. Por ejemplo, ST_ASTEXT convierte el formato de GEOGRAPHY en WKT.
Transformaciones: funciones que generan un objeto GEOGRAPHY nuevo a partir de otros que se adhieren a alguna propiedad. Los ejemplos incluyen ST_INTERSECTION y ST_BOUNDARY.
Predicados: funciones que muestran TRUE o FALSE para alguna relación espacial entre dos objetos GEOGRAPHY o alguna propiedad de una geografía. Por lo general, estas funciones se usan en cláusulas de filtro. Por ejemplo, ST_DWITHIN es un predicado.
Descriptores de acceso: funciones que proporcionan acceso a las propiedades de un objeto GEOGRAPHY sin efectos secundarios, como ST_NUMPOINTS.
Medidas: funciones que calculan medidas de uno o más objetos GEOGRAPHY, por ejemplo, ST_DISTANCE.
Funciones agregadas: funciones agregadas específicas de la geografía, como ST_UNION_AGG.

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

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_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 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, 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)

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, 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 es NULL, ST_MAKEPOLYGONORIENTED muestra NULL.

NOTA: El argumento de entrada para ST_MAKEPOLYGONORIENTED puede contener un objeto GEOGRAPHY vacío. 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_GEOGFROMGEOJSON

ST_GEOGFROMGEOJSON(geojson_string)

Descripción

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

ST_GEOGFROMGEOJSON acepta entradas que cumplan con RFC 7946.

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

ST_GEOGFROMTEXT(wkt_string)

ST_GEOGFROMTEXT(wkt_string, oriented)

Descripción

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 los bordes y sistemas de coordenadas.

Tipo de datos que se muestra

GEOGRAPHY

Ejemplo

La siguiente consulta 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, FALSE), ST_GEOGPOINT(1, 1)) AS non_oriented,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, TRUE),  ST_GEOGPOINT(1, 1)) AS oriented
FROM polygon;

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

ST_GEOGFROMWKB

ST_GEOGFROMWKB(wkb_bytes)

Descripción

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

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_GEOGPOINTFROMGEOHASH

ST_STGEOGPOINTFROMGEOHASH(geohash)

Descripción

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_ASGEOJSON

ST_ASGEOJSON(geography_expression)

Descripción

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

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)

Descripción

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_GEOHASH

ST_GEOHASH(geography_expression, maxchars)

Descripción

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.

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

Tipo de datos que se muestra

STRING

ST_ASBINARY

ST_ASBINARY(geography_expression)

Descripción

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

ST_CLOSESTPOINT(geography_1, geography_2)

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

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

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 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 vacío.

Consulta ST_INTERSECTS, ST_DISJOINT para ver funciones de predicado relacionadas.

Tipo de datos que se muestra

GEOGRAPHY

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_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 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 un objeto GEOGRAPHY de entrada es NULL, muestra NULL. Para la segunda variante, si el valor de ARRAY de entrada es NULL, muestra NULL. Para un ARRAY de entrada no NULL, se calcula la unión y los elementos NULL se ignoran, de manera 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_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 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 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.

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

GEOGRAPHY

ST_DWITHIN

ST_DWITHIN(geography_1, geography_2, distance)

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_EQUALS

ST_EQUALS(geography_1, geography_2)

Descripción

Muestra TRUE si geography_1 y geography_2 representan el mismo valor GEOGRAPHY. Más precisamente, 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_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 mínima y máxima que delimitan al 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

ST_TOUCHES

ST_TOUCHES(geography_1, geography_2)

Descripción

Muestra TRUE siempre que se cumplan las dos condiciones siguientes:

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

Tipo de datos que se muestra

BOOL

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_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_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_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 el objeto GEOGRAPHY de entrada está vacío, ST_DIMENSION muestra -1.

Tipo de datos que se muestra

INT64

ST_NUMPOINTS

ST_NUMPOINTS(geography_expression)

Descripción

Muestra la cantidad de vértices en el objeto GEOGRAPHY de entrada. Esto incluye la cantidad de puntos, vértices de LineString y vértices de 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_AREA

ST_AREA(geography_expression)

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_DISTANCE

ST_DISTANCE(geography_1, geography_2)

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_LENGTH

ST_LENGTH(geography_expression)

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_MAXDISTANCE

ST_MAXDISTANCE(geography_1, geography_2)

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 y el segundo vértice está en el segundo . Si geography_1 y geography_2 son el mismo objeto , la función muestra la distancia entre los dos vértices más distantes en ese .

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_PERIMETER

ST_PERIMETER(geography_expression)

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

ST_CENTROID_AGG(geography)

Descripción

Calcula el centroide del conjunto de objetos GEOGRAPHY de entrada como un 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)      |
+-----------------+