Geografische Funktionen in Standard-SQL

Die geografischen Funktionen werden auf GEOGRAPHY-Werte von BigQuery angewendet oder generieren sie. Die Signatur jeder geografischen Funktion beginnt mit ST_. BigQuery 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 BigQuery 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_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_CENTROID
ST_CENTROID_AGG (Aggregiert)
ST_CLOSESTPOINT
ST_CONVEXHULL
ST_DIFFERENCE
ST_DUMP
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_ISCOLLECTION
ST_ISEMPTY
ST_NUMPOINTS
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_AREA
ST_DISTANCE
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.

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 BigQuery 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 BigQuery 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_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_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 im 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

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

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

GEOGRAPHY

ST_CLUSTERDBSCAN

ST_CLUSTERDBSCAN(geography_column, epsilon, minimum_geographies) OVER (...)

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

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.
  • OVER: Gibt ein Fenster an. Siehe Analysefunktionen. Die Verwendung der OVER-Klausel mit ST_CLUSTERDBSCAN ist mit Folgendem kompatibel:

    • PARTITION BY: Optional
    • ORDER BY: Optional
    • window_frame_clause: Nicht zulässig

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.
  • Mit dem geografischen Objekt EMPTY kann kein Cluster verbunden 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.

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

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

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

BOOL

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

Eine GEOGRAPHY von BigQuery 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 BigQuery 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_ASGEOJSON erfahren Sie, wie Sie eine GEOGRAPHY als GeoJSON formatieren.

Einschränkungen

Die 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

ST_GEOGFROMTEXT

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, 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, 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 BigQuery 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 standardmäßig angenommen, dass alle Eingabekanten sphärische geodätische Linien und keine planaren Geraden sind. Zum Lesen von Daten in einer planaren Projektion, übergeben Sie das Argument planar => TRUE oder verwenden Sie ST_GEOGFROMGEOJSON. 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 Attribute eines gültigen Polygons – die Schleife, die das Polygon beschreibt, ist nicht geschlossen und enthält eine Kreuzung ihrer selbst. 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)

Beschreibung

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

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 den angegebenen FLOAT64-Parametern für den Längengrad und den Breitengrad und gibt ihn in einem GEOGRAPHY-Wert zurück.

Einschränkungen

  • Breitengrade müssen im Bereich [-90, 90] liegen. Breitengrade außerhalb dieses Bereichs führen zu einem Fehler.
  • 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.

Rückgabetyp

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

GEOGRAPHY

ST_GEOHASH

ST_GEOHASH(geography_expression, maxchars)

Beschreibung

Gibt eine GeoHash-Darstellung von geography_expression zurück. Der resultierende GeoHash enthält höchstens maxchars Zeichen. Weniger Zeichen entsprechen einer geringeren Genauigkeit oder, anders ausgedrückt, einem größeren Begrenzungsrahmen.

Die Ausführung von ST_GeoHash für ein leeres GEOGRAPHY-Objekt gibt NULL zurück.

Einschränkungen

  • Es werden nur GEOGRAPHY-Objekte unterstützt, die einzelne Punkte darstellen.
  • Der Maximalwert von maxchars ist 20.

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

Rückgabetyp

STRING

ST_INTERSECTION

ST_INTERSECTION(geography_1, geography_2)

Beschreibung

Gibt eine GEOGRAPHY zurück, die die Schnittmenge der Punktmengen der zwei Eingabe-GEOGRAPHYs darstellt. Somit ist jeder Punkt in der Schnittmenge sowohl in geography_1 als auch in geography_2 enthalten.

Wenn die beiden Eingabe-GEOGRAPHYs disjunkt sind, also keine Punkte sowohl in geometry_1 als auch in geometry_2 enthalten sind, wird eine leere GEOGRAPHY zurückgegeben.

Verwandte Prädikatfunktionen finden Sie unter ST_INTERSECTS und ST_DISJOINT.

Rückgabetyp

GEOGRAPHY

ST_INTERSECTS

ST_INTERSECTS(geography_1, geography_2)

Beschreibung

Gibt TRUE zurück, wenn die Schnittmenge der Punktmengen von geography_1 und geography_2 nicht leer ist. Diese Funktion gibt also TRUE zurück, wenn es mindestens einen Punkt gibt, der in beiden Eingabe-GEOGRAPHYs enthalten ist.

