Fonctions de géographie

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

GoogleSQL pour BigQuery est compatible avec les fonctions de géographie. Les fonctions de géographie effectuent des opérations sur des valeurs GEOGRAPHY SQL, ou en génèrent. La signature de la plupart des fonctions de géographie commence par ST_. GoogleSQL pour 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 GoogleSQL renvoient NULL si l'un des arguments d'entrée est NULL.

Categories

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_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_ISCLOSED
ST_ISCOLLECTION
ST_ISEMPTY
ST_ISRING
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 INT64paramè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 un GEOGRAPHY 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 GoogleSQL 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, GoogleSQL 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) AS geo1, ST_GEOGPOINT(0, 0) AS 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), ST_GEOGPOINT(0, 0) 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 est NULL 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 : valeur GEOGRAPHY 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érateur buffer_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 est 8.0. Nommer cet argument est facultatif.
  • endcap (facultatif) : STRING vous permet de spécifier l'un des deux styles de fin : ROUND et FLAT. La valeur par défaut est ROUND. 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 et RIGHT. La valeur par défaut est BOTH. 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 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é

Polygone 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 : valeur GEOGRAPHY 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érateur buffer_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 et FLAT. La valeur par défaut est ROUND. 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 et RIGHT. La valeur par défaut est BOTH. 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 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é

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

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

Point GEOGRAPHY

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é

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

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.
  • 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 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. 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 GoogleSQL 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. Si la valeur de use_spheroid est TRUE, la fonction mesure la distance sur la surface du sphéroïde WGS84. 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<GEOGRAPHY>

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