Geografische Funktionen

GoogleSQL for BigQuery unterstützt geografische Funktionen. Geografische Funktionen werden auf GoogleSQL-GEOGRAPHY-Werte angewendet oder generieren sie. Die Signatur der meisten geografischen Funktionen beginnt mit ST_. GoogleSQL unterstützt die folgenden Funktionen, mit denen geografische Daten analysiert, räumliche Beziehungen zwischen geografischen Merkmalen bestimmt und GEOGRAPHYs erstellt oder bearbeitet werden können.

Alle geografischen Funktionen von GoogleSQL geben NULL zurück, wenn eines der Eingabeargumente NULL ist.

Kategorien

Die geografischen Funktionen werden auf der Grundlage ihres Verhaltens in folgende Kategorien eingeteilt:

Kategorie	Funktionen	Beschreibung
Konstruktoren	`ST_GEOGPOINT` `ST_MAKELINE` `ST_MAKEPOLYGON` `ST_MAKEPOLYGONORIENTED`	Funktionen, die neue geografische Werte aus Koordinaten oder vorhandenen Regionen erstellen.
Parser	`ST_GEOGFROM` `ST_GEOGFROMGEOJSON` `ST_GEOGFROMTEXT` `ST_GEOGFROMWKB` `ST_GEOGPOINTFROMGEOHASH`	Funktionen, die Regionen aus einem externen Format wie WKT und GeoJSON erstellen.
Formatierer	`ST_ASBINARY` `ST_ASGEOJSON` `ST_ASTEXT` `ST_GEOHASH`	Funktionen, die Regionen in ein externes Format wie WKT exportieren.
Transformationen	`ST_BOUNDARY` `ST_BUFFER` `ST_BUFFERWITHTOLERANCE` `ST_CENTROID` `ST_CENTROID_AGG` (Aggregiert) `ST_CLOSESTPOINT` `ST_CONVEXHULL` `ST_DIFFERENCE` `ST_EXTERIORRING` `ST_INTERIORRINGS` `ST_INTERSECTION` `ST_SIMPLIFY` `ST_SNAPTOGRID` `ST_UNION` `ST_UNION_AGG` (Aggregiert)	Funktionen, die basierend auf Eingaben eine neue Region generieren.
Zugriffsfunktionen	`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`	Funktionen, die Zugriff auf Attribute einer Region ohne Nebeneffekte ermöglichen.
Prädikate	`ST_CONTAINS` `ST_COVEREDBY` `ST_COVERS` `ST_DISJOINT` `ST_DWITHIN` `ST_EQUALS` `ST_INTERSECTS` `ST_INTERSECTSBOX` `ST_TOUCHES` `ST_WITHIN`	Funktionen, die `TRUE` oder `FALSE` für eine bestimmte räumliche Beziehung zwischen zwei Regionen oder einigen Attributen einer Region zurückgeben. Diese Funktionen werden häufig in Filterklauseln verwendet.
Messung	`ST_ANGLE` `ST_AREA` `ST_AZIMUTH` `ST_BOUNDINGBOX` `ST_DISTANCE` `ST_EXTENT` (Aggregate) `ST_LENGTH` `ST_MAXDISTANCE` `ST_PERIMETER`	Funktionen, die Messwerte einer oder mehrerer Regionen berechnen.
Clustering	`ST_CLUSTERDBSCAN`	Funktionen, die Clustering für Regionen ausführen.
S2-Funktionen	`S2_CELLIDFROMPOINT` `S2_COVERINGCELLIDS`	Funktionen für die Arbeit mit S2-Zellabdeckungen von GEOGRAPHY.

`S2_CELLIDFROMPOINT`

S2_CELLIDFROMPOINT(point_geography[, level => cell_level])

Beschreibung

Gibt die S2-Zellen-ID zurück, die einen Punkt GEOGRAPHY abdeckt.

Der optionale INT64-Parameter level gibt die S2-Zellebene für die zurückgegebene Zelle an. Die Benennung dieses Arguments ist optional.

Dies ist eine erweiterte Funktionalität für die Interoperabilität mit Systemen, die die S2 Geometry-Bibliothek verwenden.

Einschränkungen

Gibt die Zellen-ID als INT64-Bit mit Vorzeichen zurück, das der vorzeichenlosen 64-Bit-Ganzzahldarstellung entspricht.
Kann negative Zellen-IDs zurückgeben.
Gültige S2-Zellenebenen sind 0 bis 30.
level ist standardmäßig 30, wenn nicht explizit angegeben.
Die Funktion unterstützt nur eine Einzelpunkt-GEOGRAPHY. Verwenden Sie das Präfix SAFE, wenn die Eingabe ein Multipunkt, ein LineString, ein Polygon oder eine leere GEOGRAPHY sein kann.
Verwenden Sie S2_COVERINGCELLIDS, um die Abdeckung einer komplexen GEOGRAPHY zu berechnen.

Rückgabetyp

INT64

Beispiel

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

Beschreibung

Gibt ein Array von S2-Zellen-IDs zurück, die die Eingabe-GEOGRAPHY abdeckt. Die Funktion gibt höchstens max_cells Zellen zurück. Die optionalen Argumente min_level und max_level geben Mindest- und Höchstwerte für die zurückgegebenen S2-Zellen an. Die Arraygröße wird durch das optionale Argument max_cells begrenzt. Das optionale Argument buffer gibt einen Pufferfaktor in Metern an. Die zu erfassende Region wird von der Ausdehnung der Eingabegeografie um diesen Betrag erweitert.

Dies ist eine erweiterte Funktionalität für die Interoperabilität mit Systemen, die die S2 Geometry-Bibliothek verwenden.

Einschränkungen

Gibt die Zellen-ID als INT64-Bit mit Vorzeichen zurück, das der vorzeichenlosen 64-Bit-Ganzzahldarstellung entspricht.
Kann negative Zellen-IDs zurückgeben.
Gültige S2-Zellenebenen sind 0 bis 30.
max_cells ist standardmäßig 8, wenn nicht explizit angegeben.
buffer darf nicht negativ sein. Standardmäßig wird 0,0 Meter verwendet, wenn nicht explizit angegeben.

Rückgabetyp

ARRAY<INT64>

Beispiel

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)

Beschreibung

Verwendet Drei-Punkt-Werte für GEOGRAPHY, die zwei sich überschneidende Linien darstellen. Gibt den Winkel zwischen diesen Linien zurück. Punkt 2 und Punkt 1 stellen die erste Linie dar und Punkt 2 und Punkt 3 stellen die zweite Linie dar. Der Winkel zwischen diesen Linien wird im Bogenmaß angegeben und liegt im Bereich [0, 2pi). Der Winkel wird von der ersten Linie bis zur zweiten Linie im Uhrzeigersinn gemessen.

ST_ANGLE hat folgende Sonderfälle:

Wenn die Punkte 2 und 3 identisch sind, wird NULL zurückgegeben.
Wenn die Punkte 2 und 1 identisch sind, wird NULL zurückgegeben.
Wenn die Punkte 2 und 3 genau entgegengesetzt sind, wird NULL zurückgegeben.
Wenn die Punkte 2 und 1 genau entgegengesetzt sind, wird NULL zurückgegeben.
Wenn eine der Eingabe-Geografien keine einzelnen Punkte oder leer sind wird ein Fehler ausgegeben.

