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_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_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_ISCOLLECTION ST_ISEMPTY ST_NPOINTS ST_NUMPOINTS 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_AREA 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_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_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_ASGEOJSON
ST_ASGEOJSON(geography_expression)
Descripción
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)
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_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 deGEOGRAPHY
que está agrupada en clústeres.epsilon
: La épsilon que especifica el radio, medido en metros, alrededor de un valor principal. ValorFLOAT64
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. ValorINT64
no negativo.OVER
: Especifica una ventana. Consulta Funciones analíticas. El uso de la cláusulaOVER
conST_CLUSTERDBSCAN
es compatible con los siguientes elementos:PARTITION BY
: OpcionalORDER BY
: Opcionalwindow_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íasminimum_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 distanciaepsilon
. 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 distanciaepsilon
. - 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 distanciaepsilon
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
. UnaGEOGRAPHY
vacía siempre se clasifica como ruido.
Limitaciones
- El argumento
minimum_geographies
es unINT64
no negativo, yepsilon
es unFLOAT64
no negativo. - El objeto de geografía
EMPTY
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
muestraNULL
si la entrada esNULL
o laGEOGRAPHY
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
.
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_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_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_GEOGFROMGEOJSON
ST_GEOGFROMGEOJSON(geojson_string [, make_valid => constant_expression])
Descripción
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
yGeometryCollection
. Cualquier otro tipo de GeoJSON, comoFeature
oFeatureCollection
, 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 decoordinates
.
Tipo de datos que se muestra
GEOGRAPHY
ST_GEOGFROMTEXT
Firma 1
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 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 sufijoM
. - 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, 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 |
+-------------------+---------------+-----------+
Firma 2
ST_GEOGFROMTEXT(wkt_string[, oriented => boolean_constant_1]
[, planar => boolean_constant_2] [, make_valid => boolean_constant_3])
Descripción
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 usarST_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 sufijoM
. - 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
yplanar
no pueden ser iguales aTRUE
al mismo tiempo.oriented
ymake_valid
no pueden ser iguales aTRUE
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)
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_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)
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_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_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 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_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)
Descripción
Un alias de ST_NUMPOINTS.
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_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_TOUCHES
ST_TOUCHES(geography_1, geography_2)
Descripción
Muestra TRUE
siempre que se cumplan las dos condiciones siguientes:
geography_1
ygeography_2
se intersecan.- El interior de
geography_1
y el interior degeography_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.