Fonctions de géographie en SQL standard

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_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_CENTROID` `ST_CENTROID_AGG` (agrégation) `ST_CLOSESTPOINT` `ST_CONVEXHULL` `ST_DIFFERENCE` `ST_DUMP` `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_ISCOLLECTION` `ST_ISEMPTY` `ST_NPOINTS` `ST_NUMPOINTS` `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_AREA` `ST_DISTANCE` `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 partitionnement sur des zones géographiques.

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

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 (...)

Effectue un partitionnement DBSCAN sur une colonne de zones géographiques. Renvoie un numéro de cluster basé sur 0.

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 valeur FLOAT64 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 valeur INT64 non négative.
OVER : spécifie une fenêtre. Consultez la page consacrée aux fonctions analytiques. L'utilisation de la clause OVER dans le cadre de ST_CLUSTERDBSCAN est compatible avec les éléments suivants :
- PARTITION BY : facultatif.
- ORDER BY : facultatif.
- window_frame_clause : non autorisée.

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 valeur minimum_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 valeur GEOGRAPHY vide est toujours classée comme bruit.

Contraintes

L'argument minimum_geographies est une valeur INT64 non négative et epsilon une valeur FLOAT64 non négative.
L'objet géographique EMPTY ne peut rejoindre 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 renvoie NULL si l'entrée est NULL ou s'il s'agit d'un objet GEOGRAPHY 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.

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

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.

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.

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

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 ou GeometryCollection. Tout autre type GeoJSON, tel que Feature ou FeatureCollection 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 membre coordinates.

Type renvoyé

GEOGRAPHY

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 suffixe M.
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'utiliser ST_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 suffixe M.
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 et planar ne peuvent pas simultanément être égales à TRUE.
Les valeurs oriented et make_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

Renvoie une représentation GeoHash de geography_expression. Le GeoHash résultant contiendra au maximum maxchars caractères. Un nombre moins important de caractères correspond à une précision inférieure (ou, autrement dit, à un cadre de délimitation plus grand).

L'exécution de ST_GeoHash sur un objet GEOGRAPHY vide renvoie NULL.

Contraintes

Seuls les objets GEOGRAPHY représentant des points uniques sont acceptés.
La valeur maximale de maxchars est 20.

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

Type renvoyé

STRING

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 minimale et maximale qui délimitent le rectangle. lat1 et lat2 spécifient les lignes constantes de latitude 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 être comprises dans la plage [-180, 180] degrés.

Type renvoyé

BOOL

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.

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.

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

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

ST_TOUCHES(geography_1, geography_2)

Description

Renvoie TRUE pour autant que les deux conditions suivantes soient remplies :

geography_1 et geography_2 s'entrecroisent.
L'intérieur de geography_1 et l'intérieur de geography_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.