Rückgabetyp

FLOAT64

Beispiel

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

Beschreibung

Gibt die Fläche in Quadratmetern zurück, die von den Polygonen in der Eingabe-GEOGRAPHY abgedeckt wird.

Wenn geography_expression ein Punkt oder eine Linie ist, wird null zurückgegeben. Ist geography_expression eine Sammlung, wird die Fläche der Polygone in der Sammlung zurückgegeben. Enthält die Sammlung keine Polygone, wird null zurückgegeben.

Der optionale Parameter use_spheroid bestimmt, wie diese Funktion die Entfernung misst. Wenn use_spheroid auf FALSE gesetzt ist, misst die Funktion die Entfernung auf der Oberfläche einer perfekten Kugel.

Der Parameter use_spheroid unterstützt derzeit nur den Wert FALSE. FALSE ist auch der Standardwert von use_spheroid.

Rückgabetyp

FLOAT64

`ST_ASBINARY`

ST_ASBINARY(geography_expression)

Beschreibung

Gibt die WKB-Darstellung einer Eingabe-GEOGRAPHY zurück.

Unter ST_GEOGFROMWKB erfahren Sie, wie Sie eine GEOGRAPHY aus WKB erstellen.

Rückgabetyp

BYTES

`ST_ASGEOJSON`

ST_ASGEOJSON(geography_expression)

Beschreibung

Gibt die RFC 7946-konforme GeoJSON-Darstellung der Eingabe-GEOGRAPHY zurück.

Eine GEOGRAPHY von GoogleSQL hat sphärische geodätische Kanten, während ein Geometry-Objekt im GeoJSON-Format explizit planare Kanten hat. Zur Umwandlung dieser zwei Arten von Kanten fügt GoogleSQL der Linie bei Bedarf zusätzliche Punkte hinzu, sodass die resultierende Abfolge von Kanten im Umkreis von zehn Metern zur ursprünglichen Kante bleibt.

Unter ST_GEOGFROMGEOJSON erfahren Sie, wie Sie eine GEOGRAPHY aus GeoJSON erstellen.

Rückgabetyp

STRING

`ST_ASTEXT`

ST_ASTEXT(geography_expression)

Beschreibung

Gibt die WKT-Darstellung einer Eingabe-GEOGRAPHY zurück.

Unter ST_GEOGFROMTEXT erfahren Sie, wie Sie eine GEOGRAPHY aus WKT erstellen.

Rückgabetyp

STRING

`ST_AZIMUTH`

ST_AZIMUTH(point_geography_1, point_geography_2)

Beschreibung

Nimmt zwei Punkt-GEOGRAPHY-Werte an und gibt den Azimut des Liniensegment zurück, das durch die Punkte 1 und 2 gebildet wird. Der Azimut ist der Winkel im Bogenmaß, der zwischen der Linie von Punkt 1 gegenüber dem Liniensegment von Punkt 1 zum Punkt 2 gemessen wird.

Der positive Winkel wird auf der Oberfläche einer Sphäre im Uhrzeigersinn gemessen. Beispiel: der Azimut für ein Liniensegment:

Nordwärts gerichtet ist 0
Ostwärts gerichtet ist PI/2
Südwärts gerichtet ist PI
Westwärts gerichtet ist 3PI/2

ST_AZIMUTH hat folgende Sonderfälle:

Wenn beide Eingabepunkte gleich sind, wird NULL zurückgegeben.
Wenn die beiden Eingabepunkte genau entgegengesetzt sind, wird NULL zurückgegeben.
Wenn eine der Eingabegeografien keine einzelnen Punkte oder leer sind, wird ein Fehler ausgegeben.

Rückgabetyp

FLOAT64

Beispiel

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)

Beschreibung

Gibt eine einzelne GEOGRAPHY zurück, die die Vereinigung der Grenzen aller Komponenten in der jeweiligen Eingabe-GEOGRAPHY enthält.

Die Grenze der einzelnen Komponenten einer GEOGRAPHY ist so definiert:

Die Grenze eines Punkts ist leer.
Die Grenze eines Linienzugs besteht aus den Endpunkten des Linienzugs.
Die Grenze eines Polygons besteht aus den Linienzügen, die die Polygonhülle und die einzelnen Löcher des Polygons bilden.

Rückgabetyp

GEOGRAPHY

`ST_BOUNDINGBOX`

ST_BOUNDINGBOX(geography_expression)

Beschreibung

Gibt ein STRUCT zurück, das den Begrenzungsrahmen für die angegebene Geografie darstellt. Der Begrenzungsrahmen ist das minimale Rechteck, das die Geografie einschließt. Die Kanten des Rechtecks folgen konstanten Längen- und Breitengradlinien.

Vorsichtsmaßnahmen:

Gibt NULL zurück, wenn die Eingabe NULL oder eine leere Geografie ist.
Der Begrenzungsrahmen kann den Antimeridian kreuzen, wenn dadurch ein kleineres Rechteck möglich ist. In diesem Fall liegt eine der Längsbegrenzungen des Begrenzungsrahmens außerhalb des Bereichs [-180, 180], sodass xmin kleiner ist als der östlichste Wert xmax.

Rückgabetyp

STRUCT<xmin FLOAT64, ymin FLOAT64, xmax FLOAT64, ymax FLOAT64>.

Teile des Begrenzungsrahmens:

xmin: Die westlichste konstante Längengradlinie, die das Rechteck umgrenzt.
xmax: Die östlichste konstante Längengradlinie, die das Rechteck umgrenzt.
ymin: Die minimale konstante Breitengradlinie, die das Rechteck umgrenzt.
ymax: Die maximale konstante Breitengradlinie, die das Rechteck begrenzt.

Beispiel

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

Die Aggregatversion von ST_BOUNDINGBOX finden Sie unter 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])

Beschreibung

Gibt eine GEOGRAPHY zurück, die den Zwischenspeicher um die Eingabe-GEOGRAPHY darstellt. Diese Funktion entspricht ST_BUFFERWITHTOLERANCE, Sie geben jedoch die Anzahl der Segmente an, anstatt eine Toleranz anzugeben, um zu bestimmen, wie stark die resultierende Geografie vom idealen Zwischenspeicherradius abweichen darf.

geography: Die Eingabe-GEOGRAPHY, die mit dem Zwischenspeicherradius eingekreist werden soll.
buffer_radius: DOUBLE-Wert, der den Radius des Zwischenspeichers um die Eingabegeografie darstellt. Der Radius wird in Metern angegeben. Beachten Sie, dass Polygone beim Zwischenspeichern mit einem negativen buffer_radius kontrahieren. Polygonschalen und -löcher, die auf einen Punkt kontrahiert sind, werden verworfen.
num_seg_quarter_circle: (Optional) DOUBLE, das die Anzahl der Segmente angibt, die zur Annäherung an einen Viertelkreis verwendet werden. Der Standardwert ist 8.0. Die Benennung dieses Arguments ist optional.
endcap: (Optional) STRING, mit dem Sie einen von zwei endcap-Formaten angeben können: ROUND und FLAT. Der Standardwert ist ROUND. Diese Option wirkt sich nur auf die endcaps von zwischengespeicherten Linienzügen aus.
side: (Optional) STRING, mit dem Sie eine von drei Möglichkeiten für die Linien angeben können: BOTH, LEFT und RIGHT. Der Standardwert ist BOTH. Diese Option wirkt sich nur auf die Art und Weise aus, wie Linienzüge zwischengespeichert werden.
use_spheroid: (Optional) BOOL, der bestimmt, wie diese Funktion die Entfernung misst. Wenn use_spheroid auf FALSE gesetzt ist, misst die Funktion die Entfernung auf der Oberfläche einer perfekten Kugel. Der Parameter use_spheroid unterstützt derzeit nur den Wert FALSE. Der Standardwert von use_spheroid ist FALSE.