Wenn ST_INTERSECTS den Wert TRUE zurückgibt, impliziert dies, dass ST_DISJOINT den Wert FALSE zurückgibt.

Rückgabetyp

BOOL

ST_INTERSECTSBOX

ST_INTERSECTSBOX(geography, lng1, lat1, lng2, lat2)

Beschreibung

Gibt TRUE zurück, wenn sich geography mit dem Rechteck zwischen [lng1, lng2] und [lat1, lat2] schneidet. Die Kanten des Rechtecks folgen konstanten Längen- und Breitengradlinien. lng1 und lng2 geben die minimalen und maximalen Längengradlinien an, die das Rechteck begrenzen, und lat1 und lat2 die konstanten minimalen und maximalen Breitengradlinien, die ebenfalls das Rechteck begrenzen.

Geben Sie alle Längen- und Breitengradargumente in Grad an.

Einschränkungen

Die Eingabeargumente unterliegen den folgenden Einschränkungen:

  • Breitengrade müssen im Gradbereich [-90, 90] liegen.
  • Längengrade müssen im Gradbereich [-180, 180] liegen.

Rückgabetyp

BOOL

ST_ISCOLLECTION

ST_ISCOLLECTION(geography_expression)

Beschreibung

Gibt TRUE zurück, wenn die Gesamtzahl der Punkte, Linienzüge und Polygone größer als eins ist.

Eine leere GEOGRAPHY ist keine Sammlung.

Rückgabetyp

BOOL

ST_ISEMPTY

ST_ISEMPTY(geography_expression)

Beschreibung

Gibt TRUE zurück, wenn die angegebene GEOGRAPHY leer ist. Dies bedeutet, dass die GEOGRAPHY keine Punkte, Linien oder Polygone enthält.

HINWEIS: Eine leere BigQuery-GEOGRAPHY steht mit keiner besonderen geometrischen Form in Verbindung. Beispielsweise sind die Ergebnisse der Ausdrücke ST_GEOGFROMTEXT('POINT EMPTY') und ST_GEOGFROMTEXT('GEOMETRYCOLLECTION EMPTY') identisch.

Rückgabetyp

BOOL

ST_LENGTH

ST_LENGTH(geography_expression[, use_spheroid])

Beschreibung

Gibt die Gesamtlänge der Linien in der Eingabe-GEOGRAPHY in Metern zurück.

Wenn geography_expression ein Punkt oder ein Polygon ist, wird null zurückgegeben. Ist geography_expression eine Sammlung, wird die Länge der Linien in der Sammlung zurückgegeben. Enthält die Sammlung keine Linien, 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_MAKELINE

ST_MAKELINE(geography_1, geography_2)
ST_MAKELINE(array_of_geography)

Beschreibung

Erstellt eine GEOGRAPHY mit einem einzelnen Linienzug (LineString-Objekt), indem die Punkte oder Linieneckpunkte von jeder Eingabe-GEOGRAPHY in der Reihenfolge verkettet werden, in der sie angegeben sind.

Es gibt zwei Varianten von ST_MAKELINE. Bei der ersten Variante muss die Eingabe aus zwei GEOGRAPHYs bestehen. Bei der zweiten muss die Eingabe ein ARRAY vom Typ GEOGRAPHY sein. In beiden Varianten muss jede Eingabe-GEOGRAPHY aus einem der folgenden Werte bestehen:

  • Genau einem Punkt
  • Genau einem Linienzug

Bei der ersten Variante von ST_MAKELINE gibt ST_MAKELINE den Wert NULL zurück, wenn eine der GEOGRAPHY-Eingaben gleich NULL ist. Wenn bei der zweiten Variante das Eingabe-ARRAY oder eines der Elemente im Eingabe-ARRAY gleich NULL ist, gibt ST_MAKELINE den Wert NULL zurück.

Einschränkungen

Winkel an Kanten müssen grundsätzlich weniger als 180 Grad betragen.

HINWEIS: Der Ausrichtungsprozess von BigQuery kann hinreichend kurze Kanten verwerfen und die zwei Endpunkte übereinander ausrichten. Wenn beispielsweise zwei Eingabe-GEOGRAPHYs jeweils einen Punkt enthalten und die Entfernung zwischen den zwei Punkten kleiner als der Ausrichtungsradius ist, fallen die Punkte aufeinander. In diesem Fall ist das Ergebnis eine GEOGRAPHY mit genau einem Punkt.

