Aus BigQuery abrufen

Auf dieser Seite wird beschrieben, wie Sie BigQuery-Tabellen mithilfe der Methoden ee.FeatureCollection.loadBigQueryTable() und ee.FeatureCollection.runBigQuery() als ee.FeatureCollection-Objekte in Earth Engine-Workflows einbinden.

Daten aus BigQuery laden

Mit der Funktion ee.FeatureCollection.loadBigQueryTable() wird eine BigQuery-Tabelle nahtlos in ein ee.FeatureCollection-Objekt gelesen. Er stellt eine Verbindung zu einer bestimmten Tabelle her, konvertiert alle Datentypen, wendet die erforderlichen Filter und Selektoren an und fügt der Sammlung bei Bedarf eine Indexierung hinzu. Die Funktion verwendet die interaktive Umgebung von Earth Engine und gibt die Ergebnisse direkt an den Client zurück, damit sie angezeigt oder als Teil einer größeren Analyse verwendet werden können.

JavaScript

// Load the BigQuery table with a specified geometry column.
var features = ee.FeatureCollection.loadBigQueryTable({
  table: 'my_project.my_dataset.my_table',
  geometryColumn: 'geo'
});

// Display features on the map.
Map.addLayer(features);

Python

# Load the BigQuery table with a specified geometry column.
features = ee.FeatureCollection.loadBigQueryTable(
    table='my_project.my_dataset.my_table',
    geometryColumn='geo')

# Display the first feature.
display(features.first().getInfo())

Abrechnung

Die Kosten für die bei der Verarbeitung der Anfrage verwendeten EECU-Stunden werden dem Aufrufer wie bei jeder anderen Earth Engine-Methode in Rechnung gestellt (siehe EECUs – Übersicht).

Für die Übertragung der Daten in Earth Engine fallen keine zusätzlichen BigQuery-Kosten an. Die entsprechende BigQuery-Nutzung wird im Google Cloud API-Dashboard des verwendeten Projekts angezeigt (siehe API-Nutzung im Blick behalten). Das Lesen von BigQuery-Daten auf diese Weise ist jedoch kostenlos.

Daten aus BigQuery abfragen

Die Methode ee.FeatureCollection.runBigQuery() führt eine BigQuery-SQL-Abfrage aus und gibt die Ergebnisse als ee.FeatureCollection-Objekt zurück. Weitere Informationen zu Abfragen finden Sie im Hilfeartikel Abfrage ausführen.

JavaScript

// Construct a BigQuery query.
var query = 'SELECT * FROM my_project.my_dataset.my_table WHERE column > 1000';

// Run the query and return the results as a FeatureCollection.
var features = ee.FeatureCollection.runBigQuery(query);

// Print the first feature.
print(features.first());

Python

# Construct a BigQuery query.
query = 'SELECT * FROM my_project.my_dataset.my_table WHERE column > 1000'

# Run the query and retrieve the results as a FeatureCollection.
features = ee.FeatureCollection.runBigQuery(query)

# Print the first feature.
print(features.first().getInfo())

BigQuery-Abfragen

Jeder Aufruf von ee.FeatureCollection.runBigQuery() initiiert einen separaten BigQuery-Abfragejob. Weitere Informationen zu Abfragen finden Sie in der Dokumentation zum Ausführen einer Abfrage. Sie können dann wichtige BigQuery-Funktionen verwenden:

  • Jobverlauf: Hier können Sie den sechsmonatigen Verlauf der Abfrageausführungen Ihres Projekts einsehen. Weitere Informationen finden Sie unter Jobs auflisten.
  • Abfrage-Caching: In BigQuery werden Abfrageergebnisse nach Möglichkeit automatisch zwischengespeichert. Bei nachfolgenden identischen Abfragen werden Daten aus dem Cache abgerufen, um redundante Abbuchungen zu vermeiden. Weitere Informationen finden Sie unter Im Cache gespeicherte Abfrageergebnisse verwenden.

Weitere Informationen zu Abfragen oder ihrer Verwendung in BigQuery finden Sie in der BigQuery-Dokumentation.

Abrechnung