Rückgabetyp

Polygon GEOGRAPHY

Beispiel

Im folgenden Beispiel wird das Ergebnis von ST_BUFFER für einen Punkt dargestellt. Ein Punkt im Zwischenspeicher ist ungefähr ein Kreis. Bei num_seg_quarter_circle = 2 gibt es zwei Liniensegmente in einem Viertelkreis. Der Kreis im Zwischenspeicher hat daher acht Seiten und ST_NUMPOINTS gibt neun Eckpunkte zurück. Bei num_seg_quarter_circle = 8 gibt es acht Liniensegmente in einem Viertelkreis, sodass der Kreis im Zwischenspeicher 22 Seiten hat und ST_NUMPOINTS 33 Eckpunkte zurückgibt.

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

Gibt eine GEOGRAPHY zurück, die den Zwischenspeicher um die Eingabe-GEOGRAPHY darstellt. Diese Funktion entspricht ST_BUFFER, Sie legen jedoch eine Toleranz anstelle von Segmenten fest, um zu bestimmen, wie stark die resultierende Geografie vom idealen Zwischenspeicherradius abweichen kann.

geography: Die Eingabe-GEOGRAPHY, die mit dem Zwischenspeicherradius eingekreist werden soll.
buffer_radius: DOUBLE-Wert, der den Radius des Zwischenspeichers um die Eingabegeografie darstellt. Der Radius wird in Metern angegeben. Beachten Sie, dass Polygone beim Zwischenspeichern mit einem negativen buffer_radius kontrahieren. Polygonschalen und -löcher, die auf einen Punkt kontrahiert sind, werden verworfen.
tolerance_meters: DOUBLE-Wert gibt eine Toleranz in Metern an, mit der die Form approximiert wird. Die Toleranz bestimmt, wie stark ein Polygon vom idealen Radius abweichen kann. Die Benennung dieses Arguments ist optional.
endcap: (Optional) STRING, mit dem Sie einen von zwei endcap-Formaten angeben können: ROUND und FLAT. Der Standardwert ist ROUND. Diese Option wirkt sich nur auf die endcaps von zwischengespeicherten Linienzügen aus.
side: (Optional) STRING, mit dem Sie eine von drei möglichen Linienformaten angeben können: BOTH, LEFT und RIGHT. Der Standardwert ist BOTH. Diese Option wirkt sich nur auf die endcaps von zwischengespeicherten Linienzügen aus.
use_spheroid: (Optional) BOOL, der bestimmt, wie diese Funktion die Entfernung misst. Wenn use_spheroid auf FALSE gesetzt ist, misst die Funktion die Entfernung auf der Oberfläche einer perfekten Kugel. Der Parameter use_spheroid unterstützt derzeit nur den Wert FALSE. Der Standardwert von use_spheroid ist FALSE.

Rückgabetyp

Polygon GEOGRAPHY

Beispiel

Das folgende Beispiel zeigt die Ergebnisse von ST_BUFFERWITHTOLERANCE für einen Punkt bei zwei verschiedenen Werten für die Toleranz, aber mit demselben Zwischenspeicherradius von 100. Ein Punkt im Zwischenspeicher ist ungefähr ein Kreis. Bei tolerance_meters=25 ist die Toleranz ein hoher Prozentsatz des Zwischenspeicherradius. Daher werden nur fünf Segmente verwendet, um einen Kreis um den Eingabepunkt anzunähern. Bei tolerance_meters=1 ist die Toleranz ein wesentlich kleinerer Prozentsatz des Zwischenspeicherradius. Daher werden vierundzwanzig Kanten verwendet, um einen Kreis um den Eingabepunkt anzunähern.

SELECT
  -- tolerance_meters=25, or 25% of the buffer radius.
  ST_NumPoints(ST_BUFFERWITHTOLERANCE(ST_GEOGFROMTEXT('POINT(1 2)'), 100, 25)) AS five_sides,
  -- tolerance_meters=1, or 1% of the buffer radius.
  st_NumPoints(ST_BUFFERWITHTOLERANCE(ST_GEOGFROMTEXT('POINT(100 2)'), 100, 1)) AS twenty_four_sides;

+------------+-------------------+
| five_sides | twenty_four_sides |
+------------+-------------------+
| 6          | 24                |
+------------+-------------------+

`ST_CENTROID`

ST_CENTROID(geography_expression)

Beschreibung

Gibt den Schwerpunkt der Eingabe-GEOGRAPHY als Einzelpunkt-GEOGRAPHY zurück.

Der Schwerpunkt einer GEOGRAPHY ist der gewichtete Durchschnitt der Schwerpunkte der Komponenten mit der höchsten Dimension in der GEOGRAPHY. Der Schwerpunkt für Komponenten in den einzelnen Dimensionen wird so definiert:

Der Schwerpunkt von Punkten ist das arithmetische Mittel der Eingabekoordinaten.
Der Schwerpunkt von Linienzügen ist der Schwerpunkt aller nach der Länge gewichteten Kanten. Der Schwerpunkt jeder Kante ist der geodätische Mittelpunkt der Kante.
Der Schwerpunkt eines Polygons ist sein Massenmittelpunkt.

Wenn die Eingabe-GEOGRAPHY leer ist, wird eine leere GEOGRAPHY zurückgegeben.

Einschränkungen

Im unwahrscheinlichen Fall, dass der Schwerpunkt einer GEOGRAPHY nicht durch einen einzelnen Punkt auf der Erdoberfläche definiert werden kann, wird ein deterministischer, aber ansonsten beliebiger Punkt zurückgegeben. Dies kann nur geschehen, wenn sich der Schwerpunkt genau am Mittelpunkt der Erde befindet. Ein Beispiel hierfür wäre der Schwerpunkt von zwei antipodisch gelegenen Punkten. Die Wahrscheinlichkeit, dass dieser Fall eintritt, ist jedoch verschwindend gering.

Rückgabetyp

Punkt GEOGRAPHY

`ST_CENTROID_AGG`

ST_CENTROID_AGG(geography)

Beschreibung

Berechnet den Schwerpunkt der Gruppe von Eingabe-GEOGRAPHYs als Einzelpunkt-GEOGRAPHY.

Der Schwerpunkt der Gruppe von Eingabe-GEOGRAPHYs ist der gewichtete Durchschnitt der Schwerpunkte der einzelnen GEOGRAPHYs. Nur die GEOGRAPHYs mit der höchsten Dimension in der Eingabe fließen in den Schwerpunkt der gesamten Gruppe ein. Wenn die Eingabe beispielsweise sowohl GEOGRAPHYs mit Linien als auch GEOGRAPHYs nur mit Punkten enthält, gibt ST_CENTROID_AGG den gewichteten Durchschnitt der GEOGRAPHYs mit Linien zurück, da diese die höchste Dimension haben. In diesem Beispiel werden GEOGRAPHYs, die nur Punkte enthalten, von ST_CENTROID_AGG beim Berechnen des aggregierten Schwerpunkts ignoriert.

