Daten aus Datastore-Exporten laden

BigQuery unterstützt das Laden von Daten aus Datastore-Exporten, die mit dem verwalteten Import- und Exportdienst von Datastore erstellt wurden. Sie können diesen verwenden, um Datastore-Entitäten in einen Cloud Storage-Bucket zu exportieren. Danach können Sie den Export als Tabelle in BigQuery laden.

Informationen zum Erstellen einer Datastore-Exportdatei finden Sie in der Datastore-Dokumentation unter Entitäten exportieren und importieren. Informationen zur Planung von Exporten finden Sie unter Export planen.

Hinweis: Wenn Sie einen Datastore-Export in BigQuery laden möchten, müssen Sie in Ihrem Exportbefehl einen Entitätsfilter angeben. Daten, die ohne Angabe eines Entitätsfilters exportiert wurden, können nicht in BigQuery geladen werden.

Sie können festlegen, welche Attribute BigQuery laden soll. Dazu geben Sie in der API das Attribut projectionFields an oder verwenden im bq-Befehlszeilentool das Flag --projection_fields.

Wenn Sie den Ladevorgang überspringen möchten, können Sie den Export direkt abfragen, indem Sie ihn als externe Datenquelle einrichten. Weitere Informationen finden Sie unter Externe Datenquellen.

Wenn Sie Daten aus Cloud Storage in eine BigQuery-Tabelle laden, muss sich das Dataset, das die Tabelle enthält, am selben regionalen oder multiregionalen Standort wie der Cloud Storage-Bucket befinden.

Beschränkungen

Beachten Sie die folgenden Einschränkungen, wenn Sie Daten aus einem Datastore-Export in BigQuery laden:

• Sie können im Cloud Storage-URI keinen Platzhalter verwenden, wenn Sie eine Datastore-Exportdatei angeben.
• Sie können beim Laden von Daten aus Datastore-Exporten nur einen einzelnen Cloud Storage-URI angeben.
• Sie können Datastore-Exportdaten nicht an eine vorhandene Tabelle mit einem definierten Schema anhängen.
• Damit ein Datastore-Export korrekt geladen wird, müssen die Entitäten in den Exportdaten ein konsistentes Schema mit weniger als 10.000 einmaligen Attributnamen haben.
• Daten, die ohne Angabe eines Entitätsfilters exportiert wurden, können nicht in BigQuery geladen werden. Die Exportanfrage muss im Entitätsfilter mindestens einen Typnamen enthalten.
• Die maximale Feldgröße für Datastore-Exporte beträgt 64 KB. Beim Laden eines Datastore-Exports wird jedes Feld, das größer als 64 KB ist, abgeschnitten.

Hinweis

Erteilen Sie IAM-Rollen (Identity and Access Management), die Nutzern die erforderlichen Berechtigungen zum Ausführen der einzelnen Aufgaben in diesem Dokument geben.

Erforderliche Berechtigungen

Zum Laden von Daten in BigQuery benötigen Sie IAM-Berechtigungen, um einen Ladejob auszuführen und Daten in BigQuery-Tabellen und -Partitionen zu laden. Zum Laden von Daten aus Cloud Storage sind außerdem IAM-Berechtigungen für den Zugriff auf den Bucket erforderlich, der Ihre Daten enthält.

Berechtigungen zum Laden von Daten in BigQuery

Wenn Sie Daten in eine neue BigQuery-Tabelle oder -Partition laden oder eine vorhandene Tabelle oder Partition anfügen oder überschreiben möchten, benötigen Sie die folgenden IAM-Berechtigungen:

• bigquery.tables.create
• bigquery.tables.updateData
• bigquery.tables.update
• bigquery.jobs.create

Die folgenden vordefinierten IAM-Rollen enthalten jeweils die Berechtigungen, die zum Laden von Daten in eine BigQuery-Tabelle oder -Partition erforderlich sind:

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin (einschließlich der Berechtigung bigquery.jobs.create)
• bigquery.user (einschließlich der Berechtigung bigquery.jobs.create)
• bigquery.jobUser (einschließlich der Berechtigung bigquery.jobs.create)

