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 eingelesen. Er stellt eine Verbindung zu einer angegebenen 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 Ergebnisse direkt an den Client zurück, damit sie angezeigt oder als Komponente 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 EECU-Stunden, die während der Verarbeitung der Anfrage verwendet werden, werden dem Aufrufer in Rechnung gestellt, wie bei jeder anderen Earth Engine-Methode (siehe EECUs – Übersicht).

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

Daten aus BigQuery abfragen

Mit der Methode ee.FeatureCollection.runBigQuery() wird eine BigQuery-SQL-Abfrage ausgeführt und die Ergebnisse werden als ee.FeatureCollection-Objekt zurückgegeben. Weitere Informationen zu Abfragen finden Sie in der Dokumentation zum Ausführen von Abfragen.

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 von Abfragen). So können Sie wichtige BigQuery-Funktionen nutzen:

• Jobverlauf: Hier können Sie auf einen sechsmonatigen Verlauf der Abfrageausführungen Ihres Projekts zugreifen (Jobs auflisten).
• Abfrage-Caching: BigQuery speichert Abfrageergebnisse automatisch im Cache, wenn möglich. Bei nachfolgenden identischen Abfragen werden Daten aus dem Cache abgerufen, wodurch redundante Gebühren vermieden werden (weitere Informationen finden Sie unter Im Cache gespeicherte Abfrageergebnisse verwenden).

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

Abrechnung

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

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

Der Parameter maxBytesBilled dient als Sicherheitsmaßnahme, um potenzielle Kosten im Zusammenhang mit ee.FeatureCollection.runBigQuery() zu kontrollieren. Alle BigQuery-Jobs, die dieses Limit überschreiten, schlagen fehl und werden nicht abgerechnet. Der Standardwert von maxBytesBilled ist 100 GB. Wenn Ihr Anruf aufgrund einer Ü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 für das Cloud-Projekt des Aufrufers die BigQuery API und die BigQuery Storage API 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, Lesesitzungen und Jobs im Zielprojekt zu erstellen. Die erforderlichen BigQuery-Berechtigungen sind:

• 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

Weitere Informationen zum Verwalten von Berechtigungen finden Sie in der Dokumentation zur BigQuery-Zugriffssteuerung.

Datenfilterung

Jeder ee.FeatureCollection kann mit der Methode .filter(Filter) gefiltert werden. Damit Google Earth Engine-Nutzer von der hochgradig 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 Leseanfrage für die Tabelle. Bei diesem Ansatz wird die Filterverarbeitung zwar in den BigQuery-Stack verlagert, es gelten aber auch zwei Einschränkungen:

1. Wie jede andere Abfrage in BigQuery (siehe BigQuery-Kontingente) ist diese Anfrage auf eine Größe von 10 MB begrenzt. Das bedeutet, dass übergebene Filter nicht zu kompliziert sein dürfen. Wenn das Limit von 10 MB überschritten 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.

   Dieser Fehler tritt häufig auf, wenn Sie nach Geometrien mit vielen Knoten filtern. Um dieses Problem zu beheben, sollten Sie ee.Geometry.simplify() für das problematische Objekt verwenden.

2. Einige komplexere 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 übersetzen wir den Filter nicht, sondern wenden ihn nach dem Lesen der Daten in Earth Engine an.

Datenindexierung

Earth Engine-Sammlungen basieren auf der internen Indexierung, während in BigQuery davon abgeraten wird, Tabellen indexiert zu lassen. Damit die beiden Systeme zusammenarbeiten, erstellen wir Sammlungsindexe auf folgende Weise:

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

  In solchen Fällen muss der Aufrufer dafür sorgen, dass die Indexe eindeutig sind. Andernfalls kann es zu unerwartetem Verhalten kommen. Der Featureindex muss ein nicht leerer String sein. Das Laden einer BigQuery-Tabelle mit einem Nicht-String-Wert oder einem null-Wert 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, einschließlich der Filter. Andernfalls können wir nicht davon ausgehen, dass die Indexe denselben Merkmalen entsprechen. Wenn eine genaue eindeutige Datenindexierung für den Anrufer wichtig ist, empfehlen wir daher, 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 begrenzt. Wenn dieses Limit erreicht wird, wird der folgende 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 Selektoren verwenden, um nur die erforderlichen Spalten zu lesen, oder ee.FeatureCollection.runBigQuery() verwenden, um die Tabelle in BigQuery vorzuverarbeiten und die Menge der abgerufenen Daten zu verringern.

• Bei der Methode ee.FeatureCollection.runBigQuery() gilt eine Beschränkung von 10 GB für die Größe von Abfrageergebnissen. Quelltabellen können zwar eine beliebige Größe haben, aber die Verarbeitung größerer Datenmengen erhöht die Abfragekosten.

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

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

Vorsichtsmaßnahmen

• Die ee.FeatureCollection.loadBigQueryTable() unterstützt keine Ressourcen aus verknüpften Datasets. Wenn Sie versuchen, Daten aus einer solchen Tabelle zu laden, erhalten Sie den Fehler „Tabelle nicht gefunden“.

  Als Problemumgehung können Sie ee.FeatureCollection.runBigQuery() mit einer Abfrage ausführen, in der die angeforderte Tabelle aus dem verknüpften Dataset angegeben wird. 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')
        

• Das Verknüpfen von BigQuery-Tabellen mit automatisch generierten IDs über system:index kann zu unerwartetem Verhalten führen. Um dies zu verhindern, können Sie der BigQuery-Tabelle manuell system:index hinzufügen oder die Tabelle mit einer anderen Property verknüpfen. Weitere Informationen zur Indexierung finden Sie im Abschnitt „Datenindexierung“.

• Die Methode ee.FeatureCollection.randomColumn() funktioniert nicht mit automatisch generierten BigQuery-IDs. 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“.