Mit Rasterdaten in BigQuery mit Earth Engine arbeiten

In diesem Dokument wird erläutert, wie Sie Raster- und Vektordaten mit der ST_REGIONSTATS Funktion kombinieren. Diese Funktion verwendet Google Earth Engine, um auf Bild- und Rasterdaten in BigQuery zuzugreifen.

Übersicht

Ein Raster ist ein zweidimensionales Pixelraster, wobei jedem Pixel ein oder mehrere Werte zugewiesen sind, die als Bänder bezeichnet werden. Jedes Pixel kann beispielsweise einem bestimmten Quadratkilometer auf der Erdoberfläche entsprechen und Bänder für die Durchschnittstemperatur und den durchschnittlichen Niederschlag haben. Zu den Rasterdaten gehören Satellitenbilder und andere kontinuierliche, rasterbasierte Daten wie Wettervorhersagen und Landbedeckung. Viele gängige Bildformate wie PNG- oder JPEG-Dateien sind als Rasterdaten formatiert.

Rasterdaten werden oft Vektordaten gegenübergestellt, bei denen die Daten durch Linien oder Kurven und nicht durch ein festes rechteckiges Raster beschrieben werden. Sie können beispielsweise den Datentyp GEOGRAPHY in BigQuery verwenden, um die Grenzen von Ländern, Städten oder anderen Regionen zu beschreiben.

Geospatiale Raster- und Vektordaten werden oft mit einer Zonenstatistik kombiniert, bei der ein Aggregat aller Rasterwerte innerhalb einer bestimmten Vektorregion berechnet wird. Beispiele:

• Durchschnittliche Luftqualität in einer Reihe von Städten.
• Solarpotenzial für eine Reihe von Gebäudepolygonen.
• Zusammenfassung des Brandrisikos entlang von Stromleitungskorridoren in Waldgebieten.

BigQuery eignet sich hervorragend für die Verarbeitung von Vektordaten und Google Earth Engine für die Verarbeitung von Rasterdaten. Mit der ST_REGIONSTATS geografischen Funktion können Sie Rasterdaten mit Earth Engine mit Ihren in BigQuery gespeicherten Vektordaten kombinieren.

Hinweis

1. Wenn Sie die Funktion ST_REGIONSTATS in Ihren Abfragen verwenden möchten, aktivieren Sie die Earth Engine API.

   API aktivieren

2. Optional: Wenn Sie Daten abonnieren und verwenden möchten, die in BigQuery sharing (früher Analytics Hub) veröffentlicht wurden, indem Sie die ST_REGIONSTATS Funktion verwenden, aktivieren Sie die Analytics Hub API.

   API aktivieren

Erforderliche Berechtigungen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, damit Sie die nötigen Berechtigungen zum Aufrufen der Funktion ST_REGIONSTATS haben:

• Earth Engine Resource Viewer (roles/earthengine.viewer)
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
• Datasets in BigQuery sharing abonnieren: BigQuery-Datenbearbeiter (roles/bigquery.dataEditor)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Aufrufen der ST_REGIONSTATS Funktion erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um die Funktion ST_REGIONSTATS aufzurufen:

• earthengine.computations.create
• serviceusage.services.use
• bigquery.datasets.create

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Rasterdaten suchen

Der Parameter raster_id in der Funktion ST_REGIONSTATS ist ein String, der die Quelle Ihrer Rasterdaten angibt. In den folgenden Abschnitten wird erläutert, wie Sie die Raster-ID finden und formatieren.

BigQuery-Bildtabellen

Mit BigQuery sharing (früher Analytics Hub) können Sie Raster-Datasets in BigQuery finden und darauf zugreifen. Wenn Sie BigQuery sharing verwenden möchten, müssen Sie die Analytics Hub API aktivieren und die erforderlichen Berechtigungen zum Ansehen und Abonnieren von Einträgen und Datenaustauschen haben.

Google Earth Engine veröffentlicht öffentlich verfügbare Datasets mit Rasterdaten in den Multiregionen US und EU. So abonnieren Sie ein Earth Engine-Dataset mit Rasterdaten:

1. Rufen Sie die Seite Sharing (Analytics Hub) auf.

   Sharing (Analytics Hub) aufrufen

2. Klicken Sie auf das Lupensymbol Einträge suchen.

3. Geben Sie im Feld Nach Einträgen suchen "Google Earth Engine" ein.