Rückgabetyp

GEOGRAPHY

ST_MAKEPOLYGON

ST_MAKEPOLYGON(geography_expression[, array_of_geography])

Beschreibung

Erstellt eine GEOGRAPHY mit einem einzelnen Polygon aus Linienzugeingaben, wobei jeder eingegebene Linienzug zum Erstellen eines Polygonrings verwendet wird.

Es gibt zwei Varianten von ST_MAKEPOLYGON. Bei der ersten Variante wird der Eingabelinienzug durch eine einzelne GEOGRAPHY angegeben, die genau einen Linienzug enthält. Bei der zweiten Variante besteht die Eingabe aus einer einzelnen GEOGRAPHY und einem Array von GEOGRAPHYs, die jeweils einen Linienzug enthalten. Die erste GEOGRAPHY jeder Variante wird zum Erstellen der Polygonhülle verwendet. Weitere GEOGRAPHYs im Eingabe-ARRAY geben ein Polygonloch an. Für jede Eingabe-GEOGRAPHY mit genau einem Linienzug muss Folgendes gegeben sein:

  • Der Linienzug muss aus mindestens drei verschiedenen Eckpunkten bestehen.
  • Der Linienzug muss geschlossen sein. Das heißt, die ersten und letzten Eckpunkte müssen identisch sein. Wenn sich der erste und letzte Eckpunkt unterscheiden, erstellt die Funktion eine Abschlusskante vom ersten Eckpunkt zum letzten.

Bei der ersten Variante von ST_MAKEPOLYGON gibt ST_MAKEPOLYGON den Wert NULL zurück, wenn eine der GEOGRAPHY-Eingaben gleich NULL ist. Wenn bei der zweiten Variante das Eingabe-ARRAY oder eines der Elemente im Eingabe-ARRAY gleich NULL ist, gibt ST_MAKEPOLYGON den Wert NULL zurück.

HINWEIS: ST_MAKEPOLYGON nimmt eine leere GEOGRAPHY als Eingabe an. ST_MAKEPOLYGON interpretiert eine leere GEOGRAPHY als Geografie mit leerem Linienzug. Damit wird eine vollständige Schleife erstellt, also ein Polygon, das die gesamte Erde abdeckt.

Einschränkungen

Die Eingaberinge müssen zusammen ein gültiges Polygon bilden:

  • Die Polygonhülle muss jedes Polygonloch abdecken.
  • Es darf nur eine Polygonhülle geben, die der erste Eingabering sein muss. Dies impliziert, dass Polygonlöcher nicht verschachtelt sein können.
  • Polygonringe dürfen sich nur in einem Eckpunkt auf der Grenze von beiden Ringen schneiden.

Winkel an Kanten müssen grundsätzlich weniger als 180 Grad betragen.

Jeder Polygonring unterteilt die Kugel in zwei Regionen. Der erste Eingabelinienzug für ST_MAKEPOLYGON bildet die Polygonhülle und für das Innere wird die kleinere der zwei Regionen ausgewählt. Jeder nachfolgende Eingabelinienzug gibt ein Polygonloch an, sodass das Innere des Polygons bereits klar definiert ist. Wenn Sie eine Polygonhülle so definieren möchten, dass das Innere des Polygons die größere der zwei Regionen ist, lesen Sie die Informationen unter ST_MAKEPOLYGONORIENTED.

HINWEIS: Der Ausrichtungsprozess von BigQuery kann hinreichend kurze Kanten verwerfen und die zwei Endpunkte übereinander ausrichten. Wenn Eckpunkte auf diese Weise aufeinanderfallen, ist es damit möglich, dass ein hinreichend kleines Polygonloch verschwindet oder die Ausgabe-GEOGRAPHY nur eine Linie oder einen Punkt enthält.

Rückgabetyp

GEOGRAPHY

ST_MAKEPOLYGONORIENTED

ST_MAKEPOLYGONORIENTED(array_of_geography)

Beschreibung