Wenn Sie die Berechtigung bigquery.datasets.create haben, können Sie außerdem mit einem Ladejob Tabellen in den von Ihnen erstellten Datasets anlegen und aktualisieren.

Weitere Informationen zu IAM-Rollen und Berechtigungen in BigQuery finden Sie unter Vordefinierte Rollen und Berechtigungen.

Berechtigungen zum Laden von Daten aus Cloud Storage

Um die Berechtigungen zu erhalten, die Sie zum Laden von Daten aus einem Cloud Storage-Bucket benötigen, bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Storage Admin (roles/storage.admin) für den Bucket zu erteilen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Laden von Daten aus einem Cloud Storage-Bucket erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Daten aus einem Cloud Storage-Bucket zu laden:

• storage.buckets.get
• storage.objects.get
• storage.objects.list (required if you are using a URI wildcard)

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

Daten des Datastore-Exportdiensts laden

So laden Sie Daten aus einer Datastore-Metadaten-Exportdatei:

Console

1. Öffnen Sie in der Google Cloud Console die Seite BigQuery.

   BigQuery aufrufen

2. Maximieren Sie im Bereich Explorer Ihr Projekt und wählen Sie dann ein Dataset aus.
3. Klicken Sie im Abschnitt Dataset-Informationen auf Tabelle erstellen.
4. Geben Sie im Bereich Tabelle erstellen die folgenden Details an:
1. Wählen Sie im Abschnitt Quelle in der Liste Tabelle erstellen aus die Option Google Cloud Storage aus. Führen Sie anschließend folgende Schritte aus:
   1. Wählen Sie eine Datei aus dem Cloud Storage-Bucket aus oder geben Sie den Cloud Storage-URI ein. In der Google Cloud Console kann zwar nur ein URI eingefügt werden, aber Platzhalter werden unterstützt. Der Cloud Storage-Bucket muss sich am selben Standort wie das Dataset befinden, das die Tabelle enthält, die Sie erstellen, anhängen oder überschreiben möchten.
      Der URI für Ihre Datastore-Exportdatei sollte auf KIND_NAME.export_metadata oder export[NUM].export_metadata enden. Beispiel: In default_namespace_kind_Book.export_metadata ist Book der Artname und default_namespace_kind_Book der von Datastore generierte Dateiname.
   2. Wählen Sie unter File format (Dateiformat) die Option Cloud Datastore Backup (Cloud Datastore-Sicherung) aus.
2. Geben Sie im Bereich Ziel die folgenden Details an:
   1. Wählen Sie bei Dataset das Dataset aus, in dem Sie die Tabelle erstellen möchten.
   2. Geben Sie im Feld Tabelle den Namen der Tabelle ein, die Sie erstellen möchten.
   3. Achten Sie darauf, dass das Feld Tabellentyp auf Native Tabelle eingestellt ist.
3. Im Abschnitt Schema ist keine Aktion erforderlich. Das Schema wird für einen Firestore-Export abgeleitet.
4. Optional: Geben Sie Partitions- und Clustereinstellungen an. Weitere Informationen finden Sie unter Partitionierte Tabellen erstellen und Geclusterte Tabellen erstellen und verwenden.
5. Klicken Sie auf Erweiterte Optionen und gehen Sie so vor:
   • Lassen Sie unter Write preference (Schreibeinstellung) die Option Write if empty (Schreiben, wenn leer) ausgewählt. Mit dieser Option wird eine neue Tabelle erstellt und Ihre Daten werden in diese Tabelle geladen.
   • Wenn Sie Werte in einer Zeile ignorieren möchten, die im Schema der Tabelle nicht vorhanden sind, wählen Sie Unbekannte Werte aus.
   • Klicken Sie unter Verschlüsselung auf Vom Kunden verwalteter Schlüssel, um einen Cloud Key Management Service-Schlüssel zu verwenden. Wenn Sie die Einstellung Von Google verwalteter Schlüssel übernehmen, verschlüsselt BigQuery inaktive Daten.
   Informationen zu den verfügbaren Optionen finden Sie unter Datastore-Optionen.
