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 Firestore-Exporte können geladen werden. Anhand der BigQuery-Einschränkungen erstellen Sie einen Firestore-Export, der in eine BigQuery-Tabelle geladen werden kann.

Beschränkungen

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

• Das Dataset muss sich am selben Speicherort 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.

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

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

In der Google 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 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 Firestore-Exportdatei muss auf KIND_COLLECTION_ID.export_metadata enden. Beispiel: In default_namespace_kind_Book.export_metadata ist Book die Sammlungs-ID und default_namespace_kind_Book der von Firestore generierte Dateiname. Wenn der URI nicht mit KIND_COLLECTION_ID.export_metadata endet, erhalten Sie die folgende Fehlermeldung: enthält keine gültigen Sicherungsmetadaten. (error code: invalid).
      Hinweis: Verwenden Sie nicht die Datei, die auf overall_export_metadata endet. Sie kann in BigQuery nicht verwendet werden.
      
   2. Wählen Sie unter File format (Dateiformat) die Option Cloud Datastore Backup (Cloud Datastore-Sicherung) aus. Firestore und Datastore verwenden dasselbe Exportformat.
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.
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. 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.

Python

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Python in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

# TODO(developer): Set table_id to the ID of the table to create.
table_id = "your-project.your_dataset.your_table_name"

# TODO(developer): Set uri to the path of the kind export metadata
uri = (
    "gs://cloud-samples-data/bigquery/us-states"
    "/2021-07-02T16:04:48_70344/all_namespaces/kind_us-states"
    "/all_namespaces_kind_us-states.export_metadata"
)

# TODO(developer): Set projection_fields to a list of document properties
#                  to import. Leave unset or set to `None` for all fields.
projection_fields = ["name", "post_abbr"]

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.DATASTORE_BACKUP,
    projection_fields=projection_fields,
)

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

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:

Option der Google Cloud Console	„bq“-Flag	BigQuery API-Attribut	Beschreibung
Nicht verfügbar	--projection_fields	projectionFields (Java, Python)	(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