Wie ST_MAKEPOLYGON, allerdings bestimmt die Reihenfolge der Eckpunkte eines jeden Eingabelinienzugs die Ausrichtung der einzelnen Polygonringe. Durch die Ausrichtung eines Polygonrings wird das Innere des Polygons so definiert: Wenn eine Person in der Reihenfolge der Eingabeeckpunkte an der Grenze des Polygons entlanggeht, befindet sich das Innere des Polygons auf der linken Seite. Dies gilt für jeden angegebenen Polygonring.

Diese Variante des Polygonkonstruktors ist flexibler, da sich durch ST_MAKEPOLYGONORIENTED ein Polygon so erstellen lässt, dass das Innere auf beiden Seiten des Polygonrings liegen kann. Die richtige Ausrichtung von Polygonringen spielt jedoch eine entscheidende Rolle, um das gewünschte Polygon zu erstellen.

Wenn das Eingabe-ARRAY oder eines der Elemente im ARRAY gleich NULL ist, gibt ST_MAKEPOLYGONORIENTED den Wert NULL zurück.

HINWEIS: Das Eingabeargument für ST_MAKEPOLYGONORIENTED kann eine leere GEOGRAPHY enthalten. ST_MAKEPOLYGONORIENTED interpretiert eine leere GEOGRAPHY als Geografie mit einem leeren Linienzug. Damit wird eine vollständige Schleife erstellt, also ein Polygon, das die gesamte Erde abdeckt.

Einschränkungen

Die Eingaberinge müssen zusammen ein gültiges Polygon bilden:

  • Die Polygonhülle muss jedes Polygonloch abdecken.
  • Es darf nur eine Polygonhülle geben, die der erste Eingabering sein muss. Dies impliziert, dass Polygonlöcher nicht verschachtelt sein können.
  • Polygonringe dürfen sich nur in einem Eckpunkt auf der Grenze von beiden Ringen schneiden.

Winkel an Kanten müssen grundsätzlich weniger als 180 Grad betragen.

ST_MAKEPOLYGONORIENTED zieht die Reihenfolge der Eingabeeckpunkte eines jeden Linienzugs heran, um die Ausrichtung des Polygons zu bestimmen. Dies gilt für die Polygonhülle und alle Polygonlöcher. ST_MAKEPOLYGONORIENTED erwartet, dass alle Polygonlöcher die entgegengesetzte Ausrichtung der Hülle haben. Unter ST_MAKEPOLYGON finden Sie einen alternativen Polygonkonstruktor und weitere Einschränkungen zum Erstellen eines gültigen Polygons.

HINWEIS: Aufgrund des Ausrichtungsprozesses von BigQuery werden hinreichend kurze Kanten verworfen und die zwei Endpunkte auf einen einzelnen Punkt ausgerichtet. Daher können Eckpunkte in einem Linienzug aufeinanderfallen, sodass eine oder mehrere Kanten verschwinden. Es ist also möglich, dass ein hinreichend kleines Polygonloch verschwindet oder die resultierende GEOGRAPHY nur eine Linie oder einen Punkt enthält.

Rückgabetyp

GEOGRAPHY

ST_MAXDISTANCE

ST_MAXDISTANCE(geography_1, geography_2[, use_spheroid])

Gibt die längste Entfernung zwischen zwei nicht leeren GEOGRAPHYs in Metern zurück, also die Entfernung zwischen zwei Eckpunkten, wobei der erste Eckpunkt in der ersten GEOGRAPHY liegt und der zweite Eckpunkt in der zweiten GEOGRAPHY. Wenn geography_1 und geography_2 dieselbe GEOGRAPHY sind, gibt die Funktion die Entfernung zwischen den Eckpunkten zurück, die in dieser GEOGRAPHY am weitesten voneinander entfernt sind.

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

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_NUMPOINTS

ST_NUMPOINTS(geography_expression)

Beschreibung

Gibt die Anzahl der Eckpunkte in der Eingabe-GEOGRAPHY zurück. Dies umfasst die Anzahl der Punkte, die Anzahl der Eckpunkte von Linienzügen und die Anzahl der Eckpunkte von Polygonen.

HINWEIS: Der erste und der letzte Eckpunkt eines Polygonrings werden als eigene Eckpunkte gezählt.

Rückgabetyp

INT64

ST_PERIMETER

ST_PERIMETER(geography_expression[, use_spheroid])

Beschreibung