ST_CENTROID_AGG ignoriert Eingabe-GEOGRAPHYs mit NULL-Werten.

Unter ST_CENTROID finden Sie die Version von ST_CENTROID_AGG ohne Aggregation und die Definition des Schwerpunkts für einen einzelnen GEOGRAPHY-Wert.

Rückgabetyp

Punkt GEOGRAPHY

Beispiel

Die folgenden Abfragen berechnen den aggregierten Schwerpunkt einer Gruppe von GEOGRAPHY-Werten. Die Eingabe für die erste Abfrage enthält nur Punkte. Daher fließt jeder Wert in den aggregierten Schwerpunkt ein. Beachten Sie außerdem, dass ST_CENTROID_AGG nicht dem Aufruf von ST_CENTROID für das Ergebnis von ST_UNION_AGG entspricht. Im Gegensatz zu ST_CENTROID_AGG werden Duplikate von der Vereinigung entfernt. Die Eingabe für die zweite Abfrage enthält gemischte Dimensionen, sodass sich nur die Werte mit der höchsten Dimension in der Gruppe (die Linien) auf den aggregierten Schwerpunkt auswirken.

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

Beschreibung

Gibt eine GEOGRAPHY zurück, die einen Punkt in geography_1 mit der kleinstmöglichen Entfernung zu geography_2 enthält. Dies impliziert, dass die Entfernung zwischen dem von ST_CLOSESTPOINT zurückgegebenen Punkt und geography_2 kleiner oder gleich der Entfernung zwischen jedem anderen Punkt in geography_1 und geography_2 ist.

Wenn eine der Eingabe-GEOGRAPHYs leer ist, gibt ST_CLOSESTPOINT den Wert NULL zurück.

Der Parameter use_spheroid unterstützt derzeit nur den Wert FALSE. FALSE ist auch der Standardwert von use_spheroid.

Rückgabetyp

Punkt 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 }  ] [, ...] ]

Führt DBSCAN-Clustering für eine Spalte mit Regionen aus. Gibt eine 0-basierte Clusternummer zurück.

Weitere Informationen zur OVER-Klausel und deren Verwendung finden Sie unter Fensterfunktionsaufrufe.

Eingabeparameter

geography_column: Eine Spalte von GEOGRAPHYs, die geclustert sind.
epsilon: Der Epilson, der den Radius in Metern um einen Kernwert angibt. Nicht negativer Wert für FLOAT64.
minimum_geographies: Gibt die Mindestanzahl der Standorte in einem einzelnen Cluster an. Nur eine dichte Eingabe bildet einen Cluster, andernfalls wird sie als Rauschen klassifiziert. Nicht negativer Wert für INT64.

Geografische Typen und der DBSCAN-Algorithmus

Der DBSCAN-Algorithmus erkennt hochrangige Cluster von Daten und kennzeichnet Ausreißer in Nebengeräuschbereichen. Mit geography_column übergebene Geografieregionen werden vom DBSCAN-Algorithmus auf eine von drei Arten klassifiziert:

Grundwert: Eine Geografie ist ein Kernwert, wenn sie sich innerhalb von epsilon-Entfernung von minimum_geographies-Geografien, einschließlich sich selbst befindet. Der Kernwert startet einen neuen Cluster oder wird demselben Cluster als Kernwert innerhalb der epsilon-Entfernung hinzugefügt. Kernwerte werden in einem Cluster mit allen anderen Kern- und Randwerten gruppiert, die sich innerhalb der epsilon-Entfernung befinden.
Randwert: Eine Geografie ist ein Randwert, wenn sie innerhalb einer Epilson-Entfernung eines Kernwerts liegt. Sie wird zum selben Cluster als Kernwert innerhalb der epsilon-Entfernung hinzugefügt. Ein Randwert kann innerhalb von epsilon-Entfernungen mehrerer Cluster liegen. In diesem Fall kann sie willkürlich einem Cluster zugewiesen werden und die Funktion führt für nachfolgende Aufrufe das gleiche Ergebnis.
Nebengeräusch: Eine geografische Umgebung ist ein Nebengeräusch, wenn sie weder ein Kern- noch ein Randwert ist. Nebengeräuschwerte werden einem NULL-Cluster zugewiesen. Eine leere GEOGRAPHY wird immer als Nebengeräusch klassifiziert.

Einschränkungen

Das Argument minimum_geographies ist ein nicht negativer Wert INT64 und epsilon ist ein nicht negativer Wert FLOAT64.
Eine leere Geografie kann keinem Cluster hinzugefügt werden.
Für einen Randwert sind mehrere Clustering-Zuweisungen möglich. Wenn eine Geografie ein Randwert ist, weist ST_CLUSTERDBSCAN sie einem beliebigen gültigen Cluster zu.

Rückgabetyp

INT64 für jede Region in der Spalte "Geografie".

Beispiele

In diesem Beispiel wird das DBSCAN-Clustering mit einem Radius von 100.000 Metern und einem Argument minimum_geographies von 1 ausgeführt. Die analysierten Geografien sind eine Mischung aus Punkten, Linien und Polygonen.

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)

Beschreibung

Gibt TRUE zurück, wenn kein Punkt von geography_2 außerhalb von geography_1 liegt und sich das Innere der Geografien schneidet. Andernfalls wird FALSE zurückgegeben.

HINWEIS: Eine GEOGRAPHY enthält nicht ihre eigene Grenze. Zum Vergleich: ST_COVERS.

Rückgabetyp

BOOL

Beispiel

Die folgende Abfrage prüft, ob das Polygon POLYGON((1 1, 20 1, 10 20, 1 1)) jeden der drei Punkte (0, 0), (1, 1) und (10, 10) enthält, die jeweils außerhalb, auf der Grenze bzw. innerhalb des Polygons liegen.

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)

Beschreibung

Gibt die konvexe Struktur für den Eingabe-GEOGRAPHY zurück. Die konvexe Hülle ist die kleinste konvexe GEOGRAPHY, die die Eingabe abdeckt. GEOGRAPHY ist konvex, wenn für jedes Punktpaar in GEOGRAPHY eine geodätische Kante, die die Punkte verbindet, ebenfalls in derselben GEOGRAPHY enthalten ist.

In den meisten Fällen besteht die konvexe Hülle aus einem einzelnen Polygon. Wichtige Grenzfälle sind:

Die konvexe Hüle eines einzelnen Punkts ist ebenfalls ein Punkt.
Die konvexe Hülle von zwei oder mehr kollinearen Punkten ist ein Linienzug, solange dieser "konvex" ist.
Wenn der Eingabe-GEOGRAPHY mehr als eine Hemisphäre umfasst, ist die konvexe Hülle der gesamte Globus. Dazu gehören alle Eingaben, die ein Paar antipodaler Punkte enthalten.
ST_CONVEXHULL gibt NULL zurück, wenn die Eingabe entweder NULL oder die leere GEOGRAPHY ist.