4. Klicken Sie auf ein Dataset, das Sie abonnieren möchten.

5. Klicken Sie auf Abonnieren.

6. Optional: Aktualisieren Sie die Felder Projekt oder Name des verknüpften Datasets.

7. Klicken Sie auf Speichern. Das verknüpfte Dataset wird Ihrem Projekt hinzugefügt.

Das Dataset enthält eine Bildtabelle , in der Metadaten für eine Sammlung von Rasterbildern gemäß der STAC-Items-Spezifikation gespeichert sind. Eine Bildtabelle ist analog zu einer Earth Engine-Bildsammlung (ImageCollection).

Jede Zeile in der Tabelle entspricht einem einzelnen Rasterbild. Die Spalten enthalten Bildattribute und Metadaten. Die Raster-ID für jedes Bild wird in der Spalte assets.image.href gespeichert. Verweisen Sie in Ihren Abfragen mit dieser ID als Wert des Parameters raster_id auf Bilder.

Filtern Sie die Tabelle nach Attributspalten, um bestimmte Bilder oder Bilduntergruppen auszuwählen, die Ihren Kriterien entsprechen. Weitere Informationen zu verfügbaren Bändern, Pixelgröße und Attributdefinitionen finden Sie in der Tabelle auf dem Tab Bilddetails.

Jede Bildtabelle enthält eine entsprechende *_metadata-Tabelle, die zusätzliche Informationen für die Bildtabelle enthält.

Das ERA5-Land-Dataset enthält beispielsweise Statistiken zu täglichen Klimavariablen und ist öffentlich verfügbar. Die Tabelle climate enthält mehrere Raster-IDs. Die folgende Abfrage filtert die Bildtabelle mit der Spalte start_datetime, um die Raster-ID für das Bild vom 1. Januar 2025 abzurufen, und berechnet die Durchschnittstemperatur für jedes Land mit dem Band temperature_2m:

SQL

WITH SimplifiedCountries AS (
  SELECT
    ST_SIMPLIFY(geometry, 10000) AS simplified_geometry,
    names.primary AS name
  FROM
    `bigquery-public-data.overture_maps.division_area`
  WHERE
    subtype = 'country'
)
SELECT
  sc.simplified_geometry AS geometry,
  sc.name,
  ST_REGIONSTATS(
    sc.simplified_geometry,
    (SELECT assets.image.href
    FROM `LINKED_DATASET_NAME.climate`
    WHERE start_datetime = '2025-01-01 00:00:00'),
    'temperature_2m'
  ).mean - 273.15 AS mean_temperature
FROM
  SimplifiedCountries AS sc
ORDER BY
  mean_temperature DESC;

BigQuery DataFrames

Bevor Sie dieses Beispiel ausprobieren, folgen Sie den Schritten zur Einrichtung von BigQuery DataFrames in der BigQuery-Kurzanleitung: BigQuery DataFrames verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu BigQuery DataFrames.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Set up ADC für eine lokale Entwicklungsumgebung einrichten.

import datetime
from typing import cast

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# TODO: Set the project_id to your Google Cloud project ID.
# project_id = "your-project-id"
bpd.options.bigquery.project = project_id

# TODO: Set the dataset_id to the ID of the dataset that contains the
# `climate` table. This is likely a linked dataset to Earth Engine.
# See: https://cloud.google.com/bigquery/docs/link-earth-engine
linked_dataset = "era5_land_daily_aggregated"

# For the best efficiency, use partial ordering mode.
bpd.options.bigquery.ordering_mode = "partial"

# Load the table of country boundaries.
countries = bpd.read_gbq("bigquery-public-data.overture_maps.division_area")

# Filter to just the countries.
countries = countries[countries["subtype"] == "country"].copy()
countries["name"] = countries["names"].struct.field("primary")
countries["simplified_geometry"] = bbq.st_simplify(
    countries["geometry"],
    tolerance_meters=10_000,
)

# Get the reference to the temperature data from a linked dataset.
# Note: This sample assumes you have a linked dataset to Earth Engine.
image_href = (
    bpd.read_gbq(f"{project_id}.{linked_dataset}.climate")
    .set_index("start_datetime")
    .loc[[datetime.datetime(2025, 1, 1, tzinfo=datetime.timezone.utc)], :]
)
raster_id = image_href["assets"].struct.field("image").struct.field("href")
raster_id = raster_id.item()
stats = bbq.st_regionstats(
    countries["simplified_geometry"],
    raster_id=cast(str, raster_id),
    band="temperature_2m",
)

