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.

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

Console

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

    BigQuery aufrufen

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

  3. Maximieren Sie die Option Aktionen und klicken Sie auf Öffnen.

  4. Klicken Sie im Detailfeld auf Tabelle erstellen.

  5. Gehen Sie auf der Seite Tabelle erstellen im Bereich 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 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.

      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 als Dateiformat aus. Dies ist die geeignete Option für Firestore. Firestore und Datastore verwenden dasselbe Exportformat.

  6. Gehen Sie auf der Seite Tabelle erstellen im Abschnitt Ziel folgendermaßen 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.

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

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

    Tabelle überschreiben

  9. 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 ausprobieren, folgen Sie den Schritten zur Einrichtung von Python in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur  Python API.

# 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))

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 (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