Rückgabetyp

GEOGRAPHY

Beispiele

Bei der von ST_CONVEXHULL zurückgegebenen konvexen Hülle kann es sich je nach Eingabe um einen Punkt, einen Linienzug oder ein Polygon handeln.

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)

Beschreibung

Gibt FALSE zurück, wenn geography_1 oder geography_2 leer ist. Gibt TRUE zurück, wenn keine Punkte von geography_1 außerhalb von geography_2 liegen.

Bei zwei GEOGRAPHYs a und b gibt ST_COVEREDBY(a, b) dasselbe Ergebnis zurück wie ST_COVERS(b, a). Beachten Sie die umgekehrte Reihenfolge der Argumente.

Rückgabetyp

BOOL

`ST_COVERS`

ST_COVERS(geography_1, geography_2)

Beschreibung

Gibt FALSE zurück, wenn geography_1 oder geography_2 leer ist. Gibt TRUE zurück, wenn keine Punkte von geography_2 außerhalb von geography_1 liegen.

Rückgabetyp

BOOL

Beispiel

Die folgende Abfrage prüft, ob das Polygon POLYGON((1 1, 20 1, 10 20, 1 1)) jeden der drei Punkte (0, 0), (1, 1) und (10, 10) abdeckt, die jeweils außerhalb, auf der Grenze bzw. innerhalb des Polygons liegen.

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)

Beschreibung

Gibt eine GEOGRAPHY zurück, die die Punktmengendifferenz von geography_1 und geography_2 darstellt. Daher besteht das Ergebnis aus dem Teil von geography_1, der sich nicht mit geography_2 überschneidet.

Wenn geometry_1 vollständig in geometry_2 enthalten ist, gibt ST_DIFFERENCE eine leere GEOGRAPHY zurück.

Einschränkungen

Die zugrunde liegenden geometrischen Objekte, die von einer GoogleSQL-GEOGRAPHY dargestellt werden, entsprechen einer geschlossenen Punktmenge. Daher ist ST_DIFFERENCE die Abschließung der Punktmengendifferenz von geography_1 und geography_2. Dies impliziert, dass bei einer Überschneidung von geography_1 und geography_2 ein Teil der Grenze von geography_2 in der Differenz enthalten sein könnte.

Rückgabetyp

GEOGRAPHY

Beispiel

Die folgende Abfrage veranschaulicht den Unterschied zwischen geog1, einem größeren Polygon POLYGON((0 0, 10 0, 10 10, 0 0)) und geog1, einem kleineren Polygon POLYGON((4 2, 6 2, 8 6, 4 2)), das sich mit geog1 überschneidet. Das Ergebnis ist geog1 mit einem Loch, in dem sich geog2 damit überschneidet.

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)

Beschreibung

Gibt die Dimension des Elements mit der höchsten Dimension in der Eingabe-GEOGRAPHY zurück.

Die einzelnen möglichen Elemente haben folgende Dimensionen:

Die Dimension eines Punkts ist 0.
Die Dimension eines Linienzugs ist 1.
Die Dimension eines Polygons ist 2.

Wenn die Eingabe-GEOGRAPHY leer ist, gibt ST_DIMENSION den Wert -1 zurück.

Rückgabetyp

INT64

`ST_DISJOINT`

ST_DISJOINT(geography_1, geography_2)

Beschreibung

Gibt TRUE zurück, wenn die Schnittmenge von geography_1 und geography_2 leer ist, also kein Punkt sowohl in geography_1 als auch in geography_2 enthalten ist.

ST_DISJOINT ist die logische Negation von ST_INTERSECTS.

Rückgabetyp

BOOL

`ST_DISTANCE`

ST_DISTANCE(geography_1, geography_2[, use_spheroid])

Beschreibung

Gibt die kürzeste Entfernung zwischen zwei nicht leeren GEOGRAPHYs in Metern zurück.

Wenn eine der Eingabe-GEOGRAPHYs leer ist, gibt ST_DISTANCE den Wert NULL zurück.

Der Parameter use_spheroid unterstützt derzeit nur den Wert FALSE. FALSE ist auch der Standardwert von use_spheroid.

Rückgabetyp

FLOAT64

`ST_DUMP`

ST_DUMP(geography[, dimension])

Beschreibung

Gibt ein ARRAY von einfachen GEOGRAPHYs zurück, in denen jedes Element eine Komponente der Eingabe-GEOGRAPHY ist. Eine einfache GEOGRAPHY besteht aus einem einzelnen Punkt, Linienzug oder Polygon. Wenn die Eingabe-GEOGRAPHY einfach ist, ist das Ergebnis ein einzelnes Element. Wenn die Eingabe-GEOGRAPHY eine Sammlung ist, gibt ST_DUMP ein ARRAY mit einer einfachen GEOGRAPHY für jede Komponente in der Sammlung zurück.

Wenn dimension angegeben wird, gibt die Funktion nur GEOGRAPHYs der entsprechenden Dimension zurück. Eine Dimension von -1 entspricht dem Weglassen von dimension.

Rückgabetyp

ARRAY<GEOGRAPHY>

Beispiele

Das folgende Beispiel zeigt, wie ST_DUMP die einfachen Regionen innerhalb einer komplexen Geografie zurückgibt.

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

Das folgende Beispiel zeigt, wie ST_DUMP mit dem Dimensionsargument nur einfache Geografien der angegebenen Dimension zurückgibt.

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

Beschreibung

Gibt TRUE zurück, wenn die Entfernung zwischen mindestens einem Punkt in geography_1 und einem Punkt in geography_2 kleiner oder gleich der Entfernung ist, die vom Argument distance angegeben wird. Andernfalls wird FALSE zurückgegeben. Wenn eine der Eingaben-GEOGRAPHYs leer ist, gibt ST_DWithin den Wert FALSE zurück. Die distance wird in Metern auf der Erdoberfläche angegeben.

Der Parameter use_spheroid unterstützt derzeit nur den Wert FALSE. FALSE ist auch der Standardwert von use_spheroid.

Rückgabetyp

BOOL

`ST_ENDPOINT`

ST_ENDPOINT(linestring_geography)

Beschreibung

Gibt den letzten Punkt einer LineString-Geografie als Punkt-Geografie zurück. Gibt einen Fehler zurück, wenn die Eingabe kein LineString oder leer ist. Verwenden Sie das Präfix SAFE, um NULL für eine ungültige Eingabe anstelle eines Fehlers abzurufen.

Rückgabetyp

Punkt GEOGRAPHY

Beispiel

SELECT ST_ENDPOINT(ST_GEOGFROMTEXT('LINESTRING(1 1, 2 1, 3 2, 3 3)')) last

+--------------+
| last         |
+--------------+
| POINT(3 3)   |
+--------------+

`ST_EQUALS`

ST_EQUALS(geography_1, geography_2)

Beschreibung

Gibt TRUE zurück, wenn geography_1 und geography_2 denselben

Wert GEOGRAPHY darstellen. Konkret bedeutet dies, dass eine der folgenden Bedingungen zutrifft: + ST_COVERS(geography_1, geography_2) = TRUE und ST_COVERS(geography_2, geography_1) = TRUE + geography_1 und geography_2 sind leer.