# Extract the mean and convert from Kelvin to Celsius.
countries["mean_temperature"] = stats.struct.field("mean") - 273.15

# Sort by the mean temperature to find the warmest countries.
result = countries[["name", "mean_temperature"]].sort_values(
    "mean_temperature", ascending=False
)
print(result.head(10))

Cloud Storage GeoTIFF

GeoTIFF ist ein gängiges Dateiformat zum Speichern von geospatialen Rasterdaten. Die ST_REGIONSTATS Funktion unterstützt Rasterdaten, die im Cloud Optimized GeoTIFF -Format (COG) in Cloud Storage-Buckets in den folgenden Regionen gespeichert sind:

• Multiregion US
• us-central1
• Multiregion EU
• europe-west1

Geben Sie den Cloud Storage-URI als Raster-ID an, z. B. gs://bucket/folder/raster.tif.

Earth Engine-Bild-Assets

Die Funktion ST_REGIONSTATS unterstützt die Übergabe eines Earth Engine-Bild-Asset-Pfads für das Argument raster_id. Earth Engine-Rasterdaten sind als einzelne Bilder oder Bildsammlungen verfügbar. Diese Daten befinden sich in der Region US und sind nur mit Abfragen kompatibel, die in der Region US ausgeführt werden. So finden Sie die Raster-ID für ein Bild:

1. Suchen Sie im Earth Engine-Datenkatalog nach dem gewünschten Dataset.

2. Klicken Sie auf den Namen des Datasets, um die Beschreibungsseite für diesen Eintrag zu öffnen. Das Earth Engine-Snippet beschreibt entweder ein einzelnes Bild oder eine Sammlung von Bildern.

   Wenn das Earth Engine-Snippet die Form hat ee.Image('IMAGE_PATH'), ist die Raster-ID 'ee://IMAGE_PATH'.

   Wenn das Earth Engine-Snippet die Form ee.ImageCollection('IMAGE_COLLECTION_PATH') hat, können Sie den Earth Engine Code Editor verwenden, um die ImageCollection nach einem einzelnen Bild zu filtern. Verwenden Sie die ee.Image.get('system:id') Methode, um den IMAGE_PATH Wert für dieses Bild in der Konsole auszugeben. Die Raster-ID ist 'ee://IMAGE_PATH'.

Pixelgewichtungen

Sie können für den include Parameter in der ST_REGIONSTATS Funktion, die bestimmt, wie stark jedes Pixel bei Berechnungen gewichtet wird, eine Gewichtung angeben, die manchmal auch als Maskenwert bezeichnet wird. Die Gewichtungswerte müssen zwischen 0 und 1 liegen. Gewichtungen außerhalb dieses Bereichs werden auf den nächstgelegenen Grenzwert (0 oder 1) festgelegt.

Ein Pixel gilt als gültig , wenn es eine Gewichtung von mehr als 0 hat. Eine Gewichtung von 0 gibt ein ungültiges Pixel an. Ungültige Pixel stehen in der Regel für fehlende oder unzuverlässige Daten, z. B. Bereiche, die von Wolken verdeckt sind, Sensoranomalien, Verarbeitungsfehler oder Standorte außerhalb einer definierten Grenze.

Wenn Sie keine Gewichtung angeben, wird jedes Pixel automatisch nach dem Anteil des Pixels gewichtet, der sich innerhalb der Geometrie befindet. So können sie proportional in die Zonenstatistik einbezogen werden. Wenn die Geometrie weniger als 1/256 der Größe des Pixels beträgt, ist die Gewichtung des Pixels 0. In diesen Fällen wird für alle Statistiken null zurückgegeben, mit Ausnahme von count und area, die 0 sind.

Wenn ein teilweise überlappendes Pixel eine Gewichtung aus dem Argument include für ST_REGIONSTATS hat, verwendet BigQuery das Minimum aus dieser Gewichtung und dem Anteil des Pixels, der die Region schneidet.

Gewichtungswerte haben nicht dieselbe Genauigkeit wie FLOAT64-Werte. In der Praxis kann ihr tatsächlicher Wert um bis zu 1/256 (ca.0,4%) vom Wert abweichen, der in Berechnungen verwendet wird.

