Daten aus Firestore-Exporten laden

BigQuery unterstützt das Laden von Daten aus Firestore-Exporten, die mit dem verwalteten Import- und Exportdienst von Firestore erstellt wurden. Mit dem verwalteten Import- und Exportdienst werden Firestore-Dokumente in einen Cloud Storage-Bucket exportiert. Danach können Sie die exportierten Daten in eine BigQuery-Tabelle laden.

Hinweis: Nicht alle oben beschriebenen Funktionen werden beim Laden von Firestore-Exporten unterstützt. Sie können beim Laden von Daten aus einem Firestore-Export keine URI-Platzhalter verwenden und keine Daten an eine vorhandene Tabelle anfügen.

Einschränkungen

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

• Das Dataset muss sich am selben regionalen oder multiregionalen Standort wie der Cloud Storage-Bucket mit den Exportdateien befinden.
• Sie können nur einen einzigen Cloud Storage-URI angeben und keinen URI-Platzhalter verwenden.
• Damit ein Firestore-Export korrekt geladen wird, muss für die Dokumente in den Exportdaten ein konsistentes Schema mit weniger als 10.000 eindeutigen Feldnamen verwendet werden.
• Sie können die Daten in einer neu erstellten Tabelle speichern oder eine vorhandene Tabelle damit überschreiben. Firestore-Exportdaten können nicht an eine vorhandene Tabelle angehängt werden.
• Im Exportbefehl muss ein collection-ids-Filter angegeben werden. Daten, die ohne Angabe eines Sammlungs-ID-Filters exportiert wurden, können nicht in BigQuery geladen werden.

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 Firestore-Exportdienstes laden

Zum Laden von Daten aus der Metadatendatei eines Firestore-Exports können Sie die Cloud Console, das bq-Befehlszeilentool oder die API verwenden.

In der Cloud Console und im bq-Befehlszeilentool wird manchmal Datastore-Terminologie verwendet. Die folgenden Verfahren sind jedoch mit Firestore-Exportdateien kompatibel. Firestore und Datastore verwenden dasselbe Exportformat.

Hinweis: Sie können bestimmte Felder laden, wenn Sie das Flag --projection_fields im bq-Befehlszeilentool verwenden oder das Attribut projectionFields in der Jobkonfiguration load festlegen.

Console

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

   Zur Seite "BigQuery"

2. Maximieren Sie im Bereich Explorer Ihr Projekt und wählen Sie ein Dataset aus.

   Hinweis: Die Standardeinstellung ist die Vorschau der Cloud Console. Wenn Sie auf Vorschaufunktionen ausblenden geklickt haben, um zur allgemein verfügbaren Cloud Console zu gelangen, gehen Sie stattdessen so vor: Maximieren Sie im Navigationsbereich im Abschnitt Ressourcen Ihr Projekt und wählen Sie ein Dataset aus.