Daher können zwei GEOGRAPHYs auch dann gleich sein, wenn sich die Reihenfolge der Punkte oder Eckpunkte unterscheidet, solange sie immer noch dieselbe geometrische Struktur darstellen.

Einschränkungen

Es wird nicht garantiert, dass ST_EQUALS eine transitive Funktion ist.

Rückgabetyp

BOOL

`ST_EXTENT`

ST_EXTENT(geography_expression)

Beschreibung

Gibt eine STRUCT zurück, die den Begrenzungsrahmen für den Satz von GEOGRAPHY-Eingabewerten darstellt. Der Begrenzungsrahmen ist das minimale Rechteck, das die Geografie einschließt. Die Kanten des Rechtecks folgen konstanten Längen- und Breitengradlinien.

Vorsichtsmaßnahmen:

Gibt NULL zurück, wenn alle Eingaben NULL oder leere Regionen sind.
Der Begrenzungsrahmen kann den Antimeridian kreuzen, wenn dadurch ein kleineres Rechteck möglich ist. In diesem Fall liegt eine der Längsbegrenzungen des Begrenzungsrahmens außerhalb des Bereichs [-180, 180], sodass xmin kleiner ist als der östlichste Wert xmax.
Wenn die Längengradspanne des Begrenzungsrahmens größer oder gleich 180 Grad ist, gibt die Funktion den Begrenzungsrahmen mit dem Längengradbereich [-180, 180] zurück.

Rückgabetyp

STRUCT<xmin FLOAT64, ymin FLOAT64, xmax FLOAT64, ymax FLOAT64>.

Teile des Begrenzungsrahmens:

xmin: Die westlichste konstante Längengradlinie, die das Rechteck umgrenzt.
xmax: Die östlichste konstante Längengradlinie, die das Rechteck umgrenzt.
ymin: Die minimale konstante Breitengradlinie, die das Rechteck umgrenzt.
ymax: Die maximale konstante Breitengradlinie, die das Rechteck begrenzt.

Beispiel

WITH data AS (
  SELECT 1 id, ST_GEOGFROMTEXT('POLYGON((-125 48, -124 46, -117 46, -117 49, -125 48))') g
  UNION ALL
  SELECT 2 id, ST_GEOGFROMTEXT('POLYGON((172 53, -130 55, -141 70, 172 53))') g
  UNION ALL
  SELECT 3 id, ST_GEOGFROMTEXT('POINT EMPTY') g
)
SELECT ST_EXTENT(g) AS box
FROM data

+----------------------------------------------+
| box                                          |
+----------------------------------------------+
| {xmin:172, ymin:46, xmax:243, ymax:70}       |
+----------------------------------------------+

Unter ST_BOUNDINGBOX finden Sie die Version von ST_EXTENT ohne Aggregation.

`ST_EXTERIORRING`

ST_EXTERIORRING(polygon_geography)

Beschreibung

Gibt eine LineString-Geografie zurück, die dem äußersten Ring einer Polygongeografie entspricht.

Wenn die Eingabegeografie ein Polygon ist, wird der äußerste Ring der Polygongeografie abgerufen und der entsprechende LineString zurückgegeben.
Wenn die Eingabe die vollständige GEOGRAPHY ist, wird eine leere Geografie zurückgegeben.
Gibt einen Fehler zurück, wenn die Eingabe kein einzelnes Polygon ist.

Verwenden Sie das Präfix SAFE, um NULL für eine ungültige Eingabe anstelle eines Fehlers abzurufen.

Rückgabetyp

LineString GEOGRAPHY
GEOGRAPHY ist leer

Beispiele

WITH geo as
 (SELECT ST_GEOGFROMTEXT('POLYGON((0 0, 1 4, 2 2, 0 0))') AS g UNION ALL
  SELECT ST_GEOGFROMTEXT('''POLYGON((1 1, 1 10, 5 10, 5 1, 1 1),
                                  (2 2, 3 4, 2 4, 2 2))''') as g)
SELECT ST_EXTERIORRING(g) AS ring FROM geo;

+---------------------------------------+
| ring                                  |
+---------------------------------------+
| LINESTRING(2 2, 1 4, 0 0, 2 2)        |
| LINESTRING(5 1, 5 10, 1 10, 1 1, 5 1) |
+---------------------------------------+

`ST_GEOGFROM`

ST_GEOGFROM(expression)

Beschreibung

Wandelt einen Ausdruck für einen STRING- oder BYTES-Wert in einen GEOGRAPHY-Wert um.

Wenn expression einen STRING-Wert darstellt, muss es eine gültige GEOGRAPHY-Darstellung in einem der folgenden Formate sein:

WKT-Format. Weitere Informationen zu diesem Format und den Anforderungen für die Verwendung finden Sie unter ST_GEOGFROMTEXT.
WKB im Hexadezimaltextformat. Weitere Informationen zu diesem Format und den Anforderungen für die Verwendung finden Sie unter ST_GEOGFROMWKB.
GeoJSON-Format. Weitere Informationen zu diesem Format und den Anforderungen für die Verwendung finden Sie unter ST_GEOGFROMGEOJSON.

Wenn expression einen BYTES-Wert darstellt, muss es ein gültiger GEOGRAPHY-binärer Ausdruck im WKB-Format sein. Weitere Informationen zu diesem Format und den Anforderungen für die Verwendung finden Sie unter ST_GEOGFROMWKB.

Wenn expression NULL ist, ist die Ausgabe NULL.

Rückgabetyp

GEOGRAPHY

Beispiele

Dieser Typ verwendet einen WKT-formatierten String und gibt ein GEOGRAPHY-Polygon zurück:

SELECT ST_GEOGFROM('POLYGON((0 0, 0 2, 2 2, 2 0, 0 0))') AS WKT_format

+------------------------------------+
| WKT_format                         |
+------------------------------------+
| POLYGON((2 0, 2 2, 0 2, 0 0, 2 0)) |
+------------------------------------+

Dabei wird ein WKB-formatierter hexadezimal codierter String verwendet und ein GEOGRAPHY-Punkt zurückgegeben:

SELECT ST_GEOGFROM(FROM_HEX('010100000000000000000000400000000000001040')) AS WKB_format

+----------------+
| WKB_format     |
+----------------+
| POINT(2 4)     |
+----------------+

Dieser Typ nimmt WKB-formatierte Bytes zurück und gibt einen GEOGRAPHY-Punkt zurück:

SELECT ST_GEOGFROM('010100000000000000000000400000000000001040')-AS WKB_format

+----------------+
| WKB_format     |
+----------------+
| POINT(2 4)     |
+----------------+

Dieser Typ verwendet einen GeoJSON-formatierten String und gibt ein Polygon GEOGRAPHY zurück:

SELECT ST_GEOGFROM(
  '{ "type": "Polygon", "coordinates": [ [ [2, 0], [2, 2], [1, 2], [0, 2], [0, 0], [2, 0] ] ] }'
) AS GEOJSON_format

+-----------------------------------------+
| GEOJSON_format                          |
+-----------------------------------------+
| POLYGON((2 0, 2 2, 1 2, 0 2, 0 0, 2 0)) |
+-----------------------------------------+

`ST_GEOGFROMGEOJSON`

ST_GEOGFROMGEOJSON(geojson_string [, make_valid => constant_expression])

Beschreibung