Sie können im Argument include einen Ausdruck mit der Earth Engine Bildausdruckssyntax angeben, um Pixel basierend auf bestimmten Kriterien in Rasterbändern dynamisch zu gewichten. Der folgende Ausdruck beschränkt Berechnungen beispielsweise auf Pixel, bei denen das Band probability 70 % übersteigt:

include => 'probability > 0.7'

Wenn das Dataset ein Band mit einem Gewichtungsfaktor enthält, können Sie es mit der folgenden Syntax verwenden:

include => 'weight_factor_band_name'

Pixelgröße und Analyseskala

Ein geospatiales Rasterbild ist ein Pixelraster, das einer bestimmten Position auf der Erdoberfläche entspricht. Die Pixelgröße eines Rasters, manchmal auch als Skala bezeichnet, ist die nominale Größe einer Kante eines Pixels im Koordinaten referenzsystem des Rasters. Ein Raster mit einer Auflösung von 10 Metern hat beispielsweise Pixel mit einer Größe von 10 × 10 Metern. Die ursprünglich angegebene Pixelgröße kann zwischen Datasets erheblich variieren, von weniger als 1 Meter bis mehr als 20 Kilometer.

Bei der Berechnung der Zonenstatistik mit der Funktion ST_REGIONSTATS ist die Pixelgröße der Rasterdaten ein wichtiger Faktor. Die Aggregation von Rasterdaten mit hoher Auflösung über die Region eines Landes kann beispielsweise rechenintensiv und unnötig detailliert sein. Umgekehrt liefern aggregierte Daten mit niedriger Auflösung über die Region, z. B. Stadtgrundstücke, möglicherweise nicht genügend Details.

Um aussagekräftige und effiziente Ergebnisse aus Ihrer Analyse zu erhalten, empfehlen wir, eine Pixelgröße zu wählen, die für die Größe Ihrer Polygone und das Ziel Ihrer Analyse geeignet ist. Die Pixelgröße für jedes Raster-Dataset finden Sie im Beschreibungsbereich der Bildtabellen in BigQuery sharing.

Wenn Sie die Pixelgröße ändern, ändert sich die Anzahl der Pixel, die eine bestimmte geografische Einheit schneiden. Dies wirkt sich auf die Ergebnisse und ihre Interpretation aus. Wir empfehlen, die Pixelgröße für Produktionsanalysen nicht zu ändern. Wenn Sie jedoch eine Abfrage prototypisieren, kann das Erhöhen der Pixelgröße die Laufzeit und die Kosten der Abfrage reduzieren, insbesondere bei Daten mit hoher Auflösung.

Wenn Sie die Pixelgröße ändern möchten, legen Sie die scale im Argument options für die Funktion ST_REGIONSTATS fest. Wenn Sie beispielsweise Statistiken für 1.000-Meter-Pixel berechnen möchten, verwenden Sie options => JSON '{"scale":1000}'. Dadurch wird Earth Engine angewiesen, das Bild mit der angeforderten Skala neu zu berechnen. Weitere Informationen zur Verarbeitung der Neuskalierung durch Earth Engine finden Sie in der Google Earth Engine-Dokumentation unter Scale.

Die Berechnung von Statistiken für Polygone, die deutlich kleiner als die Pixel des Rasters sind, kann zu ungenauen oder leeren Ergebnissen führen. In diesem Fall können Sie das Polygon alternativ mit ST_CENTROIDdurch seinen Mittelpunkt ersetzen.

Abrechnung

Wenn Sie eine Abfrage ausführen, wird die Verwendung der Funktion ST_REGIONSTATS separat von der restlichen Abfrage in Rechnung gestellt, da Earth Engine die Ergebnisse des Funktionsaufrufs berechnet. Diese Nutzung wird Ihnen in Slotstunden unter der BigQuery Services-Artikelnummer in Rechnung gestellt, unabhängig davon, ob Sie die On-Demand-Abrechnung oder Reservierungen verwenden. Die für BigQuery-Aufrufe an Earth Engine in Rechnung gestellte Menge finden Sie in Ihrem Abrechnungsbericht. Filtern Sie nach dem Label-Schlüssel goog-bq-feature-type mit dem Wert EARTH_ENGINE. Wenn die Funktion ST_REGIONSTATS fehlschlägt, werden Ihnen keine Earth Engine-Berechnungen in Rechnung gestellt.