6. Klicken Sie auf Tabelle erstellen.

bq

Verwenden Sie den Befehl bq load, bei dem source_format auf DATASTORE_BACKUP gesetzt wurde. Geben Sie das Flag --location an und legen Sie als Wert Ihren Standort fest.

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

Dabei gilt:

• LOCATION: Ihr Standort. Das Flag --location ist optional. Wenn Sie BigQuery beispielsweise in der Region Tokio verwenden, können Sie für das Flag den Wert asia-northeast1 angeben. Mit der Datei .bigqueryrc können Sie für den Standort einen Standardwert festlegen.
• FORMAT: DATASTORE_BACKUP.
• DATASET ist das Dataset mit der Tabelle, in die Sie Daten laden.
• TABLE ist die Tabelle, in die Sie Daten laden. Wenn die Tabelle nicht existiert, wird sie erstellt.
• PATH_TO_SOURCE: Der Cloud Storage-URI.

Der folgende Befehl lädt beispielsweise die Datastore-Exportdatei gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata in die Tabelle book_data. mybucket und mydataset wurden am multiregionalen Standort US erstellt.

bq --location=US load \
--source_format=DATASTORE_BACKUP \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

Wenn Sie Datastore-Exportdaten mithilfe der API laden möchten, legen Sie die folgenden Attribute fest:

1. Erstellen Sie einen Ladejob, der auf die Quelldaten in Cloud Storage verweist.

2. Geben Sie Ihren Standort im Abschnitt jobReference der Jobressource im Attribut location an.

3. Die Quell-URIs müssen voll qualifiziert sein und das Format gs://[BUCKET]/[OBJEKT] haben. Der Name der Datei (des Objekts) muss auf [KIND_NAME].export_metadata enden. Für Datastore-Exporte ist nur ein einzelner URI zulässig und Sie können auch keinen Platzhalter verwenden.

4. Geben Sie das Datenformat an. Legen Sie dazu das Attribut JobConfigurationLoad.sourceFormat auf DATASTORE_BACKUP fest.

Datastore-Daten an eine Tabelle anfügen oder Tabelle mit Datastore-Daten überschreiben

Wenn Sie Datastore-Exportdaten in BigQuery laden, können Sie zum Speichern dieser Daten eine neue Tabelle erstellen oder eine vorhandene überschreiben. Datastore-Exportdaten können Sie nicht an eine vorhandene Tabelle anhängen.

Wenn Sie versuchen, Datastore-Exportdaten an eine vorhandene Tabelle anzuhängen, wird der folgende Fehler ausgegeben: Cannot append a datastore backup to a table that already has a schema. Try using the WRITE_TRUNCATE write disposition to replace the existing table.

So überschreiben Sie eine vorhandene Tabelle mit Datastore-Exportdaten:

Console

1. Öffnen Sie in der Google Cloud Console die Seite BigQuery.

   BigQuery aufrufen

2. Maximieren Sie im Bereich Explorer Ihr Projekt und wählen Sie dann ein Dataset aus.
3. Klicken Sie im Abschnitt Dataset-Informationen auf Tabelle erstellen.
4. Geben Sie im Bereich Tabelle erstellen die folgenden Details an:
1. Wählen Sie im Abschnitt Quelle in der Liste Tabelle erstellen aus die Option Google Cloud Storage aus. Führen Sie anschließend folgende Schritte aus:
   1. Wählen Sie eine Datei aus dem Cloud Storage-Bucket aus oder geben Sie den Cloud Storage-URI ein. In der Google Cloud Console kann zwar nur ein URI eingefügt werden, aber Platzhalter werden unterstützt. Der Cloud Storage-Bucket muss sich am selben Standort wie das Dataset befinden, das die Tabelle enthält, die Sie erstellen, anhängen oder überschreiben möchten.
      Der URI für Ihre Datastore-Exportdatei sollte auf KIND_NAME.export_metadata oder export[NUM].export_metadata enden. Beispiel: In default_namespace_kind_Book.export_metadata ist Book der Artname und default_namespace_kind_Book der von Datastore generierte Dateiname.
   2. Wählen Sie unter File format (Dateiformat) die Option Cloud Datastore Backup (Cloud Datastore-Sicherung) aus.