Gibt einen GEOGRAPHY-Wert zurück, der der Eingabedarstellung im GeoJSON-Format entspricht.

ST_GEOGFROMGEOJSON nimmt Eingaben an, die RFC 7946-konform sind.

Wenn der Parameter make_valid auf TRUE gesetzt ist, versucht die Funktion, Polygone zu reparieren, die nicht der Semantik des Open Geospatial Consortium entsprechen. Dieser Parameter verwendet eine Syntax mit benannten Argumenten und sollte mit der Syntax make_valid => argument_value angegeben werden.

Unter ST_ASGEOJSON erfahren Sie, wie Sie eine GEOGRAPHY als GeoJSON formatieren.

Einschränkungen

Die JSON-Eingabe unterliegt den folgenden Einschränkungen:

ST_GEOGFROMGEOJSON nimmt nur JSON-Geometriefragmente an und kann nicht zur Aufnahme eines ganzen JSON-Dokuments verwendet werden.
Das JSON-Fragment in der Eingabe muss aus einem GeoJSON-Geometrietyp wie Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon oder GeometryCollection bestehen. Jeder andere GeoJSON-Typ wie Feature oder FeatureCollection führt zu einem Fehler.
Eine Position im coordinates-Mitglied eines GeoJSON-Geometrietyps muss aus genau zwei Elementen bestehen. Das erste ist der Längengrad und das zweite der Breitengrad. Daher unterstützt ST_GEOGFROMGEOJSON nicht das optionale dritte Element für eine Position im coordinates-Mitglied.

Rückgabetyp

GEOGRAPHY

Signatur 1

ST_GEOGFROMTEXT(wkt_string[, oriented])

Beschreibung

Gibt einen GEOGRAPHY-Wert zurück, der der Eingabedarstellung im WKT-Format entspricht.

Diese Funktion unterstützt einen optionalen Parameter vom Typ BOOL, oriented. Bei Einstellung dieses Parameters auf TRUE wird davon ausgegangen, dass alle Polygone in der Eingabe nach dem folgenden Muster ausgerichtet sind: Wenn eine Person in der Reihenfolge der Eingabeeckpunkte an der Grenze des Polygons entlanggeht, befindet sich das Innere des Polygons auf der linken Seite. Dadurch können mit WKT Polygone dargestellt werden, die größer als eine Halbkugel sind. Wenn oriented auf FALSE gesetzt oder weggelassen wird, gibt diese Funktion das Polygon mit der kleineren Fläche zurück. Siehe auch ST_MAKEPOLYGONORIENTED, das ST_GEOGFROMTEXT mit oriented=TRUE ähnelt.

Verwenden Sie ST_ASTEXT zum Formatieren von GEOGRAPHY als WKT.

Einschränkungen

Es wird angenommen, dass alle Eingabekanten sphärische geodätische Linien und keine planaren Geraden sind. Wenn Sie Daten in einer planaren Projektion lesen möchten, sollten Sie ST_GEOGFROMGEOJSON verwenden. Weitere Informationen zu den Unterschieden zwischen sphärischen geodätischen Linien und planaren Linien finden Sie unter Koordinatensysteme und Kanten.
Die Funktion unterstützt weder dreidimensionale Geometrien mit einem Suffix Z noch Geometrien linearer Referenzsysteme mit dem Suffix M.
Die Funktion unterstützt nur geometrische Primitive und mehrteilige Geometrien. Insbesondere werden nur Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon und GeometryCollection unterstützt.

Rückgabetyp

GEOGRAPHY

Beispiel

Die folgende Abfrage liest den WKT-String POLYGON((0 0, 0 2, 2 2, 2 0, 0 0)) sowohl als nicht ausgerichtetes Polygon als auch als ausgerichtetes Polygon und prüft, ob jedes Ergebnis den Punkt (1, 1) enthält.

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

Signatur 2

ST_GEOGFROMTEXT(wkt_string[, oriented => boolean_constant_1]
    [, planar => boolean_constant_2] [, make_valid => boolean_constant_3])

Beschreibung

Gibt einen GEOGRAPHY-Wert zurück, der der Eingabedarstellung im WKT-Format entspricht.

Diese Funktion unterstützt drei optionale Parameter vom Typ BOOL: oriented, planar und make_valid. Diese Signatur verwendet benannte Argumentsyntax und die Parameter müssen in beliebiger Reihenfolge mit der parameter_name => parameter_value-Syntax angegeben werden.

Bei Einstellung des Parameters oriented auf TRUE wird davon ausgegangen, dass alle Polygone in der Eingabe nach dem folgenden Muster ausgerichtet sind: Wenn eine Person in der Reihenfolge der Eingabeeckpunkte an der Grenze des Polygons entlanggeht, befindet sich das Innere des Polygons auf der linken Seite. Dadurch können mit WKT Polygone dargestellt werden, die größer als eine Halbkugel sind. Wenn oriented auf FALSE gesetzt oder weggelassen wird, gibt diese Funktion das Polygon mit der kleineren Fläche zurück. Siehe auch ST_MAKEPOLYGONORIENTED, das ST_GEOGFROMTEXT mit oriented=TRUE ähnelt.

Wenn der Parameter planar auf TRUE gesetzt ist, wird davon ausgegangen, dass für die Kanten der Linienstrings und Polygone die Semantik für planare Karten und nicht die standardmäßige sphärische geodätische Semantik von GoogleSQL verwendet wird. Weitere Informationen zu den Unterschieden zwischen sphärischen geodätischen Linien und planaren Linien finden Sie unter Koordinatensysteme und Kanten.

Wenn der Parameter make_valid auf TRUE gesetzt ist, versucht die Funktion, Polygone zu reparieren, die nicht der Semantik des Open Geospatial Consortium entsprechen.

Verwenden Sie ST_ASTEXT zum Formatieren von GEOGRAPHY als WKT.

Einschränkungen

Es wird angenommen, dass alle Eingabekanten standardmäßig sphärische geodätische Linien und keine planaren Geraden sind. Wenn Sie Daten in einer planaren Projektion lesen möchten, sollten Sie das Argument planar => TRUE übergeben oder ST_GEOGFROMGEOJSON verwenden. Weitere Informationen zu den Unterschieden zwischen sphärischen geodätischen Linien und planaren Linien finden Sie unter Koordinatensysteme und Kanten.
Die Funktion unterstützt weder dreidimensionale Geometrien mit einem Suffix Z noch Geometrien linearer Referenzsysteme mit dem Suffix M.
Die Funktion unterstützt nur geometrische Primitive und mehrteilige Geometrien. Insbesondere werden nur Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon und GeometryCollection unterstützt.
oriented und planar können nicht gleichzeitig TRUE sein.
oriented und make_valid können nicht gleichzeitig TRUE sein.

Beispiel

Die folgende Abfrage liest den WKT-String POLYGON((0 0, 0 2, 2 2, 0 2, 0 0)) sowohl als nicht ausgerichtetes Polygon als auch als ausgerichtetes Polygon und prüft, ob jedes Ergebnis den Punkt (1, 1) enthält.

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

Die folgende Abfrage konvertiert einen WKT-String mit einem ungültigen Polygon in GEOGRAPHY. Der WKT-String verstößt gegen zwei Eigenschaften eines gültigen Polygons – die Schleife, die das Polygon beschreibt, ist nicht geschlossen und enthält eine Selbstschneidung. Mit der Option make_valid wird ST_GEOGFROMTEXT in eine Multipolygon-Form umgewandelt.

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)