Für jede Abfrage können Sie mit der jobs.get Methode in der BigQuery API die folgenden Informationen aufrufen:

• Das slotMs Feld, das die Anzahl der Slotmillisekunden anzeigt, die von Earth Engine verbraucht wurden, wenn das externalService Feld EARTH_ENGINE und das billingMethod Feld SERVICES_SKU ist.
• Das totalServicesSkuSlotMs Feld, das die Gesamtzahl der Slotmillisekunden anzeigt, die von allen externen BigQuery-Diensten verwendet wurden, die über die BigQuery Services-Artikelnummer abgerechnet werden.

Sie können auch das Feld total_services_sku_slot_ms in der INFORMATION_SCHEMA.JOBS Ansicht abfragen, um die Gesamtzahl der Slotmillisekunden zu ermitteln, die von externen Diensten verbraucht wurden, die über die BigQuery Services-Artikelnummer abgerechnet werden.

Kostenfaktoren

Die folgenden Faktoren wirken sich auf die Compute-Nutzung aus, wenn Sie die Funktion ST_REGIONSTATS ausführen:

• Die Anzahl der Eingabezeilen.
• Das verwendete Rasterbild. Einige Raster sind Composites, die aus Quellbildsammlungen im Earth Engine-Datenkatalog erstellt wurden. Die Rechenressourcen zur Erstellung des Composite-Ergebnisses variieren.
• Die Auflösung des Bildes.
• Die Größe und Komplexität der Eingabegeografie, die Anzahl der Pixel, die die Geografie schneiden, und die Anzahl der Bildkacheln und Byte, die von Earth Engine gelesen werden.

• Die Position der Eingabegeografie auf der Erde im Verhältnis zu den Quellbildern sowie die Projektion und Auflösung des Bildes.

  • Bildprojektionen können Pixel verzerren, insbesondere Pixel in hohen Breitengraden oder weit außerhalb des beabsichtigten Abdeckungsbereichs des Bildes.
  • Bei Composite-Rastern kann die Anzahl der Quellbilder, die die Eingabegeografie schneiden, regional und im Zeitverlauf variieren. Einige Satelliten produzieren beispielsweise je nach Umlaufbahn und Datenerhebungsparametern mehr Bilder in niedrigen oder hohen Breitengraden oder lassen Bilder je nach sich ändernden atmosphärischen Bedingungen aus.

• Die Verwendung von Formeln in den Argumenten include oder band_name und die Anzahl der Bänder, die sie umfassen.

• Das Caching früherer Ergebnisse.

Kosten kontrollieren

Wenn Sie die Kosten für die Funktion ST_REGIONSTATS kontrollieren möchten, können Sie das Kontingent anpassen, das die Menge an Slotzeit steuert, die die Funktion verbrauchen darf. Der Standardwert beträgt 350 Slotstunden pro Tag. Wenn Sie Ihre Kontingente ansehen, filtern Sie die Liste Messwert nach earthengine.googleapis.com/bigquery_slot_usage_time um das Earth Engine-Kontingent für Aufrufe aus BigQuery zu sehen. Weitere Informationen finden Sie in der Google Earth Engine-Dokumentation unter BigQuery raster functions quotas.

Hinweis: Wie benutzerdefinierte Abfragekontingente in BigQuery ist auch dieses Kontingent ein ungefähres Kontingent. Es bietet einen Schutz vor übermäßigen Ausgaben, ist aber nicht dazu gedacht, die Slotzeit streng zu begrenzen. BigQuery kann gelegentlich eine Abfrage ausführen, die das Kontingentlimit überschreitet. Möglicherweise wird Ihr Kontingent erschöpft, ohne dass Ihnen der gesamte verbrauchte Betrag in Rechnung gestellt wird.

Unterstützte Regionen

Abfragen, die die Funktion ST_REGIONSTATS aufrufen, müssen in einer der folgenden Regionen ausgeführt werden:

• Multiregion US
• us-central1
• us-central2
• Multiregion EU
• europe-west1

Nächste Schritte

• Probieren Sie das Tutorial aus, in dem gezeigt wird, wie Sie Rasterdaten verwenden, um die Temperatur zu analysieren.
• Weitere Informationen zu geografischen Funktionen in BigQuery.
• Weitere Informationen zur Arbeit mit raumbezogenen Daten.