3. Klicken Sie im Detailfeld auf Tabelle erstellen.

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

   • Wählen Sie für Create table from (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 Speicherort wie Ihr Dataset befinden. Der URI für Ihre Firestore-Exportdatei sollte auf KIND_COLLECTION_ID.export_metadata enden. Beispiel: default_namespace_kind_Book.export_metadata In diesem Beispiel ist Book die Sammlungs-ID und default_namespace_kind_Book der von Firestore generierte Dateiname.

     Hinweis: Verwenden Sie nicht die Datei, die auf overall_export_metadata endet. Sie kann in BigQuery nicht verwendet werden.

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

   • Wählen Sie Datastore Backup (Datastore-Sicherung) als File format (Dateiformat) aus. Dies ist die geeignete Option für Firestore. Firestore und Datastore verwenden dasselbe Exportformat.

5. Gehen Sie auf der Seite Create table (Tabelle erstellen) im Abschnitt Destination (Ziel) so vor:

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

     

   • 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.

6. Im Abschnitt Schema ist keine Aktion erforderlich. Das Schema wird für einen Firestore-Export abgeleitet.

7. Wählen Sie im Abschnitt Advanced Options (Erweiterte Optionen) entsprechende Elemente aus. Wenn Sie eine vorhandene Tabelle überschreiben, setzen Sie Write preference (Schreibeinstellung) auf Overwrite table (Tabelle überschreiben).

   

8. 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. Wenn Sie eine vorhandene Tabelle überschreiben, fügen Sie das Flag --replace hinzu.

Wenn Sie nur bestimmte Felder laden möchten, verwenden Sie das Flag "--projection_fields".

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

Dabei gilt:

• LOCATION: Ihr Standort. Das Flag --location ist optional.
• FORMAT: DATASTORE_BACKUP. Dies ist die geeignete Option für Firestore. Firestore und Datastore verwenden dasselbe Exportformat.
• DATASET: Das Dataset mit der Tabelle, in die Sie Daten laden.
• TABLE: Die Tabelle, in die Sie Daten laden. Wenn die Tabelle nicht vorhanden ist, wird sie erstellt.
• PATH_TO_SOURCE: Der Cloud Storage-URI.

Mit dem folgenden Befehl wird beispielsweise die Firestore-Exportdatei gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata in eine Tabelle mit dem Namen book_data geladen. 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 Firestore-Exportdaten mithilfe der API laden möchten, legen Sie die folgenden Attribute fest:

1. Erstellen Sie eine Jobkonfiguration (load), die auf die Quelldaten in Cloud Storage verweist.

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

3. sourceUris muss vollständig qualifiziert sein und das Format gs://BUCKET/OBJECT in der Ladejobkonfiguration aufweisen. Der Name der Datei (des Objekts) muss auf KIND_NAME.export_metadata enden. Für Firestore-Exporte ist nur ein URI zulässig und Sie können keinen Platzhalter verwenden.

4. Geben Sie das Datenformat an. Setzen Sie dazu das Attribut sourceFormat in der Ladejobkonfiguration auf DATASTORE_BACKUP. Dies ist die geeignete Option für Firestore. Firestore und Datastore verwenden dasselbe Exportformat.

5. Wenn Sie nur bestimmte Felder laden möchten, verwenden Sie das Attribut projectionFields.

6. Wenn Sie eine vorhandene Tabelle überschreiben, geben Sie die Schreibanordnung durch Setzen des Attributs writeDisposition auf WRITE_TRUNCATE an.

Hinweis: Wenn Sie den Ladevorgang überspringen möchten, können Sie den Export direkt abfragen. Richten Sie ihn hierfür als externe Datenquelle ein. Weitere Informationen finden Sie unter Externe Datenquellen.

Firestore-Optionen

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

Cloud Console-Option	„bq“-Flag	BigQuery API-Attribut	Beschreibung
Nicht verfügbar	--projection_fields	projectionFields	(Optional) Eine durch Kommas getrennte Liste, die angibt, welche Dokumentfelder aus einem Firestore-Export geladen werden sollen. Standardmäßig werden von BigQuery alle Felder geladen. Bei Feldnamen wird zwischen Groß- und Kleinschreibung unterschieden und sie müssen im Export enthalten sein. Sie können in einem Zuordnungsfeld keine Feldpfade wie map.foo angeben.

Datentyp-Konvertierung

BigQuery wandelt Daten aus jedem in Firestore-Exportdateien vorhandenen Dokument in BigQuery-Datentypen um. In der folgenden Tabelle wird die Umwandlung von unterstützten Datentypen beschrieben.

Firestore-Datentyp	BigQuery-Datentyp
Array	RECORD
Boolean	BOOLEAN
Reference	RECORD
Datum und Uhrzeit	TIMESTAMP
Map	RECORD
Gleitkommazahl	FLOAT
Geografischer Punkt	RECORD [{"lat","FLOAT"}, {"long","FLOAT"}]
Integer	INTEGER
String	STRING (auf 64 KB abgeschnitten)

Wichtige Firestore-Attribute

Jedes Dokument in Firestore hat einen eindeutigen Schlüssel, der Informationen wie die Dokument-ID und den Dokumentpfad enthält. BigQuery erstellt für den Schlüssel den Datentyp RECORD mit verschachtelten Feldern für jede Informationseinheit. Der Datentyp für den Schlüssel wird auch als STRUCT bezeichnet. Eine Beschreibung finden Sie in der folgenden Tabelle:

Schlüsselattribut	Beschreibung	BigQuery-Datentyp
__key__.app	Der Name der Firestore-App	STRING
__key__.id	Die Dokument-ID oder null, wenn __key__.name festgelegt ist.	INTEGER
__key__.kind	Die Sammlungs-ID des Dokuments	STRING
__key__.name	Der Name des Dokuments oder null, wenn __key__.id festgelegt ist.	STRING
__key__.namespace	Firestore unterstützt keine benutzerdefinierten Namespaces. Der Standard-Namespace wird durch einen leeren String dargestellt.	STRING
__key__.path	Der Pfad des Dokuments: die Reihenfolge des Dokuments und der Sammlungspaare aus der Stammsammlung. Beispiel: "Country", "USA", "PostalCode", 10011, "Route", 1234	STRING