Gibt die Länge der Grenze der Polygone in der Eingabe-GEOGRAPHY in Metern zurück.

Wenn geography_expression ein Punkt oder eine Linie ist, wird null zurückgegeben. Ist geography_expression eine Sammlung, wird der Umfang 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_SIMPLIFY

ST_SIMPLIFY(geography, tolerance_meters)

Beschreibung

Gibt eine vereinfachte Version von geography, der gegebenen Eingabe GEOGRAPHY, zurück. Die Eingabe-GEOGRAPHY wird vereinfacht, indem nahezu gerade Verkettungen kurzer Kanten durch eine einzelne lange Seite ersetzt werden. Die Eingabe-geography ändert sich nicht um mehr als die von tolerance_meters angegebene Toleranz. Dies gewährleistet, dass vereinfachte Kanten innerhalb von tolerance_meters von den ursprünglichen Positionen aller Eckpunkte verlaufen, die von dieser Kante entfernt wurden. Der tolerance_meters-Wert wird in Metern auf der Erdoberfläche angegeben.

Beachten Sie, dass mit ST_SIMPLIFY topologische Beziehungen beibehalten werden. Es werden also keine neuen kreuzenden Kanten erstellt und die Ausgabe ist gültig. Bei einer ausreichend großen Toleranz können angrenzende Formen zu einem einzelnen Objekt minimiert werden oder eine Form kann zu einer Form mit einer niedrigeren Dimension vereinfacht werden.

Einschränkungen

Damit ST_SIMPLIFY wirksam wird, darf tolerance_meters nicht null sein.

ST_SIMPLIFY gibt einen Fehler zurück, wenn die von tolerance_meters angegebene Toleranz

  • negativ ist oder
  • mehr als rund 7.800 Kilometer beträgt.

Rückgabetyp

GEOGRAPHY

Beispiele

Das folgende Beispiel zeigt, wie ST_SIMPLIFY die Eingabelinien-GEOGRAPHY durch Entfernen von Zwischeneckpunkten vereinfacht wird.

WITH example AS
 (SELECT ST_GEOGFROMTEXT('LINESTRING(0 0, 0.05 0, 0.1 0, 0.15 0, 2 0)') AS line)
SELECT
   line AS original_line,
   ST_SIMPLIFY(line, 1) AS simplified_line
FROM example;

+---------------------------------------------+----------------------+
|                original_line                |   simplified_line    |
+---------------------------------------------+----------------------+
| LINESTRING(0 0, 0.05 0, 0.1 0, 0.15 0, 2 0) | LINESTRING(0 0, 2 0) |
+---------------------------------------------+----------------------+

Das folgende Beispiel zeigt, wie das Ergebnis von ST_SIMPLIFY eine niedrigere Dimension als die ursprüngliche Form haben kann.

WITH example AS
 (SELECT
    ST_GEOGFROMTEXT('POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0))') AS polygon,
    t AS tolerance
  FROM UNNEST([1000, 10000, 100000]) AS t)
SELECT
  polygon AS original_triangle,
  tolerance AS tolerance_meters,
  ST_SIMPLIFY(polygon, tolerance) AS simplified_result
FROM example

+-------------------------------------+------------------+-------------------------------------+
|          original_triangle          | tolerance_meters |          simplified_result          |
+-------------------------------------+------------------+-------------------------------------+
| POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |             1000 | POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |
| POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |            10000 |            LINESTRING(0 0, 0.1 0.1) |
| POLYGON((0 0, 0.1 0, 0.1 0.1, 0 0)) |           100000 |                          POINT(0 0) |
+-------------------------------------+------------------+-------------------------------------+

ST_SNAPTOGRID

ST_SNAPTOGRID(geography_expression, grid_size)

Beschreibung

Gibt die Eingabe-GEOGRAPHY zurück, wobei jeder Eckpunkt an einem Längengrad/Breitengrad-Gitternetz ausgerichtet wurde. Die Größe des Gitternetzes wird durch den Parameter grid_size bestimmt, der in Grad angegeben wird.

Einschränkungen

Beliebige Gitternetzgrößen werden nicht unterstützt. Der Parameter grid_size wird gerundet, sodass er die Form \(10^n\) hat, wobei \(-10 < n < 0\) ist.

Rückgabetyp

GEOGRAPHY

ST_TOUCHES

