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.

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 Einführung in 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.

Einschrä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.

Erforderliche Berechtigungen

Wenn Sie Daten in BigQuery laden möchten, benötigen Sie Berechtigungen zum Ausführen eines Ladejobs und zum Laden von Daten in neue oder vorhandene BigQuery-Tabellen und -Partitionen. Zum Laden von Daten aus Cloud Storage sind außerdem Berechtigungen für den Zugriff auf den Bucket erforderlich, der Ihre Daten enthält.

BigQuery-Berechtigungen

Die folgenden Berechtigungen sind mindestens erforderlich, um Daten in BigQuery zu laden. Sie werden benötigt, wenn Sie Daten in eine neue Tabelle oder Partition laden oder Daten in einer Tabelle oder Partition anfügen oder überschreiben möchten:

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

Die folgenden vordefinierten IAM-Rollen enthalten die Berechtigungen bigquery.tables.create und bigquery.tables.updateData:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

Die folgenden vordefinierten IAM-Rollen enthalten Berechtigungen vom Typ bigquery.jobs.create:

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

Wenn ein Nutzer mit Berechtigungen vom Typ bigquery.datasets.create ein Dataset erstellt, hat er dafür außerdem bigquery.dataOwner-Zugriff. Mit bigquery.dataOwner-Zugriff kann der Nutzer Tabellen im Dataset über einen Ladejob erstellen und aktualisieren.

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

Cloud Storage-Berechtigungen

Zum Laden von Daten aus einem Cloud Storage-Bucket benötigen Sie die Berechtigung storage.objects.get. Wenn Sie einen URI-Platzhalter verwenden, benötigen Sie außerdem die Berechtigung storage.objects.list.

Die vordefinierte IAM-Rolle storage.objectViewer kann erteilt werden, um die Berechtigungen storage.objects.get und storage.objects.list zu gewähren.

Daten des Datastore-Exportdiensts laden

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

Console

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

    Zur Seite "BigQuery"

  2. Maximieren Sie im Navigationsbereich im Abschnitt Ressourcen Ihr Google Cloud-Projekt und wählen Sie ein Dataset aus. Klicken Sie auf Create table (Tabelle erstellen). Der Vorgang zum Laden von Daten ist mit dem Vorgang zum Erstellen einer leeren Tabelle identisch.

    Grafik: Tabelle erstellen

  3. Gehen Sie auf der Seite Tabelle erstellen im Abschnitt Quelle so vor:

    • Wählen Sie unter Tabelle erstellen aus die Option Cloud Storage aus.
    • Geben Sie im Quellfeld den Cloud Storage-URI ein. Der Cloud Storage-Bucket muss sich am selben Standort wie das Dataset befinden, das die von Ihnen erstellte Tabelle enthält. Der URI für Ihre Datastore-Exportdatei sollte auf [KIND_NAME].export_metadata oder export[NUM].export_metadata enden. Beispiel: default_namespace_kind_Book.export_metadata. In diesem Beispiel ist Book der Typname und default_namespace_kind_Book der von Datastore generierte Dateiname.
    • Wählen Sie Datastore-Sicherung als Dateiformat aus.
  4. Gehen Sie auf der Seite Tabelle erstellen im Bereich Ziel wie folgt vor:

    • Wählen Sie für Dataset-Name das entsprechende Dataset aus.

      Grafik: Dataset auswählen

    • Geben Sie im Feld Tabellenname den Namen der Tabelle ein, die Sie in BigQuery erstellen.

    • Achten Sie darauf, dass der Tabellentyp auf Native Tabelle eingestellt ist.

  5. Im Bereich Schema ist keine Aktion erforderlich. Das Schema wird aus einem Datastore-Export abgeleitet.

  6. Wählen Sie die entsprechenden Elemente im Abschnitt Erweiterte Optionen aus und klicken Sie dann auf Tabelle erstellen. Informationen zu den verfügbaren Optionen finden Sie unter Datastore-Optionen.

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. Setzen Sie dazu das Attribut configuration.load.sourceFormat auf DATASTORE_BACKUP.

