Mit Rasterdaten in BigQuery über Earth Engine arbeiten

Wenn Sie Raster- und Vektordaten mit der Funktion ST_REGIONSTATS kombinieren, können Sie zonale Statistiken wie die durchschnittliche Luftqualität oder das Brandrisiko für bestimmte geografische Regionen berechnen. Sie können die Google Earth Engine direkt in BigQuery verwenden, um Satellitenbilder und Wettervorhersagen zusammen mit Ihren vorhandenen Vektorgrenzen zu analysieren.

Übersicht

Ein Raster ist ein zweidimensionales Pixelgitter, dem jeweils ein oder mehrere Werte zugewiesen sind, die als Bänder bezeichnet werden. Beispielsweise könnte jedes Pixel einem bestimmten Quadratkilometer auf der Erdoberfläche entsprechen und Bänder für die Durchschnittstemperatur und den durchschnittlichen Niederschlag haben. Rasterdaten umfassen 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 häufig mit Vektordaten verglichen, 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.

Georaster- und Vektordaten werden häufig mithilfe eines Vorgangs für zonale Statistiken kombiniert, bei dem ein Aggregat aller Rasterwerte innerhalb einer bestimmten Vektorregion berechnet wird. Sie können beispielsweise Folgendes berechnen:

• Durchschnittliche Luftqualität in einer Reihe von Städten.
• Solarpotenzial für eine Sammlung 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 Geografiefunktion ST_REGIONSTATS können Sie Rasterdaten aus 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, die in BigQuery Sharing (früher Analytics Hub) veröffentlicht wurden, mit der Funktion ST_REGIONSTATS abonnieren und verwenden möchten, 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 der BigQuery-Freigabe 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 Funktion ST_REGIONSTATS 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 finden

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.