Die Kosten der EECUs, die bei der Verarbeitung der Anfrage verwendet werden, werden dem Aufrufer wie bei jeder anderen Earth Engine-Methode in Rechnung gestellt (siehe EECUs – Übersicht). Außerdem wird dem Aufrufer gemäß dem BigQuery-Abrechnungsmodell das Ausführen einer Abfrage in Rechnung gestellt.

Für die Übertragung der Daten in Earth Engine fallen keine zusätzlichen BigQuery-Kosten an. Die entsprechende BigQuery-Nutzung wird im Google Cloud API-Dashboard des verwendeten Projekts angezeigt (siehe API-Nutzung im Blick behalten). Das Lesen von BigQuery-Daten auf diese Weise ist jedoch kostenlos.

Der Parameter maxBytesBilled dient als Schutzmaßnahme, um potenzielle Kosten im Zusammenhang mit ee.FeatureCollection.runBigQuery() zu kontrollieren. BigQuery-Jobs, die dieses Limit überschreiten, schlagen fehl und werden nicht in Rechnung gestellt. Der Standardwert von maxBytesBilled ist 100 GB. Wenn Ihr Aufruf aufgrund der Überschreitung dieses Limits blockiert wird, können Sie in Ihrem Script einen anderen Wert angeben.

Voraussetzungen und Berechtigungen

Damit Sie diese Funktion verwenden können, müssen die BigQuery API und die BigQuery Storage API im Cloud-Projekt des Aufrufers aktiviert sein. Folgen Sie der Anleitung auf der Seite „API aktivieren“, um die entsprechenden APIs zu aktivieren.

Zusätzlich zu den Standardrollen und ‑berechtigungen für Earth Engine benötigen Sie Lesezugriff auf die referenzierte BigQuery-Tabelle sowie die Berechtigung zum Erstellen von Lesesitzungen und Jobs im Zielprojekt. Folgende BigQuery-Berechtigungen sind erforderlich:

  • bigquery.tables.get (für jede Tabelle, auf die zugegriffen wird)
  • bigquery.tables.getData (für jede Tabelle, auf die zugegriffen wird)
  • bigquery.readSession.create
  • bigquery.jobs.create

Ausführliche Informationen zum Verwalten von Berechtigungen finden Sie in der Dokumentation zur Zugriffssteuerung in BigQuery.

Datenfilterung

Jede ee.FeatureCollection kann mit der Methode .filter(Filter) gefiltert werden. Damit Google Earth Engine-Nutzer von der hoch parallelisierten Verarbeitung tabellarischer BigQuery-Daten profitieren können, übersetzen wir Earth Engine-Filter in eine für BigQuery verständliche Sprache und senden sie zusammen mit einer Abfrage zum Lesen von Tabellen. Bei diesem Ansatz wird die Filterverarbeitung zwar in den BigQuery-Stack verschoben, aber es gibt auch zwei Einschränkungen:

  1. Wie jede andere Abfrage in BigQuery (siehe BigQuery-Kontingente) ist diese Anfrage auf 10 MB begrenzt. Das bedeutet, dass übergebene Filter nicht zu kompliziert sein dürfen. Wenn das Limit von 10 MB erreicht wird, wird der folgende Fehler ausgegeben:

    Filter sent to BigQuery is too long. This error may be caused by too complicated geometry in geometry filters. Consider simplifying the filter and used values.

    Eine häufige Ursache für diesen Fehler ist das Filtern nach Geometrien mit vielen Eckpunkten. Verwenden Sie zum Beheben dieses Problems ee.Geometry.simplify() für das betreffende Objekt.

  2. Einige kompliziertere Earth Engine-Filter können nicht in ihre BigQuery-Entsprechungen konvertiert werden. In BigQuery werden beispielsweise keine Gleichheitsprüfungen für ARRAYs unterstützt. In solchen Fällen wird der Filter nicht übersetzt, sondern nach dem Lesen der Daten in Earth Engine angewendet.

Datenindexierung