Hinweis: Sie können das Schema der Tabelle beim Anfügen oder Überschreiben ändern. Weitere Informationen zu unterstützten Schemaänderungen während eines Ladevorgangs finden Sie unter Tabellenschemas ändern.
2. Geben Sie im Bereich Ziel die folgenden Details an:
   1. Wählen Sie bei Dataset das Dataset aus, in dem Sie die Tabelle erstellen möchten.
   2. Geben Sie im Feld Tabelle den Namen der Tabelle ein, die Sie erstellen möchten.
   3. Achten Sie darauf, dass das Feld Tabellentyp auf Native Tabelle eingestellt ist.
3. Im Abschnitt Schema ist keine Aktion erforderlich. Das Schema wird für einen Firestore-Export abgeleitet.
Hinweis: Sie können das Schema der Tabelle beim Anfügen oder Überschreiben ändern. Weitere Informationen zu unterstützten Schemaänderungen während eines Ladevorgangs finden Sie unter Tabellenschemas ändern.
4. Optional: Geben Sie Partitions- und Clustereinstellungen an. Weitere Informationen finden Sie unter Partitionierte Tabellen erstellen und Geclusterte Tabellen erstellen und verwenden. Sie können eine Tabelle nicht durch Anfügen oder Überschreiben von Daten in eine partitionierte oder geclusterte Tabelle konvertieren. Die Google Cloud Console unterstützt nicht das Anfügen oder Überschreiben von Daten in partitionierten oder geclusterten Tabellen in einem Ladejob.
5. Klicken Sie auf Erweiterte Optionen und gehen Sie so vor:
   • Wählen Sie unter Schreibeinstellung die Option An Tabelle anfügen oder Tabelle überschreiben aus.
   • Wenn Sie Werte in einer Zeile ignorieren möchten, die im Schema der Tabelle nicht vorhanden sind, wählen Sie Unbekannte Werte aus.
   • Klicken Sie unter Verschlüsselung auf Vom Kunden verwalteter Schlüssel, um einen Cloud Key Management Service-Schlüssel zu verwenden. Wenn Sie die Einstellung Von Google verwalteter Schlüssel übernehmen, verschlüsselt BigQuery inaktive Daten.
   Informationen zu den verfügbaren Optionen finden Sie unter Datastore-Optionen.
6. Klicken Sie auf Tabelle erstellen.

bq

Verwenden Sie den Befehl bq load mit dem Flag --replace. Dabei muss source_format auf DATASTORE_BACKUP festgelegt sein. Geben Sie das Flag --location an und legen Sie als Wert Ihren Standort fest.

bq --location=LOCATION load \
--source_format=FORMAT \
--replace \
DATASET.TABLE \
PATH_TO_SOURCE

Dabei gilt:

• LOCATION: Ihr Standort. Das Flag --location ist optional. Wenn Sie BigQuery beispielsweise in der Region Tokio verwenden, können Sie für das Flag den Wert asia-northeast1 angeben. Mit der Datei .bigqueryrc können Sie für den Standort einen Standardwert festlegen.
• FORMAT: DATASTORE_BACKUP.
• DATASET ist das Dataset mit der Tabelle, in die Sie Daten laden.
• TABLE ist die Tabelle, die Sie überschreiben.
• PATH_TO_SOURCE: Der Cloud Storage-URI.

Mit dem folgenden Befehl wird beispielsweise die Datastore-Exportdatei gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata geladen und die Tabelle book_data überschrieben.

