Les fonctions de géographie effectuent des opérations sur des valeurs GEOGRAPHY
BigQuery ou en génèrent. La signature de toute fonction de géographie commence par ST_
. BigQuery accepte les fonctions ci-après, qui peuvent être utilisées pour analyser des données géographiques, déterminer les relations spatiales entre des éléments géographiques, et construire ou manipuler des valeurs GEOGRAPHY
.
Toutes les fonctions de géographie de BigQuery renvoient NULL
si l'un des arguments d'entrée est NULL
.
Catégories
Les fonctions de géographie sont regroupées dans les catégories suivantes en fonction de leur comportement :
Catégorie | Fonctions | Description |
Constructeurs |
ST_GEOGPOINT ST_MAKELINE ST_MAKEPOLYGON ST_MAKEPOLYGONORIENTED
|
Fonctions créant de nouvelles valeurs géographiques à partir de coordonnées ou de zones géographiques existantes. |
Analyseurs |
ST_GEOGFROM ST_GEOGFROMGEOJSON ST_GEOGFROMTEXT ST_GEOGFROMWKB ST_GEOGPOINTFROMGEOHASH |
Fonctions créant des zones géographiques à partir d'un format externe tel que WKT et GeoJSON. |
Outils de mise en forme |
ST_ASBINARY ST_ASGEOJSON ST_ASTEXT ST_GEOHASH
|
Fonctions exportant des zones géographiques vers un format externe tel que WKT. |
Transformations |
ST_BOUNDARY ST_BUFFER ST_BUFFERWITHTOLERANCE ST_CENTROID ST_CENTROID_AGG (Agrégation)ST_CLOSESTPOINT ST_CONVEXHULL ST_DIFFERENCE ST_DUMP ST_EXTERIORRING ST_INTERIORRINGS ST_INTERSECTION ST_SIMPLIFY ST_SNAPTOGRID ST_UNION ST_UNION_AGG (Agrégation) |
Fonctions générant une nouvelle zone géographique en fonction de l'entrée. |
Accesseurs |
ST_DIMENSION ST_DUMP ST_ENDPOINT ST_GEOMETRYTYPE ST_ISCOLLECTION ST_ISEMPTY ST_NPOINTS ST_NUMGEOMETRIES ST_NUMPOINTS ST_POINTN ST_STARTPOINT ST_X ST_Y |
Fonctions permettant d'accéder aux propriétés d'une zone géographique sans effets secondaires. |
Prédicats |
ST_CONTAINS ST_COVEREDBY ST_COVERS ST_DISJOINT ST_DWITHIN ST_EQUALS ST_INTERSECTS ST_INTERSECTSBOX ST_TOUCHES ST_WITHIN |
Fonctions renvoyant TRUE ou FALSE pour une relation spatiale entre deux zones géographiques ou pour une propriété d'une zone géographique. Ces fonctions sont couramment utilisées dans les clauses de filtre.
|
Évaluations |
ST_ANGLE ST_AREA ST_AZIMUTH ST_BOUNDINGBOX ST_DISTANCE ST_EXTENT (Agrégation)ST_LENGTH ST_MAXDISTANCE ST_PERIMETER |
Fonctions calculant les mesures d'une ou de plusieurs zones géographiques. |
Filtrage par cluster |
ST_CLUSTERDBSCAN
|
Fonctions effectuant un clustering sur des zones géographiques. |
Fonctions S2 |
S2_CELLIDFROMPOINT S2_COVERINGCELLIDS |
Fonctions permettant d'utiliser des couvertures de cellule S2 de GEOGRAPHY. |
S2_CELLIDFROMPOINT
S2_CELLIDFROMPOINT(point_geography[, level => cell_level])
Description
Renvoie l'ID de cellule S2 couvrant un point GEOGRAPHY
.
- Le
INT64
paramètrelevel
facultatif spécifie le niveau de cellule S2 pour la cellule renvoyée. Nommer cet argument est facultatif.
Il s'agit d'une fonctionnalité avancée d'interopérabilité avec les systèmes utilisant la bibliothèque Geometry S2.
Contraintes
- Renvoie l'ID de cellule sous la forme d'un
INT64
équivalent à un nombre entier non signé de 64 bits. - Peut renvoyer des ID de cellule négatifs.
- Les niveaux de cellule S2 valides sont compris entre 0 et 30.
- La valeur par défaut de
level
est 30 si elle n'est pas spécifiée explicitement. - La fonction n'accepte que des valeurs GEOGRAPHY à un seul point. Utilisez le préfixe
SAFE
si l'entrée peut être un multipoint, une polyligne, un polygone ou unGEOGRAPHY
vide. - Pour calculer la couverture d'un élément
GEOGRAPHY
complexe, utilisez S2_COVERINGCELLIDS.
Type renvoyé
INT64
Exemple
WITH data AS (
SELECT 1 AS id, ST_GeogPoint(-122, 47) AS geo
UNION ALL
-- empty geography is not supported
SELECT 2 AS id, ST_GeogFromText('POINT EMPTY') AS geo
UNION ALL
-- only points are supported
SELECT 3 AS id, ST_GeogFromText('LINESTRING(1 2, 3 4)') AS geo
)
SELECT id,
SAFE.S2_CellIdFromPoint(geo) cell30,
SAFE.S2_CellIdFromPoint(geo, level => 10) cell10
FROM data;
+----+---------------------+---------------------+
| id | cell30 | cell10 |
+----+---------------------+---------------------+
| 1 | 6093613931972369317 | 6093613287902019584 |
| 2 | NULL | NULL |
| 3 | NULL | NULL |
+----+---------------------+---------------------+
S2_COVERINGCELLIDS
S2_COVERINGCELLIDS(
geography
[, min_level => cell_level]
[, max_level => cell_level]
[, max_cells => max_cells]
[, buffer => buffer])
Description
Renvoie un tableau d'ID de cellule S2 couvrant l'entrée GEOGRAPHY
. La fonction renvoie un maximum de max_cells
cellules. Les arguments facultatifs min_level
et max_level
spécifient les niveaux minimal et maximal pour les cellules S2 renvoyées. La taille du tableau est limitée par l'argument facultatif max_cells
. L'argument facultatif buffer
spécifie un facteur de zone tampon en mètres. La région couverte est élargie de ce facteur à partir de la zone géographique d'entrée.
Il s'agit d'une fonctionnalité avancée d'interopérabilité avec les systèmes utilisant la bibliothèque Geometry S2.
Contraintes
- Renvoie l'ID de cellule sous la forme d'un
INT64
équivalent à un nombre entier non signé de 64 bits. - Peut renvoyer des ID de cellule négatifs.
- Les niveaux de cellule S2 valides sont compris entre 0 et 30.
- La valeur par défaut de
max_cells
est 8 si elle n'est pas explicitement spécifiée. - La valeur de
buffer
ne doit pas être négative. La valeur par défaut est de 0,0 mètre si elle n'est pas explicitement spécifiée.
Type renvoyé
ARRAY<INT64>
Exemple
WITH data AS (
SELECT 1 AS id, ST_GeogPoint(-122, 47) AS geo
UNION ALL
SELECT 2 AS id, ST_GeogFromText('POINT EMPTY') AS geo
UNION ALL
SELECT 3 AS id, ST_GeogFromText('LINESTRING(-122.12 47.67, -122.19 47.69)') AS geo
)
SELECT id, S2_CoveringCellIDs(geo, min_level => 12) cells
FROM data;
+----+--------------------------------------------------------------------------------------+
| id | cells |
+----+--------------------------------------------------------------------------------------+
| 1 | [6093613931972369317] |
| 2 | [] |
| 3 | [6093384954555662336, 6093390709811838976, 6093390735581642752, 6093390740145045504, |
| | 6093390791416217600, 6093390812891054080, 6093390817187069952, 6093496378892222464] |
+----+--------------------------------------------------------------------------------------+
ST_ANGLE
ST_ANGLE(point_geography_1, point_geography_2, point_geography_3)
Description
Prend trois valeurs GEOGRAPHY
à trois points, qui représentent deux lignes croisées.
Renvoie l'angle entre ces lignes. Le point 2 et le point 1 représentent la première ligne, tandis que le point 2 et le point 3 représentent la deuxième ligne. L'angle entre ces lignes est exprimé en radians, dans la plage [0, 2pi)
. L'angle est mesuré dans le sens des aiguilles d'une montre entre la première et la deuxième ligne.
ST_ANGLE
présente les cas suivants :
- Si les points 2 et 3 sont identiques, renvoie
NULL
. - Si les points 2 et 1 sont identiques, la fonction renvoie
NULL
. - Si les points 2 et 3 sont exactement des antipodes, la fonction renvoie
NULL
. - Si les points 2 et 1 sont exactement un antipodal, la fonction renvoie
NULL
. - Si l'une des zones géographiques d'entrée ne correspond pas à un point unique ou si elle est vide, une erreur est générée.
Type renvoyé
FLOAT64
Exemple
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])
Description
Renvoie l'aire, exprimée en mètres carrés, couverte par les polygones dans la valeur GEOGRAPHY
d'entrée.
Si geography_expression
est un point ou une ligne, renvoie zéro. Si geography_expression
est une collection, renvoie l'aire des polygones que celle-ci contient. Si la collection ne contient pas de polygones, renvoie zéro.
Le paramètre use_spheroid
facultatif détermine la manière dont cette fonction mesure la distance. Si la valeur de use_spheroid
est FALSE
, la fonction mesure la distance sur la surface d'une sphère parfaite.
Actuellement, le paramètre use_spheroid
n'accepte que la valeur FALSE
. La valeur par défaut de use_spheroid
est FALSE
.
Type renvoyé
FLOAT64
ST_ASBINARY
ST_ASBINARY(geography_expression)
Description
Renvoie la représentation WKB d'une valeur GEOGRAPHY
d'entrée.
Consultez la section sur la fonction ST_GEOGFROMWKB
pour construire une valeur GEOGRAPHY
à partir de WKB.
Type renvoyé
BYTES
ST_ASGEOJSON
ST_ASGEOJSON(geography_expression)
Description
Renvoie la représentation GeoJSON conforme à la norme RFC 7946 pour la valeur GEOGRAPHY
d'entrée.
Une valeur GEOGRAPHY
BigQuery a des arêtes géodésiques sphériques, tandis qu'un objet Geometry
GeoJSON a explicitement des arêtes planes.
Pour effectuer la conversion entre ces deux types d'arêtes, BigQuery ajoute des points supplémentaires à la ligne si nécessaire, de sorte que la séquence d'arêtes résultante reste à moins de 10 mètres de l'arête d'origine.
Consultez la section sur la fonction ST_GEOGFROMGEOJSON
pour construire une valeur GEOGRAPHY
à partir de GeoJSON.
Type renvoyé
STRING
ST_ASTEXT
ST_ASTEXT(geography_expression)
Description
Renvoie la représentation WKT d'une valeur GEOGRAPHY
d'entrée.
Consultez la section sur la fonction ST_GEOGFROMTEXT
pour construire une valeur GEOGRAPHY
à partir de WKT.
Type renvoyé
STRING
ST_AZIMUTH
ST_AZIMUTH(point_geography_1, point_geography_2)
Description
Prend deux valeurs GEOGRAPHY
de point et renvoie l'azimut du segment de ligne formé par les points 1 et 2. L'azimut correspond à l'angle en radians mesuré entre la ligne du point 1 faisant face au Nord réel au segment de ligne du point 1 au point 2.
L'angle positif est mesuré dans le sens des aiguilles d'une montre sur la surface d'une sphère. Par exemple, l'azimut d'un segment de ligne :
- Le pointage vers le Nord est
0
- Vers l'Est :
PI/2
- Vers le Sud :
PI
- Vers l'Ouest :
3PI/2
ST_AZIMUTH
présente les cas suivants :
- Si les deux points d'entrée sont identiques, il renvoie
NULL
. - Si les deux points d'entrée sont exactement antipodaux, renvoie
NULL
. - Si l'une des zones géographiques d'entrée ne correspond pas à des points uniques ou est une zone vide, une erreur est générée.
Type renvoyé
FLOAT64
Exemple
WITH geos AS (
SELECT 1 id, st_geogpoint(1, 0) geo1, st_geogpoint(0, 0) geo2 UNION ALL
SELECT 2, st_geogpoint(0, 0), st_geogpoint(1, 0) UNION ALL
SELECT 3, st_geogpoint(0, 0), st_geogpoint(0, 1) UNION ALL
-- identical
SELECT 4, st_geogpoint(0, 0) geo1, st_geogpoint(0, 0) geo2 UNION ALL
-- antipode
SELECT 5, st_geogpoint(-30, 0), st_geogpoint(150, 0) UNION ALL
-- nulls
SELECT 6, st_geogpoint(0, 0), null UNION ALL
SELECT 7, null, st_geogpoint(0, 0))
SELECT ST_AZIMUTH(geo1, geo2) AS azimuth FROM geos ORDER BY id;
+--------------------+
| azimuth |
+--------------------+
| 4.71238898038469 |
| 1.5707963267948966 |
| 0 |
| NULL |
| NULL |
| NULL |
| NULL |
+--------------------+
ST_BOUNDARY
ST_BOUNDARY(geography_expression)
Description
Renvoie une seule valeur GEOGRAPHY
contenant l'union des limites de chaque composant dans la valeur GEOGRAPHY
d'entrée donnée.
La limite de chaque composant d'une valeur GEOGRAPHY
est définie comme suit :
- La limite d'un point est vide.
- La limite d'une polyligne est constituée des extrémités de cette dernière.
- La limite d'un polygone est constituée des polylignes qui forment l'enveloppe du polygone et de chacun des trous de ce dernier.
Type renvoyé
GEOGRAPHY
ST_BOUNDINGBOX
ST_BOUNDINGBOX(geography_expression)
Description
Renvoie un STRUCT
qui représente le cadre de délimitation de la zone géographique spécifiée.
Le cadre de délimitation est le rectangle minimal qui entoure la zone géographique. Les arêtes du rectangle suivent des lignes constantes de longitude et de latitude.
Mises en garde :
- Renvoie
NULL
si l'entrée estNULL
ou une zone géographique vide. - Le cadre de délimitation peut dépasser l'antiméridien si cela permet un rectangle plus petit. Dans ce cas, le cadre de délimitation possède l'une de ses limites longitudinales en dehors de la plage [-180, 180], de sorte que
xmin
soit inférieur à la valeur la plus est par rapport àxmax
.
Type renvoyé
STRUCT<xmin FLOAT64, ymin FLOAT64, xmax FLOAT64, ymax FLOAT64>
.
Parties de cadre de délimitation :
xmin
: ligne de longitude constante la plus ouest qui délimite le rectangle.xmax
: ligne de longitude constante la plus est qui délimite le rectangle.ymin
: ligne de latitude constante minimale qui délimite le rectangle.ymax
: ligne de latitude constante maximale qui délimite le rectangle.
Exemple
WITH data AS (
SELECT 1 id, ST_GEOGFROMTEXT('polygon((-125 48, -124 46, -117 46, -117 49, -125 48))') g
UNION ALL
SELECT 2 id, ST_GEOGFROMTEXT('polygon((172 53, -130 55, -141 70, 172 53))') g
UNION ALL
SELECT 3 id, ST_GEOGFROMTEXT('point empty') g
UNION ALL
SELECT 4 id, ST_GEOGFROMTEXT('polygon((172 53, -141 70, -130 55, 172 53))', oriented => TRUE)
)
SELECT id, ST_BOUNDINGBOX(g) AS box
FROM data
+----+------------------------------------------+
| id | box |
+----+------------------------------------------+
| 1 | {xmin:-125, ymin:46, xmax:-117, ymax:49} |
| 2 | {xmin:172, ymin:53, xmax:230, ymax:70} |
| 3 | NULL |
| 4 | {xmin:-180, ymin:-90, xmax:180, ymax:90} |
+----+------------------------------------------+
Pour en savoir plus sur la version agrégée de ST_BOUNDINGBOX, consultez la section sur la fonction ST_EXTENT
.
ST_BUFFER
ST_BUFFER(
geography,
buffer_radius
[, num_seg_quarter_circle => num_segments]
[, use_spheroid => boolean_expression]
[, endcap => endcap_style]
[, side => line_side])
Description
Renvoie une valeur GEOGRAPHY
qui représente le tampon autour de la valeur GEOGRAPHY
d'entrée.
Cette fonction est semblable à ST_BUFFERWITHTOLERANCE
, mais vous spécifiez le nombre de segments au lieu de fournir une tolérance pour déterminer dans quelle mesure la zone géographique résultante peut être différente du rayon de tampon idéal.
geography
: valeurGEOGRAPHY
d'entrée pour entourer le rayon de tampon.buffer_radius
:DOUBLE
représente le rayon du tampon autour de la zone géographique d'entrée. Le rayon est exprimé en mètres. Notez que les polygones se contractent lorsqu'ils sont mis en mémoire tampon avec un opérateurbuffer_radius
négatif. Les interfaces système et les trous de polygone contractés dans un point sont supprimés.num_seg_quarter_circle
(facultatif) :DOUBLE
spécifie le nombre de segments utilisés pour effectuer une approximative d'un cercle de trimestre. La valeur par défaut est8.0
. Nommer cet argument est facultatif.endcap
(facultatif) :STRING
vous permet de spécifier l'un des deux styles de fin :ROUND
etFLAT
. La valeur par défaut estROUND
. Cette option n'affecte que les extrémités des polylignes mis en mémoire tampon.side
(facultatif) :STRING
permet de spécifier l'une des trois possibilités de lignes:BOTH
,LEFT
etRIGHT
. La valeur par défaut estBOTH
. Cette option n'affecte que les mises en mémoire tampon des polylignes.use_spheroid
(facultatif) :BOOL
détermine la manière dont cette fonction mesure la distance. Si la valeur deuse_spheroid
estFALSE
, la fonction mesure la distance sur la surface d'une sphère parfaite. Actuellement, le paramètreuse_spheroid
n'accepte que la valeurFALSE
. La valeur par défaut deuse_spheroid
estFALSE
.
Type renvoyé
GEOGRAPHY
Exemple
L'exemple suivant montre le résultat de ST_BUFFER
sur un point. Un point mis en mémoire tampon est un cercle approximatif. Lorsque num_seg_quarter_circle = 2
, il existe deux segments de ligne dans un cercle de trimestre, donc le cercle mis en mémoire tampon a huit côtés et ST_NUMPOINTS
renvoie neuf sommets. Lorsque num_seg_quarter_circle = 8
, il existe huit segments de ligne dans un cercle de trimestre, donc le cercle mis en mémoire tampon a 32 côtés et ST_NUMPOINTS
renvoie 33 sommets.
SELECT
-- num_seg_quarter_circle=2
ST_NumPoints(ST_Buffer(ST_GeogFromText('POINT(1 2)'), 50, 2)) AS eight_sides,
-- num_seg_quarter_circle=8, since 8 is the default
st_NumPoints(ST_Buffer(ST_GeogFromText('POINT(100 2)'), 50)) AS thirty_two_sides;
+-------------+------------------+
| eight_sides | thirty_two_sides |
+-------------+------------------+
| 9 | 33 |
+-------------+------------------+
ST_BUFFERWITHTOLERANCE
ST_BUFFERWITHTOLERANCE(
geography,
buffer_radius,
tolerance_meters => tolernace
[, use_spheroid => boolean_expression]
[, endcap => endcap_style]
[, side => line_side])
Renvoie une valeur GEOGRAPHY
qui représente le tampon autour de la valeur GEOGRAPHY
d'entrée.
Cette fonction est semblable à ST_BUFFER
, à la différence que vous fournissez une tolérance au lieu de segments pour déterminer dans quelle mesure la zone géographique résultante peut être différente du rayon de tampon idéal.
geography
: valeurGEOGRAPHY
d'entrée pour entourer le rayon de tampon.buffer_radius
:DOUBLE
représente le rayon du tampon autour de la zone géographique d'entrée. Le rayon est exprimé en mètres. Notez que les polygones se contractent lorsqu'ils sont mis en mémoire tampon avec un opérateurbuffer_radius
négatif. Les interfaces système et les trous de polygone contractés dans un point sont supprimés.tolerance_meters
:DOUBLE
spécifie une tolérance en mètres avec laquelle la forme est approximative. La tolérance détermine combien un polygone peut s'écarter du rayon idéal. Nommer cet argument est facultatif.endcap
(facultatif) :STRING
vous permet de spécifier l'un des deux styles de fin :ROUND
etFLAT
. La valeur par défaut estROUND
. Cette option n'affecte que les extrémités des polylignes mis en mémoire tampon.side
(facultatif) :STRING
vous permet de spécifier l'un des trois styles de ligne possibles :BOTH
,LEFT
etRIGHT
. La valeur par défaut estBOTH
. Cette option n'affecte que les extrémités des polylignes mis en mémoire tampon.use_spheroid
(facultatif) :BOOL
détermine la manière dont cette fonction mesure la distance. Si la valeur deuse_spheroid
estFALSE
, la fonction mesure la distance sur la surface d'une sphère parfaite. Actuellement, le paramètreuse_spheroid
n'accepte que la valeurFALSE
. La valeur par défaut deuse_spheroid
estFALSE
.
Type renvoyé
GEOGRAPHY
Exemple
L'exemple suivant montre les résultats de ST_BUFFERWITHTOLERANCE
sur un point, avec deux valeurs différentes pour la tolérance, mais avec le même rayon de tampon de 100
. Un point mis en mémoire tampon est un cercle approximatif. Lorsque tolerance_meters=25
, la tolérance est un pourcentage élevé du rayon de tampon. Par conséquent, seuls cinq segments sont utilisés pour effectuer une approximative d'un cercle autour du point d'entrée. Lorsque tolerance_meters=1
, la tolérance est un pourcentage beaucoup plus faible du rayon de tampon. Par conséquent, 24 arêtes sont utilisées pour effectuer une approximative d'un cercle autour du point d'entrée.
SELECT
-- tolerance_meters=25, or 25% of the buffer radius.
ST_NumPoints(ST_BufferWithTolerance(ST_GeogFromText('POINT(1 2)'), 100, 25)) AS five_sides,
-- tolerance_meters=1, or 1% of the buffer radius.
st_NumPoints(ST_BufferWithTolerance(ST_GeogFromText('POINT(100 2)'), 100, 1)) AS twenty_four_sides;
+------------+-------------------+
| five_sides | twenty_four_sides |
+------------+-------------------+
| 6 | 24 |
+------------+-------------------+
ST_CENTROID
ST_CENTROID(geography_expression)
Description
Renvoie le centroïde de la valeur GEOGRAPHY
d'entrée sous la forme d'une valeur GEOGRAPHY
à un seul point.
Le centroïde d'une valeur GEOGRAPHY
est la moyenne pondérée des centroïdes des composants ayant la dimension la plus élevée dans la valeur GEOGRAPHY
. Le centroïde des composants dans chaque dimension est défini comme suit :
- Le centroïde des points correspond à la moyenne arithmétique des coordonnées en entrée.
- Le centroïde des polylignes correspond au centroïde de toutes les arêtes pondérées par la longueur. Le centroïde de chaque arête est le milieu géodésique de l'arête.
- Le centroïde d'un polygone est son centre de masse.
Si la valeur GEOGRAPHY
d'entrée est vide, une valeur GEOGRAPHY
vide est renvoyée.
Contraintes
Dans le cas peu probable où le centroïde d'une valeur GEOGRAPHY
ne peut pas être défini par un seul point situé sur la surface de la Terre, un point déterministe mais arbitraire est renvoyé. Cela ne peut se produire que si le centroïde est exactement au centre de la Terre, par exemple dans le cas du centroïde d'une paire de points antipodaux, et la probabilité que cela se produise est extrêmement faible.
Type renvoyé
GEOGRAPHY
ST_CENTROID_AGG
ST_CENTROID_AGG(geography)
Description
Calcule le centroïde de l'ensemble de valeurs GEOGRAPHY
d'entrée sous la forme d'une valeur GEOGRAPHY
à un seul point.
Le centroïde de l'ensemble de valeurs GEOGRAPHY
d'entrée est la moyenne pondérée du centroïde de chaque valeur GEOGRAPHY
individuelle. Seules les valeurs GEOGRAPHY
ayant la dimension la plus élevée présentes dans l'entrée contribuent au centroïde de l'ensemble entier. Par exemple, si l'entrée contient à la fois des valeurs GEOGRAPHY
avec des lignes et des valeurs GEOGRAPHY
ne contenant que des points, ST_CENTROID_AGG
renvoie la moyenne pondérée des valeurs GEOGRAPHY
avec des lignes, car celles-ci ont la dimension maximale. Dans cet exemple, ST_CENTROID_AGG
ignore les valeurs GEOGRAPHY
ne contenant que des points lors du calcul du centroïde agrégé.
ST_CENTROID_AGG
ignore les valeurs GEOGRAPHY
d'entrée NULL
.
Pour en savoir plus sur la version non agrégée de ST_CENTROID_AGG
et sur la définition du centroïde d'une valeur GEOGRAPHY
individuelle, consultez la section sur la fonction ST_CENTROID
.
Type renvoyé
GEOGRAPHY
Exemple
Les requêtes suivantes calculent le centroïde agrégé sur un ensemble de valeurs GEOGRAPHY
. L'entrée de la première requête ne contient que des points. Par conséquent, chaque valeur contribue au centroïde agrégé. Notez également que ST_CENTROID_AGG
n'équivaut pas à appeler ST_CENTROID
sur le résultat de ST_CENTROID_AGG
. Les doubles sont supprimés par l'opération d'union, ce qui n'est pas le cas avec la fonction ST_UNION_AGG
. L'entrée de la seconde requête a des dimensions mixtes, et seules les valeurs ayant la dimension la plus élevée de l'ensemble, c'est-à-dire les lignes, affectent le centroïde agrégé.
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])
Description
Renvoie une valeur GEOGRAPHY
contenant un point sur geography_1
situé à la distance la plus faible possible de geography_2
. Cela implique que la distance entre le point renvoyé par ST_CLOSESTPOINT
et geography_2
est inférieure ou égale à la distance entre tout autre point sur geography_1
et geography_2
.
Si l'une des valeurs GEOGRAPHY
d'entrée est vide, ST_CLOSESTPOINT
renvoie NULL
.
Le paramètre use_spheroid
facultatif détermine la manière dont cette fonction mesure la distance. Si la valeur de use_spheroid
est FALSE
, la fonction mesure la distance sur la surface d'une sphère parfaite.
Actuellement, le paramètre use_spheroid
n'accepte que la valeur FALSE
. La valeur par défaut de use_spheroid
est FALSE
.
Type renvoyé
GEOGRAPHY
ST_CLUSTERDBSCAN
ST_CLUSTERDBSCAN(geography_column, epsilon, minimum_geographies)
OVER over_clause
over_clause:
{ named_window | ( [ window_specification ] ) }
window_specification:
[ named_window ]
[ PARTITION BY partition_expression [, ...] ]
[ ORDER BY expression [ { ASC | DESC } ] [, ...] ]
Effectue un partitionnement DBSCAN sur une colonne de zones géographiques. Renvoie un numéro de cluster basé sur 0.
Pour en savoir plus sur la clause OVER
et son utilisation, consultez la page Appels de fonctions de fenêtrage.
Paramètres d'entrée
geography_column
: une colonne de zones géographiques (GEOGRAPHY
) en cluster.epsilon
: valeur epsilon spécifiant le rayon, exprimé en mètres, autour d'une valeur centrale. Il s'agit d'une valeurFLOAT64
non négative.minimum_geographies
: spécifie le nombre minimal de zones géographiques au sein d'un même cluster. Seules les entrées denses constituent un cluster, sinon elles sont classées comme bruit. Il s'agit d'une valeurINT64
non négative.
Types de zones géographiques et algorithme DBSCAN
L'algorithme DBSCAN identifie les clusters de données à haute densité et marque les anomalies dans les zones de bruit, à faible densité. Les zones géographiques transmises via geography_column
sont classées par l'algorithme DBSCAN dans l'une des trois catégories suivantes :
- Valeur centrale : une zone géographique est une valeur centrale si elle se trouve à une distance inférieure à
epsilon
de la valeurminimum_geographies
d'une zone géographique, y compris la sienne. La valeur centrale démarre un nouveau cluster ou est ajoutée au cluster associé à une valeur centrale située à une distance inférieure àepsilon
. Les valeurs centrales sont regroupées au sein d'un cluster avec toutes les autres valeurs centrales et frontières situées à une distance inférieure àepsilon
. - Valeur frontière : une zone géographique est une valeur frontière si elle se situe à une distance inférieure à epsilon d'une valeur centrale. Elle est ajoutée au cluster associé à une valeur centrale située à une distance inférieure à
epsilon
. Une valeur frontière peut se trouver à une distance inférieure àepsilon
de plusieurs clusters. Dans ce cas, elle peut être assignée de manière arbitraire à l'un des clusters, et la fonction produit un résultat identique pour les appels suivants. - Bruit : une zone géographique est considérée comme bruit s'il ne s'agit ni d'une valeur centrale, ni d'une valeur frontière.
Les valeurs de bruit sont attribuées à un cluster
NULL
. Une valeurGEOGRAPHY
vide est toujours classée comme bruit.
Contraintes
- L'argument
minimum_geographies
est une valeurINT64
non négative etepsilon
une valeurFLOAT64
non négative. - Une zone géographique vide ne peut être associée à aucun cluster.
- Il est possible qu'une valeur frontière puisse être associée à plusieurs clusters. Si une zone géographique est classée comme valeur frontière,
ST_CLUSTERDBSCAN
l'attribue à un cluster arbitraire valide.
Type renvoyé
INT64
pour chaque zone géographique dans la colonne des zones géographiques.
Exemples
Cet exemple effectue un partitionnement DBSCAN avec un rayon de 100 000 mètres et un argument minimum_geographies
ayant comme valeur 1. Les zones géographiques analysées sont une combinaison de points, de lignes et de polygones.
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)
Description
Renvoie TRUE
si aucun point de geography_2
n'est en dehors de geography_1
et que les intérieurs s'entrecroisent. Sinon, renvoie FALSE
.
REMARQUE : Une valeur GEOGRAPHY
ne contient pas sa propre limite. Comparez cette fonction avec ST_COVERS
.
Type renvoyé
BOOL
Exemple
La requête suivante vérifie si le polygone POLYGON((1 1, 20 1, 10 20, 1 1))
contient chacun des trois points (0, 0)
, (1, 1)
et (10, 10)
, qui se trouvent à l'extérieur, sur la limite et à l'intérieur du polygone, respectivement.
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)
Description
Renvoie l'enveloppe convexe correspondant à l'entrée GEOGRAPHY
.
L'enveloppe convexe correspond au plus petit objet GEOGRAPHY
convexe qui recouvre l'entrée. Un objet GEOGRAPHY
est convexe si, pour chaque paire de points de GEOGRAPHY
, l'arc géodésique reliant les points est également contenu dans cet objet GEOGRAPHY
.
Dans la plupart des cas, l'enveloppe convexe est constituée d'un polygone unique. Parmi les cas limites notables, citons les exemples suivants :
- L'enveloppe convexe d'un point unique est aussi un point.
- L'enveloppe convexe de deux points colinéaires ou plus est un objet de type linestring (polyligne), à condition que cet objet soit convexe.
- Si l'objet
GEOGRAPHY
d'entrée s'étend sur plus d'un hémisphère, l'enveloppe convexe correspond au monde entier. Cela inclut toute entrée contenant une paire de points situés aux antipodes l'un de l'autre. ST_CONVEXHULL
renvoieNULL
si l'entrée estNULL
ou s'il s'agit d'un objetGEOGRAPHY
vide.
Type renvoyé
GEOGRAPHY
Exemples
Suivant l'entrée, l'enveloppe convexe renvoyée par ST_CONVEXHULL
peut être un point, une polyligne ou un polygone.
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)
Description
Renvoie FALSE
si geography_1
ou geography_2
est vide. Renvoie TRUE
si aucun point de geography_1
ne se trouve à l'extérieur de geography_2
.
Pour deux valeurs GEOGRAPHY
nommées a
et b
, ST_COVEREDBY(a, b)
renvoie le même résultat que ST_COVERS
(b, a)
. Notez l'ordre inverse des arguments.
Type renvoyé
BOOL
ST_COVERS
ST_COVERS(geography_1, geography_2)
Description
Renvoie FALSE
si geography_1
ou geography_2
est vide.
Renvoie TRUE
si aucun point de geography_2
ne se trouve à l'extérieur de geography_1
.
Type renvoyé
BOOL
Exemple
La requête suivante vérifie si le polygone POLYGON((1 1, 20 1, 10 20, 1 1))
couvre chacun des trois points (0, 0)
, (1, 1)
et (10, 10)
, qui se trouvent à l'extérieur, sur la limite et à l'intérieur du polygone, respectivement.
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)
Description
Renvoie une valeur GEOGRAPHY
qui représente la différence entre ensembles de points, entre geography_1
et geography_2
. Par conséquent, le résultat comprend la partie de geography_1
qui ne se croise pas avec geography_2
.
Si geometry_1
est entièrement contenu dans geometry_2
, ST_DIFFERENCE
renvoie une valeur GEOGRAPHY
vide.
Contraintes
Les objets géométriques sous-jacents représentés par une valeur GEOGRAPHY
BigQuery correspondent à un ensemble de points fermé. Par conséquent, ST_DIFFERENCE
est la fermeture de la différence entre ensembles de points, entre geography_1
et geography_2
. Cela implique qu'en cas d'intersection de geography_1
et geography_2
, une partie de la limite de geography_2
pourrait se trouver dans la différence.
Type renvoyé
GEOGRAPHY
Exemple
La requête suivante illustre la différence entre geog1
, un polygone plus grand POLYGON((0 0, 10 0, 10 10, 0 0))
et geog1
, un polygone plus petit POLYGON((4 2, 6 2, 8 6, 4 2))
qui s'entrecroise avec geog1
. Vous obtenez le résultat geog1
avec un trou qui s'entrecroise avec geog2
.
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)
Description
Renvoie la dimension de l'élément ayant la dimension la plus élevée dans la valeur GEOGRAPHY
d'entrée.
La dimension de chaque élément possible est la suivante :
- La dimension d'un point est
0
. - La dimension d'une polyligne est
1
. - La dimension d'un polygone est
2
.
Si la valeur GEOGRAPHY
d'entrée est vide, ST_DIMENSION
renvoie -1
.
Type renvoyé
INT64
ST_DISJOINT
ST_DISJOINT(geography_1, geography_2)
Description
Renvoie TRUE
si l'intersection de geography_1
et geography_2
est vide, c'est-à-dire qu'aucun point de geography_1
ne figure également dans geography_2
.
ST_DISJOINT
est la négation logique de ST_INTERSECTS
.
Type renvoyé
BOOL
ST_DISTANCE
ST_DISTANCE(geography_1, geography_2[, use_spheroid])
Description
Renvoie la distance la plus courte, exprimée en mètres, entre deux valeurs GEOGRAPHY
non vides.
Si l'une des valeurs GEOGRAPHY
d'entrée est vide, ST_DISTANCE
renvoie NULL
.
Le paramètre use_spheroid
facultatif détermine la manière dont cette fonction mesure la distance. Si la valeur de use_spheroid
est FALSE
, la fonction mesure la distance sur la surface d'une sphère parfaite.
Actuellement, le paramètre use_spheroid
n'accepte que la valeur FALSE
. La valeur par défaut de use_spheroid
est FALSE
.
Type renvoyé
FLOAT64
ST_DUMP
ST_DUMP(geography[, dimension])
Description
Renvoie un ARRAY
d'éléments GEOGRAPHY
simples, où chaque élément est un composant de l'élément GEOGRAPHY
d'entrée. Un élément GEOGRAPHY
simple consiste en un point, une polyligne ou un polygone unique. Si l'élément GEOGRAPHY
d'entrée est simple, le résultat est constitué d'un seul élément. Si l'entrée GEOGRAPHY
est une collection, ST_DUMP
renvoie un ARRAY
comportant un élément GEOGRAPHY
simple pour chaque composant de la collection.
Si la valeur dimension
est fournie, la fonction renvoie uniquement les éléments GEOGRAPHY
de la dimension correspondante. Une dimension valant -1 équivaut à omettre dimension
.
Type renvoyé
ARRAY
Exemples
L'exemple suivant illustre comment ST_DUMP
renvoie les éléments "GEOGRAPHY" simples dans un élément "GEOGRAPHY" complexe.
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)] |
+-------------------------------------+-------------------------------+
L'exemple suivant illustre comment ST_DUMP
utilisé avec l'argument de dimension renvoie uniquement les éléments "GEOGRAPHY" simples de la dimension donnée.
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])
Description
Renvoie TRUE
si la distance entre au moins un point de geography_1
et un point de geography_2
est inférieure ou égale à la distance donnée par l'argument distance
. Sinon, renvoie FALSE
. Si l'une des entrées GEOGRAPHY
est vide, ST_DWithin
renvoie FALSE
. La valeur distance
donnée est exprimée en mètres sur la surface de la Terre.
Le paramètre use_spheroid
facultatif détermine la manière dont cette fonction mesure la distance. Si la valeur de use_spheroid
est FALSE
, la fonction mesure la distance sur la surface d'une sphère parfaite.
Actuellement, le paramètre use_spheroid
n'accepte que la valeur FALSE
. La valeur par défaut de use_spheroid
est FALSE
.
Type renvoyé
BOOL
ST_ENDPOINT
ST_ENDPOINT(linestring_geography)
Description
Renvoie le dernier point d'une zone géographique en polyligne en tant que géographie de points. Renvoie une erreur si l'entrée n'est pas une polyligne ou si l'entrée est vide. Utilisez le préfixe SAFE
pour obtenir NULL
en cas d'entrée non valide à la place d'une erreur.
Type renvoyé
Point GEOGRAPHY
Exemple
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)
Description
Renvoie TRUE
si geography_1
et geography_2
représentent la même
valeur GEOGRAPHY
. Plus précisément, cela signifie que l'une des conditions suivantes s'applique :
+ ST_COVERS(geography_1, geography_2) = TRUE
et ST_COVERS(geography_2,
geography_1) = TRUE
;
+ geography_1
et geography_2
sont tous deux vides.
Par conséquent, deux valeurs GEOGRAPHY
peuvent être égales même si l’ordre des points ou des sommets diffère, dans la mesure où ils représentent toujours la même structure géométrique.
Contraintes
Il n'est pas garanti que ST_EQUALS
soit une fonction transitive.
Type renvoyé
BOOL
ST_EXTENT
ST_EXTENT(geography_expression)
Description
Renvoie une valeur STRUCT
représentant le cadre de délimitation de l'ensemble des valeurs d'entrée GEOGRAPHY
. Le cadre de délimitation est le rectangle minimal qui entoure la zone géographique. Les arêtes du rectangle suivent des lignes constantes de longitude et de latitude.
Mises en garde :
- Renvoie
NULL
si toutes les entrées sontNULL
ou des zones géographiques vides. - Le cadre de délimitation peut dépasser l'antiméridien si cela permet un rectangle plus petit. Dans ce cas, le cadre de délimitation possède l'une de ses limites longitudinales en dehors de la plage [-180, 180], de sorte que
xmin
soit inférieur à la valeur la plus est par rapport àxmax
. - Si la plage de longitude du cadre de délimitation est supérieure ou égale à 180 degrés, la fonction renvoie le cadre de délimitation avec une plage de longitude de [-180, 180].
Type renvoyé
STRUCT<xmin FLOAT64, ymin FLOAT64, xmax FLOAT64, ymax FLOAT64>
.
Parties de cadre de délimitation :
xmin
: ligne de longitude constante la plus ouest qui délimite le rectangle.xmax
: ligne de longitude constante la plus est qui délimite le rectangle.ymin
: ligne de latitude constante minimale qui délimite le rectangle.ymax
: ligne de latitude constante maximale qui délimite le rectangle.
Exemple
WITH data AS (
SELECT 1 id, st_geogfromtext('polygon((-125 48, -124 46, -117 46, -117 49, -125 48))') g
UNION ALL
SELECT 2 id, st_geogfromtext('polygon((172 53, -130 55, -141 70, 172 53))') g
UNION ALL
SELECT 3 id, st_geogfromtext('point empty') g
)
SELECT st_extent(g) AS box
FROM data
+----------------------------------------------+
| box |
+----------------------------------------------+
| {xmin:172, ymin:46, xmax:243, ymax:70} |
+----------------------------------------------+
Pour en savoir plus sur la version non agrégée de ST_EXTENT, consultez la section sur la fonction ST_BOUNDINGBOX
.
ST_EXTERIORRING
ST_EXTERIORRING(polygon_geography)
Description
Renvoie une zone géographique en polyligne correspondant à l'anneau le plus externe d'une zone polygonale.
- Si la zone géographique d'entrée est un polygone, récupère l'anneau le plus externe de la zone géographique polygonale et renvoie la polyligne correspondante.
- Si l'entrée est la valeur
GEOGRAPHY
complète, renvoie une zone géographique vide. - Renvoie une erreur si l'entrée n'est pas un polygone unique.
Utilisez le préfixe SAFE
pour obtenir l'élément NULL
en cas d'entrée non valide à la place d'une erreur.
Type renvoyé
GEOGRAPHY
LineString- Vider
GEOGRAPHY
Exemples
WITH geo as
(SELECT ST_GEOGFROMTEXT('POLYGON((0 0, 1 4, 2 2, 0 0))') AS g UNION ALL
SELECT ST_GEOGFROMTEXT('''POLYGON((1 1, 1 10, 5 10, 5 1, 1 1),
(2 2, 3 4, 2 4, 2 2))''') as g)
SELECT ST_EXTERIORRING(g) AS ring FROM geo;
+---------------------------------------+
| ring |
+---------------------------------------+
| LINESTRING(2 2, 1 4, 0 0, 2 2) |
| LINESTRING(5 1, 5 10, 1 10, 1 1, 5 1) |
+---------------------------------------+
ST_GEOGFROM
ST_GEOGFROM(expression)
Description
Convertit une expression pour une valeur STRING
ou BYTES
en une valeur GEOGRAPHY
.
Si expression
représente une valeur STRING
, il doit s'agir d'une représentation GEOGRAPHY
valide dans l'un des formats suivants :
- Format WKT. Pour en savoir plus sur ce format et les conditions requises pour l'utiliser, consultez la page ST_GEOGFROMTEXT.
- WKB au format texte hexadécimal. Pour en savoir plus sur ce format et les conditions requises pour l'utiliser, consultez la section ST_GEOGFROMWKB.
- Format GeoJSON. Pour en savoir plus sur ce format et les conditions requises pour l'utiliser, consultez la section ST_GEOGFROMGEOJSON.
Si expression
représente une valeur BYTES
, il doit s'agir d'une expression binaire GEOGRAPHY
valide au format WKB. Pour en savoir plus sur ce format et les conditions requises pour l'utiliser, consultez la section sur la fonction ST_GEOGFROMWKB.
Si expression
est NULL
, le résultat est NULL
.
Type renvoyé
GEOGRAPHY
Exemples
Cela prend une chaîne au format WKT et renvoie un polygone 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)) |
+------------------------------------+
Cela prend une chaîne encodée en hexadécimal au format WKB et renvoie un point GEOGRAPHY
:
SELECT ST_GEOGFROM(FROM_HEX('010100000000000000000000400000000000001040')) AS WKB_format
+----------------+
| WKB_format |
+----------------+
| POINT(2 4) |
+----------------+
Cela prend des octets au format WKB et renvoie un point GEOGRAPHY
:
SELECT ST_GEOGFROM('010100000000000000000000400000000000001040')-AS WKB_format
+----------------+
| WKB_format |
+----------------+
| POINT(2 4) |
+----------------+
Cela prend une chaîne au format GEOJSON et renvoie un polygone 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
Renvoie une valeur GEOGRAPHY
correspondant à la représentation GeoJSON d'entrée.
ST_GEOGFROMGEOJSON
accepte une entrée conforme à la norme RFC 7946.
Si le paramètre make_valid
est défini sur TRUE
, la fonction tente de réparer les polygones non conformes à la sémantique Open Geospatial Consortium.
Ce paramètre utilise la syntaxe d'argument nommé et doit être spécifié à l'aide de la syntaxe make_valid => argument_value
.
Une valeur GEOGRAPHY
BigQuery a des arêtes géodésiques sphériques, tandis qu'un objet Geometry
GeoJSON a explicitement des arêtes planes.
Pour effectuer la conversion entre ces deux types d'arêtes, BigQuery ajoute des points supplémentaires à la ligne si nécessaire, de sorte que la séquence d'arêtes résultante reste à moins de 10 mètres de l'arête d'origine.
Pour formater une valeur GEOGRAPHY
en GeoJSON, consultez la section sur la fonction ST_ASGEOJSON
.
Contraintes
L'entrée est soumise aux contraintes suivantes :
- La fonction
ST_GEOGFROMGEOJSON
n'accepte que des fragments de géométrie JSON et elle ne peut pas être utilisée pour ingérer un document JSON complet. - Le fragment JSON d'entrée doit être d'un type de géométrie GeoJSON, soit
Point
,MultiPoint
,LineString
,MultiLineString
,Polygon
,MultiPolygon
ouGeometryCollection
. Tout autre type GeoJSON, tel queFeature
ouFeatureCollection
entraînera une erreur. - Une position dans le membre
coordinates
d'un type de géométrie GeoJSON doit comporter exactement deux éléments. Le premier est la longitude, et le second est la latitude. Par conséquent,ST_GEOGFROMGEOJSON
n'accepte pas le troisième élément facultatif pour une position dans le membrecoordinates
.
Type renvoyé
GEOGRAPHY
ST_GEOGFROMTEXT
Signature 1
ST_GEOGFROMTEXT(wkt_string[, oriented])
Description
Renvoie une valeur GEOGRAPHY
correspondant à la représentation WKT d'entrée.
Cette fonction accepte un paramètre facultatif de type BOOL
, oriented
. Si ce paramètre est défini sur TRUE
, tous les polygones de l'entrée sont supposés être orientés comme suit : si quelqu'un marche le long de la limite du polygone dans l'ordre des sommets d'entrée, l'intérieur du polygone se trouve sur la gauche. WKT peut ainsi représenter des polygones plus grands qu'un hémisphère. Si oriented
est défini sur FALSE
ou est omis, cette fonction renvoie le polygone ayant la plus petite aire.
Consultez également la section sur la fonction ST_MAKEPOLYGONORIENTED
, qui est semblable à la fonction ST_GEOGFROMTEXT
avec le paramètre oriented=TRUE
.
Pour formater une valeur GEOGRAPHY
en WKT, utilisez la fonction ST_ASTEXT
.
Contraintes
- Toutes les arêtes de l'objet d'entrée sont supposées être des géodésiques sphériques, et non des lignes droites planes. Pour lire des données dans une projection planaire, envisagez d'utiliser
ST_GEOGFROMGEOJSON
. Pour plus d'informations sur les différences entre les géodésiques sphériques et les lignes planes, consultez la section Systèmes de coordonnées et arêtes. - La fonction n'est pas compatible avec les géométries tridimensionnelles ayant un suffixe
Z
, ni avec les géométries de système de référence linéaire ayant un suffixeM
. - La fonction n'accepte que des primitives de géométrie et des géométries en plusieurs parties. En particulier, elle n'accepte que les types "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon" et "GeometryCollection".
Type renvoyé
GEOGRAPHY
Exemple
La requête suivante lit la chaîne WKT POLYGON((0 0, 0 2, 2 2, 2 0, 0 0))
à la fois comme un polygone non orienté et comme un polygone orienté, et vérifie si chaque résultat contient le point (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 |
+-------------------+---------------+-----------+
Signature 2
ST_GEOGFROMTEXT(wkt_string[, oriented => boolean_constant_1]
[, planar => boolean_constant_2] [, make_valid => boolean_constant_3])
Description
Renvoie une valeur GEOGRAPHY
correspondant à la représentation WKT d'entrée.
Cette fonction accepte trois paramètres facultatifs de type BOOL
: oriented
, planar
et make_valid
.
Cette signature utilise une syntaxe d'arguments nommés et les paramètres doivent être spécifiés à l'aide de la syntaxe parameter_name => parameter_value
, dans n'importe quel ordre.
Si le paramètre oriented
est défini sur TRUE
, tous les polygones de l'entrée sont supposés être orientés comme suit : si quelqu'un marche le long de la limite du polygone dans l'ordre des sommets d'entrée, l'intérieur du polygone se trouve sur la gauche. WKT peut ainsi représenter des polygones plus grands qu'un hémisphère. Si oriented
est défini sur FALSE
ou est omis, cette fonction renvoie le polygone ayant la plus petite aire.
Consultez également la section sur la fonction ST_MAKEPOLYGONORIENTED
, qui est semblable à la fonction ST_GEOGFROMTEXT
avec le paramètre oriented=TRUE
.
Si le paramètre planar
est défini sur TRUE
, les arêtes des chaînes et des polygones de ligne sont supposées utiliser la sémantique de mappage plane, plutôt que la sémantique des géodésiques sphériques par défaut de BigQuery. Pour en savoir plus sur les différences entre les géodésiques sphériques et les lignes planes, consultez la section Systèmes de coordonnées et arêtes.
Si le paramètre make_valid
est défini sur TRUE
, la fonction tente de réparer les polygones non conformes à la sémantique Open Geospatial Consortium.
Pour formater une valeur GEOGRAPHY
en WKT, utilisez la fonction ST_ASTEXT
.
Contraintes
- Toutes les arêtes d'entrée sont supposées être des géodésiques sphériques par défaut, et non des lignes droites planes. Pour lire des données dans une projection planaire, transmettez l'argument
planar => TRUE
ou envisagez d'utiliserST_GEOGFROMGEOJSON
. Pour en savoir plus sur les différences entre les géodésiques sphériques et les lignes planes, consultez la section Systèmes de coordonnées et arêtes. - La fonction n'est pas compatible avec les géométries tridimensionnelles ayant un suffixe
Z
, ni avec les géométries de système de référence linéaire ayant un suffixeM
. - La fonction n'accepte que des primitives de géométrie et des géométries en plusieurs parties. En particulier, elle n'accepte que les types "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon" et "GeometryCollection".
- Les valeurs
oriented
etplanar
ne peuvent pas simultanément être égales àTRUE
. - Les valeurs
oriented
etmake_valid
ne peuvent pas simultanément être égales àTRUE
.
Exemple
La requête suivante lit la chaîne WKT POLYGON((0 0, 0 2, 2 2, 0 2, 0 0))
à la fois comme un polygone non orienté et comme un polygone orienté, et vérifie si chaque résultat contient le point (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 |
+-------------------+---------------+-----------+
La requête suivante convertit une chaîne WKT avec un polygone non valide en GEOGRAPHY
. La chaîne WKT enfreint deux propriétés d'un polygone valide : la boucle décrivant le polygone n'est pas fermée et le polygone contient une auto-intersection. Avec l'option make_valid
, ST_GeogFromText
la convertit en forme de multipolygone.
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
Convertit une expression pour une valeur STRING
ou BYTES
au format hexadécimal en une valeur GEOGRAPHY
. L'expression doit être au format WKB.
Pour formater une valeur GEOGRAPHY
en WKB, utilisez la fonction ST_ASBINARY
.
Contraintes
Toutes les arêtes d'entrée sont supposées être des géodésiques sphériques, et non des lignes droites planes. Pour lire des données dans une projection planaire, envisagez d'utiliser ST_GEOGFROMGEOJSON
.
Type renvoyé
GEOGRAPHY
ST_GEOGPOINT
ST_GEOGPOINT(longitude, latitude)
Description
Crée une valeur GEOGRAPHY
avec un seul point.
ST_GEOGPOINT
crée un point à partir des paramètres de longitude et de latitude FLOAT64
spécifiés, et le renvoie dans une valeur GEOGRAPHY
.
Contraintes
- Les latitudes doivent être comprises dans la plage [-90, 90]. Si elles sont situées en dehors de cette plage, elles entraînent une erreur.
- Les longitudes non comprises dans la plage [-180, 180] sont autorisées.
ST_GEOGPOINT
utilise le modulo 360 de longitudes d'entrée pour obtenir une longitude comprise dans cette plage.
Type renvoyé
GEOGRAPHY
ST_GEOGPOINTFROMGEOHASH
ST_GEOGPOINTFROMGEOHASH(geohash)
Description
Renvoie une valeur GEOGRAPHY
correspondant à un point au milieu d'un cadre de délimitation défini dans le GeoHash.
Type renvoyé
GEOGRAPHY
ST_GEOHASH
ST_GEOHASH(geography_expression[, maxchars])
Description
Prend une valeur GEOGRAPHY
à un seul point et renvoie une représentation GeoHash de cet objet GEOGRAPHY
.
geography_expression
: représente un objetGEOGRAPHY
. Seul un objetGEOGRAPHY
représentant un seul point est accepté. SiST_GEOHASH
est utilisé sur un objetGEOGRAPHY
vide, renvoieNULL
.maxchars
: ce paramètre facultatifINT64
spécifie le nombre maximal de caractères que le hachage contiendra. Un nombre moins important de caractères correspond à une précision inférieure (ou, autrement dit, à un cadre de délimitation plus grand). La valeur par défaut demaxchars
est 20 si elle n'est pas explicitement spécifiée. Une valeurmaxchars
valide est comprise entre 1 et 20. Toute valeur inférieure ou supérieure à cette plage est considérée comme non spécifiée, auquel cas la valeur par défaut de 20 est utilisée.
Type renvoyé
STRING
Exemple
Renvoie un GeoHash du Seattle Center avec une précision de 10 caractères.
SELECT ST_GEOHASH(ST_GEOGPOINT(-122.35, 47.62), 10) geohash
+--------------+
| geohash |
+--------------+
| c22yzugqw7 |
+--------------+
ST_GEOMETRYTYPE
ST_GEOMETRYTYPE(geography_expression)
Description
Renvoie le type de géométrie Open Geospatial Consortium (OGC) qui décrit l'entrée GEOGRAPHY
en tant que STRING
. Le type de géométrie OGC correspond aux types utilisés aux formats WKT et GeoJSON, et affichés pour ST_ASTEXT et . ST_ASGEOJSON.
ST_GEOMETRYTYPE
renvoie le type de géométrie OGC avec le préfixe "ST_".
ST_GEOMETRYTYPE
renvoie les éléments suivants en fonction du type de l'entrée :
- Zone géographique à un seul point : renvoie
ST_Point
. - Collection de points seulement : renvoie
ST_MultiPoint
. - Zone géographique unique pour une polyligne : renvoie
ST_LineString
. - Collection de polylignes seulement : renvoie
ST_MultiLineString
. - Zone géographique à un seul polygone : renvoie
ST_Polygon
. - Collection de polygones seulement : renvoie
ST_MultiPolygon
. - Collection avec des éléments de dimensions différentes, ou entrée représentant la zone géographique vide : renvoie
ST_GeometryCollection
.
Type renvoyé
STRING
Exemple
L'exemple suivant montre comment ST_GEOMETRYTYPE
prend des zones géographiques et renvoie les noms de leurs types de géométrie OGC.
WITH example AS(
SELECT ST_GeogFromText('POINT(0 1)') AS geography
UNION ALL
SELECT ST_GeogFromText('MULTILINESTRING((2 2, 3 4), (5 6, 7 7))')
UNION ALL
SELECT ST_GeogFromText('GEOMETRYCOLLECTION(MULTIPOINT(-1 2, 0 12), LINESTRING(-2 4, 0 6))')
UNION ALL
SELECT ST_GeogFromText('GEOMETRYCOLLECTION EMPTY'))
SELECT
geography AS WKT,
ST_GeometryType(geography) AS geometry_type_name
FROM example;
+-------------------------------------------------------------------+-----------------------+
| WKT | geometry_type_name |
+-------------------------------------------------------------------+-----------------------+
| POINT(0 1) | ST_Point |
| MULTILINESTRING((2 2, 3 4), (5 6, 7 7)) | ST_MultiLineString |
| GEOMETRYCOLLECTION(MULTIPOINT(-1 2, 0 12), LINESTRING(-2 4, 0 6)) | ST_GeometryCollection |
| GEOMETRYCOLLECTION EMPTY | ST_GeometryCollection |
+-------------------------------------------------------------------+-----------------------+
ST_INTERIORRINGS
ST_INTERIORRINGS(polygon_geography)
Description
Renvoie un tableau de zones géographiques de polylignes correspondant aux anneaux intérieurs d'une zone géographique de polygone. Chaque anneau intérieur correspond à la bordure d'un trou situé dans le polygone d'entrée.
- Si la géographie d'entrée est un polygone, cela exclut l'anneau le plus externe de la zone géographique du polygone et renvoie les polylignes correspondant aux anneaux intérieurs.
- Si l'entrée est la valeur
GEOGRAPHY
complète, renvoie un tableau vide. - Si le polygone d'entrée n'a pas de trou, renvoie un tableau vide.
- Renvoie une erreur si l'entrée n'est pas un polygone unique.
Utilisez le préfixe SAFE
pour obtenir l'élément NULL
en cas d'entrée non valide à la place d'une erreur.
Type renvoyé
ARRAY
Exemples
WITH geo AS (
SELECT ST_GEOGFROMTEXT('polygon((0 0, 1 1, 1 2, 0 0))') AS g UNION ALL
SELECT ST_GEOGFROMTEXT('polygon((1 1, 1 10, 5 10, 5 1, 1 1), (2 2, 3 4, 2 4, 2 2))') UNION ALL
SELECT ST_GEOGFROMTEXT('polygon((1 1, 1 10, 5 10, 5 1, 1 1), (2 2.5, 3.5 3, 2.5 2, 2 2.5), (3.5 7, 4 6, 3 3, 3.5 7))') UNION ALL
SELECT ST_GEOGFROMTEXT('fullglobe') UNION ALL
SELECT null)
SELECT ST_INTERIORRINGS(g) AS rings FROM geo;
+----------------------------------------------------------------------------+
| rings |
+----------------------------------------------------------------------------+
| [] |
| [LINESTRING(2 2, 3 4, 2 4, 2 2)] |
| [LINESTRING(2.5 2, 3.5 3, 2 2.5, 2.5 2), LINESTRING(3 3, 4 6, 3.5 7, 3 3)] |
| [] |
| NULL |
+----------------------------------------------------------------------------+
ST_INTERSECTION
ST_INTERSECTION(geography_1, geography_2)
Description
Renvoie une valeur GEOGRAPHY
représentant l'intersection des ensembles de points des deux valeurs GEOGRAPHY
d'entrée. Ainsi, chaque point de l'intersection apparaît à la fois dans geography_1
et geography_2
.
Si les deux valeurs GEOGRAPHY
d'entrée sont disjointes, c'est-à-dire si aucun point n'apparaît à la fois dans geometry_1
et dans geometry_2
, une valeur GEOGRAPHY
vide est renvoyée.
Pour en savoir plus sur les fonctions de prédicat associées, consultez les sections sur les fonctions ST_INTERSECTS et ST_DISJOINT.
Type renvoyé
GEOGRAPHY
ST_INTERSECTS
ST_INTERSECTS(geography_1, geography_2)
Description
Renvoie TRUE
si l'intersection des ensembles de points de geography_1
et geography_2
n'est pas vide. Ainsi, cette fonction renvoie TRUE
si au moins un point apparaît dans les deux valeurs GEOGRAPHY
d'entrée.
Si ST_INTERSECTS
renvoie TRUE
, cela signifie que ST_DISJOINT
renvoie FALSE
.
Type renvoyé
BOOL
ST_INTERSECTSBOX
ST_INTERSECTSBOX(geography, lng1, lat1, lng2, lat2)
Description
Renvoie TRUE
en cas d'intersection de geography
et du rectangle entre [lng1, lng2]
et [lat1, lat2]
. Les arêtes du rectangle suivent des lignes constantes de longitude et de latitude. lng1
et lng2
spécifient les lignes de longitude constantes le plus à l'ouest et le plus à l'est qui délimitent le rectangle, et lat1
et lat2
spécifient les lignes de latitude constantes minimale et maximale qui délimitent le rectangle.
Spécifiez tous les arguments de longitude et de latitude en degrés.
Contraintes
Les arguments d'entrée sont soumis aux contraintes suivantes :
- Les latitudes doivent être comprises dans la plage
[-90, 90]
degrés. - Les longitudes doivent respecter l'une des règles suivantes :
- Les deux longitudes sont comprises dans la plage
[-180, 180]
degrés. - L'une des longitudes est comprise dans la plage
[-180, 180]
degrés, etlng2 - lng1
se situe dans l'intervalle[0, 360]
.
- Les deux longitudes sont comprises dans la plage
Type renvoyé
BOOL
Exemple
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)
Description
Renvoie TRUE
si le nombre total de points, de polylignes et de polygones est supérieur à un.
Une valeur GEOGRAPHY
vide n'est pas une collection.
Type renvoyé
BOOL
ST_ISEMPTY
ST_ISEMPTY(geography_expression)
Description
Renvoie TRUE
si la valeur GEOGRAPHY
donnée est vide, c'est-à-dire que la valeur GEOGRAPHY
ne contient ni point, ni ligne, ni polygone.
REMARQUE : Une valeur GEOGRAPHY
BigQuery vide n'est pas associée à une forme géométrique particulière. Par exemple, les résultats des expressions ST_GEOGFROMTEXT('POINT EMPTY')
et ST_GEOGFROMTEXT('GEOMETRYCOLLECTION EMPTY')
sont identiques.
Type renvoyé
BOOL
ST_LENGTH
ST_LENGTH(geography_expression[, use_spheroid])
Description
Renvoie la longueur totale, exprimée en mètres, des lignes de la valeur GEOGRAPHY
d'entrée.
Si geography_expression
est un point ou un polygone, renvoie zéro. Si geography_expression
est une collection, renvoie la longueur des lignes que celle-ci contient. Si la collection ne contient pas de lignes, renvoie zéro.
Le paramètre use_spheroid
facultatif détermine la manière dont cette fonction mesure la distance. Si la valeur de use_spheroid
est FALSE
, la fonction mesure la distance sur la surface d'une sphère parfaite.
Actuellement, le paramètre use_spheroid
n'accepte que la valeur FALSE
. La valeur par défaut de use_spheroid
est FALSE
.
Type renvoyé
FLOAT64
ST_MAKELINE
ST_MAKELINE(geography_1, geography_2)
ST_MAKELINE(array_of_geography)
Description
Crée une valeur GEOGRAPHY
avec une seule polyligne en concaténant les sommets correspondant aux points ou aux lignes de chacune des valeurs GEOGRAPHY
d'entrée, dans l'ordre dans lequel elles sont données.
ST_MAKELINE
comporte deux variantes. Pour la première variante, l'entrée consiste en deux valeurs GEOGRAPHY
. Pour la seconde, l'entrée est un tableau (ARRAY
) de type GEOGRAPHY
. Dans l'une ou l'autre variante, chaque valeur GEOGRAPHY
d'entrée doit comporter l'une des valeurs suivantes :
- Exactement un point
- Exactement une polyligne
Pour la première variante de ST_MAKELINE
, si l'une des valeurs GEOGRAPHY
d'entrée est NULL
, ST_MAKELINE
renvoie NULL
. Pour la deuxième variante, si l'ARRAY
d'entrée ou un élément de l'ARRAY
d'entrée est NULL
, ST_MAKELINE
renvoie NULL
.
Contraintes
Chaque arête doit couvrir strictement moins de 180 degrés.
REMARQUE : Le processus d'ancrage de BigQuery peut supprimer les arêtes suffisamment courtes et ancrer les deux extrémités ensemble. Par exemple, si deux valeurs GEOGRAPHY
d'entrée contiennent chacune un point et que la distance séparant les deux points est inférieure au rayon d'ancrage, les points sont ancrés ensemble. Dans ce cas, le résultat obtenu est une valeur GEOGRAPHY
avec exactement un point.
Type renvoyé
GEOGRAPHY
ST_MAKEPOLYGON
ST_MAKEPOLYGON(geography_expression[, array_of_geography])
Description
Crée une valeur GEOGRAPHY
contenant un seul polygone à partir d'entrées de polyligne, chacune étant utilisée pour construire un anneau de polygone.
ST_MAKEPOLYGON
comporte deux variantes. Pour la première variante, la polyligne d'entrée est fournie par une seule valeur GEOGRAPHY
contenant exactement une polyligne. Pour la seconde variante, l'entrée est composée d'une seule valeur GEOGRAPHY
et d'un tableau de valeurs GEOGRAPHY
, chacun contenant exactement une polyligne.
La première valeur GEOGRAPHY
de l'une ou l'autre variante est utilisée pour construire l'enveloppe du polygone. Les valeurs GEOGRAPHY
supplémentaires fournies dans l'ARRAY
d'entrée spécifient un trou du polygone. Pour chaque valeur GEOGRAPHY
d'entrée contenant exactement une polyligne, les conditions suivantes doivent être remplies :
- La polyligne doit comporter au moins trois sommets distincts.
- La polyligne doit être fermée, c'est-à-dire que le premier et le dernier sommet doivent être identiques. S'ils sont différents, la fonction construit une arête finale allant du premier au dernier sommet.
Pour la première variante de ST_MAKEPOLYGON
, si l'une des entrées GEOGRAPHY
est NULL
, ST_MAKEPOLYGON
renvoie NULL
. Pour la seconde variante, si l'entrée ARRAY
ou tout élément de l'entrée ARRAY
est NULL
, ST_MAKEPOLYGON
renvoie NULL
.
REMARQUE : ST_MAKEPOLYGON
accepte une valeur GEOGRAPHY
vide comme entrée. ST_MAKEPOLYGON
interprète une valeur GEOGRAPHY
vide comme ayant une polyligne vide, ce qui crée une boucle complète, autrement dit un polygone couvrant toute la Terre.
Contraintes
Ensemble, les anneaux d'entrée doivent former un polygone valide :
- L'enveloppe du polygone doit couvrir chacun des trous de ce dernier.
- Il ne peut y avoir qu'une seule enveloppe de polygone (qui doit être le premier anneau d'entrée). Cela implique que les trous de polygone ne peuvent pas être imbriqués.
- Les anneaux de polygone ne peuvent se croiser que dans un sommet situé sur la limite des deux anneaux.
Chaque arête doit couvrir strictement moins de 180 degrés.
Chaque anneau de polygone divise la sphère en deux régions. La première polyligne d'entrée pour ST_MAKEPOLYGON
forme l'enveloppe du polygone, et l'intérieur est choisi pour être la plus petite des deux régions. Chaque polyligne d'entrée suivante spécifie un trou de polygone, de sorte que l'intérieur du polygone est déjà bien défini. Pour définir une enveloppe de polygone de sorte que l'intérieur de celui-ci soit la plus grande des deux régions, consultez la section sur la fonction ST_MAKEPOLYGONORIENTED
.
REMARQUE : Le processus d'ancrage de BigQuery peut supprimer les arêtes suffisamment courtes et ancrer les deux extrémités ensemble. Par conséquent, lorsque les sommets sont ancrés ensemble, il est possible qu'un trou de polygone suffisamment petit disparaisse, ou que la valeur GEOGRAPHY
de sortie ne contienne qu'un point ou une ligne.
Type renvoyé
GEOGRAPHY
ST_MAKEPOLYGONORIENTED
ST_MAKEPOLYGONORIENTED(array_of_geography)
Description
Cette fonction est identique à ST_MAKEPOLYGON
, mais l'ordre des sommets de chaque polyligne d'entrée détermine l'orientation de chaque anneau de polygone. L'orientation d'un anneau de polygone définit l'intérieur du polygone de la manière suivante : si quelqu'un marche le long de la limite du polygone dans l'ordre des sommets d'entrée, l'intérieur du polygone se trouve sur la gauche. Cela s'applique à chaque anneau de polygone fourni.
Cette variante du constructeur de polygone est plus flexible, car ST_MAKEPOLYGONORIENTED
peut construire un polygone de sorte que l'intérieur se trouve de chaque côté de l'anneau de polygone. Cependant, il est primordial que les anneaux de polygone soient orientés correctement pour construire le polygone souhaité.
Si l'ARRAY
d'entrée ou tout autre élément de l'ARRAY
d'entrée est NULL
, ST_MAKEPOLYGONORIENTED
renvoie NULL
.
REMARQUE : l'argument d'entrée pour ST_MAKEPOLYGONORIENTED
peut contenir une valeur GEOGRAPHY
vide. ST_MAKEPOLYGONORIENTED
interprète une valeur GEOGRAPHY
vide comme ayant une polyligne vide, ce qui crée une boucle complète, autrement dit un polygone couvrant toute la Terre.
Contraintes
Ensemble, les anneaux d'entrée doivent former un polygone valide :
- L'enveloppe du polygone doit couvrir chacun des trous de ce dernier.
- Il ne doit y avoir qu'une seule enveloppe de polygone, qui doit être le premier anneau d'entrée. Cela implique que les trous de polygone ne peuvent pas être imbriqués.
- Les anneaux de polygone ne peuvent se croiser que dans un sommet situé sur la limite des deux anneaux.
Chaque arête doit couvrir strictement moins de 180 degrés.
ST_MAKEPOLYGONORIENTED
s'appuie sur l'ordre des sommets d'entrée de chaque polyligne pour déterminer l’orientation du polygone. Ceci s'applique à l'enveloppe du polygone et à tous les trous de ce dernier. ST_MAKEPOLYGONORIENTED
s'attend à ce que tous les trous du polygone aient une orientation opposée à celle de l'enveloppe. Consultez la section sur la fonction ST_MAKEPOLYGON
pour découvrir un autre constructeur de polygone, ainsi que les autres contraintes associées à la construction d'un polygone valide.
REMARQUE : En raison du processus d'ancrage de BigQuery, les arêtes suffisamment courtes sont supprimées et les deux extrémités sont ancrées à un seul point. Par conséquent, il est possible que les sommets d'une polyligne soient ancrés ensemble de façon qu'une ou plusieurs arêtes disparaissent. Ainsi, un trou de polygone suffisamment petit peut disparaître, ou la valeur GEOGRAPHY
résultante peut ne contenir qu'un point ou une ligne.
Type renvoyé
GEOGRAPHY
ST_MAXDISTANCE
ST_MAXDISTANCE(geography_1, geography_2[, use_spheroid])
Renvoie la distance la plus longue, exprimée en mètres, entre deux valeurs GEOGRAPHY
non vides. Autrement dit, il s'agit de la distance entre deux sommets, où le premier sommet se trouve dans la première valeur GEOGRAPHY
, et où le second sommet se trouve dans la seconde valeur GEOGRAPHY
. Si geography_1
et geography_2
correspondent à la même valeur GEOGRAPHY
, la fonction renvoie la distance entre les deux sommets les plus éloignés dans cette valeur GEOGRAPHY
.
Si l'une des valeurs GEOGRAPHY
d'entrée est vide, ST_MAXDISTANCE
renvoie NULL
.
Le paramètre use_spheroid
facultatif détermine la manière dont cette fonction mesure la distance. Si la valeur de use_spheroid
est FALSE
, la fonction mesure la distance sur la surface d'une sphère parfaite.
Actuellement, le paramètre use_spheroid
n'accepte que la valeur FALSE
. La valeur par défaut de use_spheroid
est FALSE
.
Type renvoyé
FLOAT64
ST_NPOINTS
ST_NPOINTS(geography_expression)
Description
Un alias de ST_NUMPOINTS.
ST_NUMGEOMETRIES
ST_NUMGEOMETRIES(geography_expression)
Description
Renvoie le nombre de géométries dans l'entrée GEOGRAPHY
. Pour un seul point, une polyligne ou un polygone, ST_NUMGEOMETRIES
renvoie 1
. Pour toute collection de géométries, ST_NUMGEOMETRIES
renvoie le nombre de géométries constituant la collection. ST_NUMGEOMETRIES
renvoie 0
si l'entrée est une valeur GEOGRAPHY
vide.
Type renvoyé
INT64
Exemple
L'exemple suivant calcule ST_NUMGEOMETRIES
pour une zone géographique à un seul point, deux collections et une zone géographique vide.
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)
Description
Renvoie le nombre de sommets dans la valeur GEOGRAPHY
d'entrée. Cela inclut le nombre de points, de sommets de polylignes et de sommets de polygones.
REMARQUE : Le premier et le dernier sommet d'un anneau de polygone sont comptés comme des sommets distincts.
Type renvoyé
INT64
ST_PERIMETER
ST_PERIMETER(geography_expression[, use_spheroid])
Description
Renvoie la longueur, exprimée en mètres, de la limite des polygones dans la valeur GEOGRAPHY
d'entrée.
Si geography_expression
est un point ou une ligne, renvoie zéro. Si geography_expression
est une collection, renvoie le périmètre des polygones que celle-ci contient. Si la collection ne contient pas de polygones, renvoie zéro.
Le paramètre use_spheroid
facultatif détermine la manière dont cette fonction mesure la distance. Si la valeur de use_spheroid
est FALSE
, la fonction mesure la distance sur la surface d'une sphère parfaite.
Actuellement, le paramètre use_spheroid
n'accepte que la valeur FALSE
. La valeur par défaut de use_spheroid
est FALSE
.
Type renvoyé
FLOAT64
ST_POINTN
ST_POINTN(linestring_geography, index)
Description
Renvoie le nième point d'une zone géographique en polyligne en tant que géographie de points, où N est l'index. L'index est basé sur 1. Les valeurs négatives sont comptées en partant de la fin de la polyligne, de sorte que -1 est le dernier point. Renvoie une erreur si l'entrée n'est pas une polyligne, si l'entrée est vide ou s'il n'y a pas de sommet au niveau de l'index donné. Utilisez le préfixe SAFE
pour obtenir l'élément NULL
en cas d'entrée non valide à la place d'une erreur.
Type renvoyé
Point GEOGRAPHY
Exemple
L'exemple suivant utilise ST_POINTN
, ST_STARTPOINT
et ST_ENDPOINT
pour extraire des points d'une polyligne.
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)
Description
Renvoie une version simplifiée de geography
, la valeur GEOGRAPHY
donnée en entrée. La valeur GEOGRAPHY
d'entrée est simplifiée en remplaçant les suites d'arêtes courtes presque rectilignes par une arête longue unique. Les modifications apportées à la valeur geography
d'entrée n'excèdent pas la tolérance tolerance_meters
spécifiée. C'est-à-dire que les arêtes simplifiées passent nécessairement dans les limites (tolerance_meters
) des positions d'origine des sommets supprimés sur cette arête. La valeur tolerance_meters
donnée est exprimée en mètres sur la surface de la Terre.
Notez que la fonction ST_SIMPLIFY
conserve les relations topologiques, ce qui implique que les nouvelles arêtes ne se croisent pas et que le résultat est valide. Lorsque la tolérance est importante, les formes peuvent se simplifier en des formes de plus petites dimensions, et les formes adjacentes peuvent fusionner entre elles.
Contraintes
La valeur de tolerance_meters
doit être différente de zéro pour que la fonction ST_SIMPLIFY
ait un effet.
ST_SIMPLIFY
renvoie une erreur si la tolérance tolerance_meters
spécifiée est :
- une tolérance négative ;
- une tolérance supérieure à ~ 7 800 kilomètres.
Type renvoyé
GEOGRAPHY
Exemples
L'exemple suivant montre comment la fonction ST_SIMPLIFY
simplifie la ligne GEOGRAPHY
d'entrée en supprimant les sommets intermédiaires.
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) |
+---------------------------------------------+----------------------+
L'exemple suivant illustre le cas où le résultat de la fonction ST_SIMPLIFY
a une dimension plus petite que la forme d'origine.
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)
Description
Renvoie la valeur GEOGRAPHY
d'entrée, où chaque sommet a été ancré à une grille de longitude/latitude. La taille de la grille est déterminée par le paramètre grid_size
, qui est exprimé en degrés.
Contraintes
Les tailles de grille arbitraires ne sont pas acceptées. Le paramètre grid_size
est arrondi de sorte qu'il se présente sous la forme 10^n
, où -10 < n < 0
.
Type renvoyé
GEOGRAPHY
ST_STARTPOINT
ST_STARTPOINT(linestring_geography)
Description
Renvoie le premier point d'une zone géographique en polyligne en tant que géographie de points. Renvoie une erreur si l'entrée n'est pas une polyligne ou si l'entrée est vide. Utilisez le préfixe SAFE
pour obtenir NULL
en cas d'entrée non valide à la place d'une erreur.
Type renvoyé
Point GEOGRAPHY
Exemple
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)
Description
Renvoie TRUE
pour autant que les deux conditions suivantes soient remplies :
geography_1
etgeography_2
s'entrecroisent.- L'intérieur de
geography_1
et l'intérieur degeography_2
sont disjoints.
Type renvoyé
BOOL
ST_UNION
ST_UNION(geography_1, geography_2)
ST_UNION(array_of_geography)
Description
Renvoie une valeur GEOGRAPHY
représentant l'union des ensembles de points de toutes les valeurs GEOGRAPHY
d'entrée.
ST_UNION
comporte deux variantes. Pour la première variante, l'entrée consiste en deux valeurs GEOGRAPHY
. Pour la deuxième, l'entrée est un ARRAY
de type GEOGRAPHY
.
Pour la première variante de ST_UNION
, si une entrée GEOGRAPHY
est NULL
, ST_UNION
renvoie NULL
.
Pour la seconde variante, si la valeur ARRAY
d'entrée est NULL
, ST_UNION
renvoie NULL
.
Pour un ARRAY
d'entrée non-NULL
, l'union est calculée et les éléments NULL
sont ignorés afin qu'ils n'affectent pas la sortie.
Pour en savoir plus sur la version agrégée de ST_UNION
, consultez la section sur la fonction ST_UNION_AGG
.
Type renvoyé
GEOGRAPHY
ST_UNION_AGG
ST_UNION_AGG(geography)
Description
Renvoie une valeur GEOGRAPHY
représentant l'union des ensembles de points de toutes les valeurs GEOGRAPHY
d'entrée.
ST_UNION_AGG
ignore les valeurs GEOGRAPHY
d'entrée NULL
.
Pour en savoir plus sur la version non agrégée de ST_UNION_AGG
, consultez la section sur la fonction ST_UNION
.
Type renvoyé
GEOGRAPHY
ST_WITHIN
ST_WITHIN(geography_1, geography_2)
Description
Renvoie TRUE
si aucun point de geography_1
n'est en dehors de geography_2
, et que les intérieurs de geography_1
et geography_2
s'entrecroisent.
Pour deux zones géographiques nommées a
et b
, ST_WITHIN(a, b)
renvoie le même résultat que ST_CONTAINS
(b, a)
. Notez l'ordre inverse des arguments.
Type renvoyé
BOOL
ST_X
ST_X(geography_expression)
Description
Renvoie la longitude en degrés de la valeur GEOGRAPHY
d'entrée à un seul point.
Pour toute valeur GEOGRAPHY
d'entrée qui n'est pas constituée d'un seul point, y compris une valeur GEOGRAPHY
vide, ST_X
renvoie une erreur. Utilisez le préfixe SAFE.
pour obtenir NULL
.
Type renvoyé
FLOAT64
Exemple
L'exemple suivant utilise ST_X
et ST_Y
pour extraire les coordonnées de zones géographiques à un seul point.
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)
Description
Renvoie la latitude en degrés de la valeur GEOGRAPHY
d'entrée à un seul point.
Pour toute valeur GEOGRAPHY
d'entrée qui n'est pas constituée d'un seul point, y compris une valeur GEOGRAPHY
vide, ST_Y
renvoie une erreur. Utilisez le préfixe SAFE.
pour renvoyer NULL
à la place.
Type renvoyé
FLOAT64
Exemple
Pour voir un exemple d'utilisation, consultez la section sur la fonction ST_X
.