Earth Engine-Sammlungen basieren auf der internen Indexierung, während in BigQuery die Indexierung von Tabellen nicht empfohlen wird. Damit diese beiden Systeme zusammenarbeiten, erstellen wir Sammlungsindizes auf folgende Weise:

  • Wenn die BigQuery-Tabelle eine Spalte mit dem Namen system:index enthält, wird sie zum Indexieren von „FeatureCollection“ verwendet.

    In solchen Fällen muss der Aufrufer dafür sorgen, dass die Indexe eindeutig sind. Andernfalls kann die Sammlung sich unerwartet verhalten. Der Featureindex muss ein nicht leerer String sein. Das Laden einer BigQuery-Tabelle mit einem anderen Wert als String oder null für eine system:index-Spalte schlägt fehl.

  • Wenn die BigQuery-Tabelle die Spalte system:index nicht enthält, wird sie automatisch generiert.

    Indizes zwischen zwei Leseanfragen sind stabil, aber nur, wenn die Anfragen genau gleich sind, wobei Filter berücksichtigt werden. Andernfalls können wir nicht davon ausgehen, dass die Indexe denselben Funktionen entsprechen. Wenn für den Aufrufer eine genaue Indexierung eindeutiger Daten wichtig ist, empfehlen wir, die Spalte system:index in BigQuery manuell hinzuzufügen.

Beschränkungen

  • Die Größe aller ausgewählten Spalten der Tabelle, auf die in einem ee.FeatureCollection.loadBigQueryTable()-Aufruf verwiesen wird, ist auf 400 GB beschränkt. Wird dieses Limit überschritten, wird folgender Fehler ausgegeben:

    Failed to read table from BigQuery: Requested data size is too large to read. Consider using selectors to specify only required columns.

    In solchen Fällen sollten Sie restriktivere Auswahlkriterien für die erforderlichen Spalten in Lesezugriff festlegen oder ee.FeatureCollection.runBigQuery() verwenden, um die Tabelle in BigQuery vorzuverarbeiten und die Anzahl der abgerufenen Daten zu verringern.

  • Bei der Methode ee.FeatureCollection.runBigQuery() gilt eine Größenbeschränkung von 10 GB für Abfrageergebnisse. Quelltabellen können beliebig groß sein. Die Verarbeitung größerer Datenmengen erhöht jedoch die Abfragekosten.

  • Die Größe des übersetzten Filters ist auf 10 MB begrenzt. Weitere Informationen finden Sie im Abschnitt Datenfilterung.

  • Die Verwendung von ee.FeatureCollection.loadBigQueryTable() oder ee.FeatureCollection.runBigQuery() ist in Earth Engine-Apps nicht möglich.

Vorsichtsmaßnahmen

  • ee.FeatureCollection.loadBigQueryTable() unterstützt keine Ressourcen aus verknüpften Datasets. Beim Laden von Daten aus einer solchen Tabelle wird der Fehler „Tabelle nicht gefunden“ ausgegeben.

    Als Problemumgehung können Sie ee.FeatureCollection.runBigQuery() mit einer Abfrage ausführen, in der die gewünschte Tabelle aus dem verknüpften Datenpool angegeben ist. Beispiel:

    JavaScript

    var features = ee.FeatureCollection.runBigQuery({
  query: 'SELECT * FROM my_project.my_linked_dataset.my_table',
  geometryColumn: 'geo'
});

    Python

    features = ee.FeatureCollection.runBigQuery(
  query='SELECT * FROM my_project.my_linked_dataset.my_table',
  geometryColumn='geo')

  • Wenn Sie BigQuery-Tabellen mit automatisch generierten IDs anhand von system:index zusammenführen, kann dies zu unerwarteten Ergebnissen führen. Sie können dies verhindern, indem Sie system:index manuell zur BigQuery-Tabelle hinzufügen oder die Tabelle anhand einer anderen Property zusammenführen. Weitere Informationen zur Indexierung finden Sie im Abschnitt Datenindexierung.

  • Die Methode ee.FeatureCollection.randomColumn() funktioniert nicht mit automatisch generierten IDs in BigQuery. Sie können einen alternativen Schlüssel mit dem Parameter rowKeys in der Methode ee.FeatureCollection.randomColumn() angeben. Sie können der BigQuery-Quelltabelle auch manuell random- oder system:index-Spalten hinzufügen. Weitere Informationen zur Indexierung finden Sie im Abschnitt Datenindexierung.