bq load --source_format=DATASTORE_BACKUP \
--replace \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

Legen Sie die folgenden Attribute fest, um Daten aus der API zu laden.

1. Erstellen Sie einen Ladejob, der auf die Quelldaten in Cloud Storage verweist.

2. Geben Sie Ihren Standort im Abschnitt jobReference der Jobressource im Attribut location an.

3. Die Quell-URIs müssen voll qualifiziert sein und das Format gs://[BUCKET]/[OBJEKT] haben. Der Name der Datei (des Objekts) muss auf [KIND_NAME].export_metadata enden. Für Datastore-Exporte ist nur ein einzelner URI zulässig und Sie können auch keinen Platzhalter verwenden.

4. Geben Sie das Datenformat an. Legen Sie dazu das Attribut JobConfigurationLoad.sourceFormat auf DATASTORE_BACKUP fest.

5. Geben Sie die Schreibanordnung an und legen Sie dafür das Attribut JobConfigurationLoad.writeDisposition auf WRITE_TRUNCATE fest.

Datastore-Optionen

Wenn Sie ändern möchten, wie BigQuery Datastore-Exportdaten parst, geben Sie die folgende Option an:

Console-Option	bq-Tool-Flag	BigQuery API-Attribut	Beschreibung
Nicht verfügbar	--projection_fields	projectionFields	Eine durch Kommas getrennte Liste, die angibt, welche Entitätsattribute aus einem Datastore-Export in BigQuery geladen werden. Bei den Attributnamen wird zwischen Groß- und Kleinschreibung unterschieden und die Attribute müssen aus der obersten Ebene stammen. Wenn keine Attribute angegeben wurden, lädt BigQuery alle Attribute. Wenn benannte Attribute im jeweiligen Datastore-Export nicht gefunden werden, wird im Jobergebnis ein Fehler wegen ungültiger Werte zurückgegeben. Der Standardwert ist “.

Datentyp-Konvertierung

BigQuery wandelt Daten aus jeder in Datastore-Exportdateien vorhandenen Entität in BigQuery-Datentypen um. In der folgenden Tabelle wird die Umwandlung von Datentypen beschrieben.

Datastore-Datentyp	BigQuery-Datentyp
Array	ARRAY
Blob	BYTES
Boolesch	BOOLEAN
Datum und Uhrzeit	TIMESTAMP
Eingebettete Entität	RECORD
Gleitkommazahl	FLOAT
Geografischer Punkt	RECORD [{"lat","DOUBLE"}, {"long","DOUBLE"}]
Ganzzahl	INTEGER
Schlüssel	RECORD
Null	STRING
Textstring	STRING (auf 64 KB abgeschnitten)

Datastore-Schüsselattribute

Jede Entität in Datastore hat einen eindeutigen Schlüssel, der Informationen wie den Namespace und Pfad enthält. BigQuery erstellt für den Schlüssel einen RECORD-Datentyp mit verschachtelten Feldern für jede Informationseinheit, wie in der folgenden Tabelle beschrieben:

Schlüsselattribut	Beschreibung	BigQuery-Datentyp
__key__.app	Der Datastore-Anwendungsname	STRING
__key__.id	Die Entitäts-ID oder null, wenn __key__.name festgelegt ist.	INTEGER
__key__.kind	Der Entitätstyp	STRING
__key__.name	Der Entitätsname oder null, wenn __key__.id festgelegt ist.	STRING
__key__.namespace	Wenn die Datastore-Anwendung einen benutzerdefinierten Namespace verwendet, ist dies der Namespace der Entität. Andernfalls wird der Standard-Namespace durch einen leeren String dargestellt.	STRING
__key__.path	Der vereinfachte übergeordnete Pfad der Entität, der aus der Sequenz von Typ/ID-Paaren von der Stammentität bis zur Entität selbst besteht. Beispiel: "Country", "USA", "PostalCode", 10011, "Route", 1234	STRING