Datastore Admin-Back-ups

Wenn Sie Datastore-Daten mithilfe des Back-up-Features von Datastore Admin exportieren, müssen Sie beachten, dass diese Dateien die Endung .backup_info und nicht .export_metadata haben. Solange der Datastore Admin-Back-up-Dienst verfügbar ist, können Sie beim Importieren Ihrer Daten in BigQuery entweder eine .backup_info- oder eine .export_metadata-Datei verwenden.

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 Cloud Console die Seite „BigQuery“. Zur Seite „BigQuery“
  2. Maximieren Sie im Navigationsbereich im Abschnitt Ressourcen Ihr Cloud-Projekt und wählen Sie ein Dataset aus. Klicken Sie auf Create table (Tabelle erstellen). Der Vorgang zum Laden von Daten ist mit dem Vorgang zum Erstellen einer leeren Tabelle identisch. Grafik: Tabelle erstellen
  3. Gehen Sie auf der Seite Tabelle erstellen im Abschnitt Quelle so vor:

    • Wählen Sie unter Tabelle erstellen aus die Option Cloud Storage aus.

    • Geben Sie im Quellfeld den Cloud Storage-URI ein. Der Cloud Storage-Bucket muss sich am selben Standort wie das Dataset befinden, das die von Ihnen erstellte Tabelle enthält. Der URI für Ihre Datastore-Exportdatei sollte auf [KIND_NAME].export_metadata enden. Beispiel: default_namespace_kind_Book.export_metadata. In diesem Beispiel ist Book der Typname und default_namespace_kind_Book der von Datastore generierte Dateiname.

      Prüfen Sie, ob [KIND_NAME] in Ihrem Cloud Storage-URI angegeben ist. Wenn Sie den URI ohne [KIND_NAME] angeben, wird der folgende Fehler angezeigt: does not contain valid backup metadata. (error code: invalid).

    • Wählen Sie Datastore-Sicherung als Dateiformat aus.

  4. Gehen Sie auf der Seite Tabelle erstellen im Bereich Ziel wie folgt vor:

    • Wählen Sie für Dataset-Name das entsprechende Dataset aus.

      Grafik: Dataset auswählen

    • Geben Sie im Feld Tabellenname den Namen der Tabelle ein, die Sie in BigQuery erstellen.

    • Achten Sie darauf, dass der Tabellentyp auf Native Tabelle eingestellt ist.

  5. Im Bereich Schema ist keine Aktion erforderlich. Das Schema wird aus einem Datastore-Export abgeleitet.

  6. Wählen Sie im Abschnitt Erweiterte Optionen unter Schreibeinstellung die Option Tabelle überschreiben aus.

  7. Klicken Sie auf Create table (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. Setzen Sie dazu das Attribut configuration.load.sourceFormat auf DATASTORE_BACKUP.

  5. Geben Sie die Schreibanordnung an und legen Sie für das Attribut configuration.load.writeDisposition als Wert 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
Blob BYTES
Blobstore-Schlüssel STRING
Boolescher Wert BOOLEAN
Kategorie STRING
Cloud Datastore-Schlüssel RECORD
Datum und Uhrzeit TIMESTAMP
E-Mail-Adresse STRING
Eingebettete Entität RECORD
Gleitkommazahl FLOAT
Geografischer Punkt

RECORD


[{"lat","DOUBLE"},
 {"long","DOUBLE"}]
        
IM-Handle STRING
Ganzzahl INTEGER
Link STRING
Telefonnummer STRING
Postanschrift STRING
Bewertung INTEGER
Short Blob BYTES
String STRING (auf 64 KB abgeschnitten)
Nutzer

RECORD


[{"email","STRING"}
 {"userid","STRING"}]
        

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