Die Google Earth Engine veröffentlicht öffentlich verfügbare Datasets, die Rasterdaten in den multiregionalen Standorten US und EU enthalten. 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 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-Elementspezifikation gespeichert sind. Eine Bildtabelle ist analog zu einer Earth Engine-Bildersammlung (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 auf Bilder, indem Sie diese ID als Wert für den Parameter raster_id verwenden.

Filtern Sie die Tabelle mithilfe von 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 mit unterstützenden Informationen für die Bildtabelle.

Der ERA5-Land-Datensatz bietet beispielsweise tägliche Statistiken zu Klimavariablen und ist öffentlich verfügbar. Die Tabelle climate enthält mehrere Raster-IDs. In der folgenden Abfrage wird die Bildtabelle mithilfe der Spalte start_datetime gefiltert, um die Raster-ID für das Bild vom 1. Januar 2025 abzurufen. Außerdem wird die Durchschnittstemperatur für jedes Land mithilfe des Bands temperature_2m berechnet:

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 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 Georasterdaten. Die Funktion ST_REGIONSTATS unterstützt Rasterdaten, die im Cloud Optimized GeoTIFF-Format (COG) in Cloud Storage-Buckets gespeichert sind, die sich in den folgenden Regionen befinden:

• US, multiregional
• us-central1
• EU, multiregional
• 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 Bildersammlungen 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 das Format ee.Image('IMAGE_PATH') hat, lautet die Raster-ID 'ee://IMAGE_PATH'.

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

Pixel-Gewichte

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

Ein Pixel gilt als gültig, wenn seine Gewichtung größer als 0 ist. Eine Gewichtung von 0 weist auf ein ungültiges Pixel hin. Ungültige Pixel stehen in der Regel für fehlende oder unzuverlässige Daten, z. B. Bereiche, die durch Wolken verdeckt sind, Sensoranomalien, Verarbeitungsfehler oder Orte außerhalb einer definierten Grenze.

Wenn Sie keine Gewichtung angeben, wird jedes Pixel automatisch nach dem Anteil des Pixels gewichtet, der innerhalb der Geometrie liegt. So ist eine proportionale Einbeziehung in zonale Statistiken möglich. Wenn die Geometrie kleiner als 1/256 der Pixelgröße ist, beträgt 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 überschneidendes Pixel eine Gewichtung aus dem Argument include bis ST_REGIONSTATS hat, verwendet BigQuery den Mindestwert dieser Gewichtung und den Bruchteil des Pixels, der sich mit der Region überschneidet.

Gewichtungswerte haben nicht dieselbe Genauigkeit wie FLOAT64-Werte. In der Praxis kann der tatsächliche Wert um bis zu 1/256 (etwa 0,4 %) von dem in Berechnungen verwendeten Wert abweichen.

Sie können im Argument include einen Ausdruck mit der Syntax für Bildausdrücke von Earth Engine angeben, um Pixel dynamisch anhand bestimmter Kriterien in Rasterbändern zu gewichten. Der folgende Ausdruck beschränkt beispielsweise die Berechnungen auf Pixel, bei denen das Band probability 70 % überschreitet:

include => 'probability > 0.7'

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

include => 'weight_factor_band_name'

Pixelgröße und Analyseumfang

Ein Georasterbild ist ein Pixelraster, das einem Ort auf der Erdoberfläche entspricht. Die Pixelgröße eines Rasters, manchmal auch als Maßstab bezeichnet, ist die Nenngröße einer Kante eines Pixels im Koordinatenreferenzsystem des Rasters. Ein Raster mit einer Auflösung von 10 Metern hat beispielsweise Pixel mit einer Größe von 10 × 10 Metern. Die ursprüngliche Pixelgröße kann zwischen Datasets stark variieren, von weniger als 1 Meter bis zu mehr als 20 Kilometern.

Wenn Sie die Funktion ST_REGIONSTATS verwenden, um zonale Statistiken zu berechnen, ist die Pixelgröße der Rasterdaten ein wichtiger Faktor. Beispielsweise kann das Aggregieren von hochauflösenden Rasterdaten über die Region eines Landes rechenintensiv und unnötig detailliert sein. Umgekehrt liefert die Aggregation von Daten mit niedriger Auflösung über die Region, z. B. Stadtparzellen, möglicherweise nicht genügend Details.

Damit Sie aussagekräftige und effiziente Ergebnisse aus Ihrer Analyse erhalten, empfehlen wir, eine Pixelgröße zu wählen, die der Größe Ihrer Polygone und dem Ziel Ihrer Analyse entspricht. Die Pixelgröße für jedes Raster-Dataset finden Sie im Beschreibungsabschnitt der Bildtabellen in BigQuery Sharing.

Wenn Sie die Pixelgröße ändern, ändert sich die Anzahl der Pixel, die sich mit einer bestimmten Geografie überschneiden. Das wirkt sich auf die Ergebnisse und deren Interpretation aus. Wir empfehlen nicht, die Pixelgröße für Produktionsanalysen zu ändern. Wenn Sie jedoch einen Prototyp für eine Abfrage erstellen, kann die Erhöhung der Pixelgröße die Abfragelaufzeit und die Kosten reduzieren, insbesondere bei hochauflösenden Daten.

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 im angeforderten Maßstab neu zu berechnen. Weitere Informationen dazu, wie Earth Engine die Neuskalierung handhabt, finden Sie in der Google Earth Engine-Dokumentation unter Skalierung.

Die Berechnung von Statistiken für Polygone, die deutlich kleiner als die Pixel des Rasters sind, kann zu ungenauen oder Nullergebnissen führen. In diesem Fall können Sie das Polygon mit ST_CENTROID durch seinen Schwerpunkt ersetzen.

Abrechnung

Wenn Sie eine Abfrage ausführen, wird die Verwendung der Funktion ST_REGIONSTATS separat vom Rest der Abfrage abgerechnet, da Earth Engine die Ergebnisse des Funktionsaufrufs berechnet. Diese Nutzung wird Ihnen in Slotstunden unter der BigQuery Services-SKU in Rechnung gestellt, unabhängig davon, ob Sie die On-Demand-Abrechnung oder Reservierungen verwenden. Wenn Sie den Betrag sehen möchten, der für BigQuery-Aufrufe an die Earth Engine in Rechnung gestellt wurde, rufen Sie Ihren Abrechnungsbericht auf und filtern Sie mit Labels nach dem Labelschlü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 die Methode jobs.get in der BigQuery API verwenden, um die folgenden Informationen aufzurufen:

• Das Feld slotMs, das die Anzahl der von Earth Engine verbrauchten Slot-Millisekunden angibt, wenn das Feld externalService den Wert EARTH_ENGINE und das Feld billingMethod den Wert SERVICES_SKU hat.
• Das Feld totalServicesSkuSlotMs, das die Gesamtzahl der Slot-Millisekunden zeigt, die von allen externen BigQuery-Diensten verwendet werden, die über die BigQuery Services-SKU abgerechnet werden.

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

Kostenelemente

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

• Die Anzahl der Eingabezeilen.
• Das Rasterbild, das Sie verwenden. Einige Raster sind zusammengesetzte Bilder, die aus Quellbildsammlungen im Earth Engine Data Catalog erstellt wurden. Die Rechenressourcen, die zum Erstellen des zusammengesetzten Bildes erforderlich sind, variieren.
• Die Auflösung des Bildes.
• Die Größe und Komplexität der Eingabegeografie, die Anzahl der Pixel, die sich mit der Geografie überschneiden, 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 vorgesehenen Abdeckungsbereichs des Bildes.
  • Bei zusammengesetzten Rastern kann die Anzahl der Quellbilder, die sich mit der Eingabegeografie überschneiden, regional und im Laufe der Zeit variieren. Einige Satelliten erzeugen 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 beteiligten Bänder.

• Das Caching früherer Ergebnisse.

Kosten kontrollieren

Wenn Sie die mit der Funktion ST_REGIONSTATS verbundenen Kosten kontrollieren möchten, können Sie das Kontingent anpassen, das die Slot-Zeit steuert, die die Funktion verbrauchen darf. Der Standardwert ist 350 Slot-Stunden pro Tag. Wenn Sie Ihre Kontingente aufrufen, 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-Rasterfunktionskontingente.

Hinweis: Wie bei benutzerdefinierten Abfragekontingenten in BigQuery ist dieses Kontingent ein ungefährer Wert. Es bietet Schutz vor übermäßigen Ausgaben, ist aber nicht dafür gedacht, die Slot-Zeit strikt zu begrenzen. BigQuery kann gelegentlich eine Abfrage ausführen, die das Kontingentlimit überschreitet. Möglicherweise schöpfen Sie Ihr Kontingent aus, 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:

• US, multiregional
• us-central1
• us-central2
• EU, multiregional
• europe-west1

Nächste Schritte

• In dieser Anleitung erfahren Sie, wie Sie Rasterdaten zur Temperaturanalyse verwenden.
• Geografiefunktionen in BigQuery
• Weitere Informationen zur Arbeit mit Geodaten