ST_TOUCHES(geography_1, geography_2)

Beschreibung

Gibt TRUE zurück, sofern die beiden folgenden Bedingungen erfüllt sind:

  1. geography_1 schneidet sich mit geography_2.
  2. Das Innere von geography_1 und das Innere von geography_2 sind disjunkt.

Rückgabetyp

BOOL

ST_UNION

ST_UNION(geography_1, geography_2)
ST_UNION(array_of_geography)

Beschreibung

Gibt eine GEOGRAPHY zurück, die die Punktmengenvereinigung aller Eingabe-GEOGRAPHYs darstellt.

Es gibt zwei Varianten von ST_UNION. Für die erste Variante muss die Eingabe aus zwei GEOGRAPHYs bestehen. Bei der zweiten Variante handelt es sich um ein ARRAY vom Typ GEOGRAPHY.

Für die erste Variante von ST_UNION gibt ST_UNION den Wert NULL zurück, wenn eine der Eingabe-GEOGRAPHYs NULL ist. Wenn für die zweite Variante der Wert des Eingabe-ARRAYs gleich NULL ist, gibt ST_UNION den Wert NULL zurück. Bei einem Eingabe-ARRAY, dessen Wert nicht gleich NULL ist, wird die Vereinigung berechnet. NULL-Elemente werden dabei ignoriert, um eine Beeinträchtigung der Ausgabe zu vermeiden.

Die Aggregatversion von ST_UNION finden Sie unter ST_UNION_AGG.

Rückgabetyp

GEOGRAPHY

ST_UNION_AGG

ST_UNION_AGG(geography)

Beschreibung

Gibt eine GEOGRAPHY zurück, die die Punktmengenvereinigung aller Eingabe-GEOGRAPHYs darstellt.

ST_UNION_AGG ignoriert Eingabe-GEOGRAPHYs mit NULL-Werten.

Unter ST_UNION finden Sie die Version von ST_UNION_AGG ohne Aggregation.

Rückgabetyp

GEOGRAPHY

ST_WITHIN

ST_WITHIN(geography_1, geography_2)

Beschreibung

Gibt TRUE zurück, wenn kein Punkt von geography_1 außerhalb von geography_2 liegt und sich das Innere von geography_1 und das Innere von geography_2 schneiden.

Bei zwei Geografien a und b gibt ST_WITHIN(a, b) dasselbe Ergebnis wie ST_CONTAINS(b, a) zurück. Beachten Sie die umgekehrte Reihenfolge der Argumente.

Rückgabetyp

BOOL

ST_X

ST_X(geography_expression)

Beschreibung

Gibt den Längengrad der eingegebenen Einzelpunkt-GEOGRAPHY in Grad zurück.

Für jede Eingabe-GEOGRAPHY, die kein einzelner Punkt ist (einschließlich einer leeren GEOGRAPHY), gibt ST_X einen Fehler zurück. Verwenden Sie das Präfix SAFE., um NULL zu erhalten.

Rückgabetyp

FLOAT64

Beispiel

Im folgenden Beispiel werden ST_X und ST_Y zum Extrahieren von Koordinaten aus Einzelpunkt-Geografien verwendet.

WITH points AS
   (SELECT ST_GEOGPOINT(i, i + 1) AS p FROM UNNEST([0, 5, 12]) AS i)
 SELECT
   p,
   ST_X(p) as longitude,
   ST_Y(p) as latitude
FROM points;

+--------------+-----------+----------+
| p            | longitude | latitude |
+--------------+-----------+----------+
| POINT(0 1)   | 0.0       | 1.0      |
| POINT(5 6)   | 5.0       | 6.0      |
| POINT(12 13) | 12.0      | 13.0     |
+--------------+-----------+----------+

ST_Y

ST_Y(geography_expression)

Beschreibung

Gibt den Breitengrad der eingegebenen Einzelpunkt-GEOGRAPHY in Grad zurück.

Für jede Eingabe-GEOGRAPHY, die kein einzelner Punkt ist (einschließlich einer leeren GEOGRAPHY), gibt ST_Y einen Fehler zurück. Verwenden Sie das Präfix SAFE., um stattdessen NULL zurückzugeben.

Rückgabetyp

FLOAT64

Beispiel

Unter ST_X finden Sie ein Anwendungsbeispiel.