Beschreibung

Wandelt einen Ausdruck für einen hexadezimalen STRING- oder BYTES-Wert in einen GEOGRAPHY-Wert um. Der Ausdruck muss das WKB-Format haben.

Verwenden Sie ST_ASBINARY zum Formatieren von GEOGRAPHY als WKB.

Einschränkungen

Es wird angenommen, dass alle Eingabekanten sphärische geodätische Linien und keine planaren Geraden sind. Wenn Sie Daten in einer planaren Projektion lesen möchten, sollten Sie ST_GEOGFROMGEOJSON verwenden.

Rückgabetyp

GEOGRAPHY

`ST_GEOGPOINT`

ST_GEOGPOINT(longitude, latitude)

Beschreibung

Erstellt eine GEOGRAPHY mit einem einzelnen Punkt. ST_GEOGPOINT erstellt einen Punkt aus dem angegebenen Parametern FLOAT64-Längengrad (in Grad, negativ: Westlich des Nullmeridians, positiv: Östlich) und Breitengrad (in Grad, positiv: Nördlich des Äquators, negativ: Südlich) und gibt diesen Punkt in einem GEOGRAPHY-Wert zurück.

HINWEIS: Einige Systeme geben zuerst den Breitengrad an. Achten Sie auf die Reihenfolge der Argumente.

Einschränkungen

Längengrade außerhalb des Bereichs [-180, 180] sind zulässig. ST_GEOGPOINT verwendet den Eingabelängengrad-Modulo 360, um einen Längengrad innerhalb von [-180, 180] zu ermitteln.
Breitengrade müssen im Bereich [-90, 90] liegen. Breitengrade außerhalb dieses Bereichs führen zu einem Fehler.

Rückgabetyp

Punkt GEOGRAPHY

`ST_GEOGPOINTFROMGEOHASH`

ST_GEOGPOINTFROMGEOHASH(geohash)

Beschreibung

Gibt einen GEOGRAPHY-Wert zurück, der einem Punkt in der Mitte eines Begrenzungsrahmens entspricht, der im GeoHash definiert ist.

Rückgabetyp

Punkt GEOGRAPHY

`ST_GEOHASH`

ST_GEOHASH(geography_expression[, maxchars])

Beschreibung

Nimmt eine Ein-Punkt-GEOGRAPHY an und gibt eine GeoHash-Darstellung dieses GEOGRAPHY-Objekts zurück.

geography_expression: stellt ein GEOGRAPHY-Objekt dar. Es wird nur ein GEOGRAPHY-Objekt unterstützt, das einen einzelnen Punkt darstellt. Wenn ST_GEOHASH für ein leeres GEOGRAPHY-Objekt verwendet wird, wird NULL zurückgegeben.
maxchars: Der optionale Parameter INT64 gibt die maximale Anzahl der Zeichen an, die der Hash enthalten soll. Weniger Zeichen entsprechen einer geringeren Genauigkeit oder, anders ausgedrückt, einem größeren Begrenzungsrahmen. maxchars ist standardmäßig 20, wenn nicht explizit angegeben. Ein gültiger maxchars-Wert liegt zwischen 1 und 20 (inklusive). Jeder Wert unter oder höher gilt als nicht angegeben und es wird der Standardwert 20 verwendet.

Rückgabetyp

STRING

Beispiel

Gibt einen GeoHash des Seattle Centers mit einer Genauigkeit von zehn Zeichen zurück.

SELECT ST_GEOHASH(ST_GEOGPOINT(-122.35, 47.62), 10) geohash

+--------------+
| geohash      |
+--------------+
| c22yzugqw7   |
+--------------+

`ST_GEOMETRYTYPE`

ST_GEOMETRYTYPE(geography_expression)

Beschreibung

Gibt den OGC-Geometrietyp (Open Geospatial Consortium) zurück, der die Eingabe-GEOGRAPHY als einen STRING beschreibt. Der OGC-Geometrietyp entspricht den Typen, die in den Formaten WKT und GeoJSON verwendet und für ST_ASTEXT und ST_ASGEOJSON gedruckt werden. ST_GEOMETRYTYPE gibt den OGC-Geometrietyp mit dem Präfix "ST_" zurück.

ST_GEOMETRYTYPE gibt Folgendes für den Typ der Eingabe zurück:

Ein-Punkt-Geografie: Gibt ST_Point zurück.
Sammlung von nur Punkten: Gibt ST_MultiPoint zurück.
Geografie mit einem LineString: Gibt ST_LineString zurück.
Sammlung von nur LinienStrings: Gibt ST_MultiLineString zurück.
Geografie mit einem Polygon: Gibt ST_Polygon zurück.
Sammlung von nur Polygonen: Gibt ST_MultiPolygon zurück.
Sammlung mit Elementen verschiedener Dimensionen, oder die Eingabe ist die leere Geografie: Gibt ST_GeometryCollection zurück.

Rückgabetyp

STRING

Beispiel

Das folgende Beispiel zeigt, wie ST_GEOMETRYTYPE Regionen übernimmt und die Namen ihrer OGC-Geometrietypen zurückgibt.

WITH example AS(
  SELECT ST_GEOGFROMTEXT('POINT(0 1)') AS geography
  UNION ALL
  SELECT ST_GEOGFROMTEXT('MULTILINESTRING((2 2, 3 4), (5 6, 7 7))')
  UNION ALL
  SELECT ST_GEOGFROMTEXT('GEOMETRYCOLLECTION(MULTIPOINT(-1 2, 0 12), LINESTRING(-2 4, 0 6))')
  UNION ALL
  SELECT ST_GEOGFROMTEXT('GEOMETRYCOLLECTION EMPTY'))
SELECT
  geography AS WKT,
  ST_GEOMETRYTYPE(geography) AS geometry_type_name
FROM example;

+-------------------------------------------------------------------+-----------------------+
| WKT                                                               | geometry_type_name    |
+-------------------------------------------------------------------+-----------------------+
| POINT(0 1)                                                        | ST_Point              |
| MULTILINESTRING((2 2, 3 4), (5 6, 7 7))                           | ST_MultiLineString    |
| GEOMETRYCOLLECTION(MULTIPOINT(-1 2, 0 12), LINESTRING(-2 4, 0 6)) | ST_GeometryCollection |
| GEOMETRYCOLLECTION EMPTY                                          | ST_GeometryCollection |
+-------------------------------------------------------------------+-----------------------+

`ST_INTERIORRINGS`

ST_INTERIORRINGS(polygon_geography)

Beschreibung

Gibt ein Array von Linienzug-Geografien zurück, das den Innenringen einer Polygongeografie entspricht. Jeder Innenring ist der Rand eines Lochs im Eingabepolygon.

Wenn die Eingabegeographie ein Polygon ist, wird der äußere Ring der Polygongeografie ausgeschlossen und es werden die Linestrings zurückgegeben, die den inneren Ringen entsprechen.
Wenn die Eingabe die vollständige GEOGRAPHY ist, wird ein leeres Array zurückgegeben.
Wenn das Eingabepolygon keine Löcher hat, wird ein leeres Array z