Caricamento dei dati dalle esportazioni di Firestore

BigQuery supporta il caricamento dei dati dalle esportazioni di Firestore create utilizzando il servizio di importazione ed esportazione gestito di Firestore . Il servizio di importazione ed esportazione gestito esporta i documenti Firestore in un bucket Cloud Storage. Puoi quindi caricare i dati esportati in una tabella BigQuery.

Limitazioni

Quando carichi i dati in BigQuery da un'esportazione di Firestore, tieni presente le seguenti limitazioni:

Prima di iniziare

Concedi i ruoli Identity and Access Management (IAM) che forniscono agli utenti le autorizzazioni necessarie per eseguire ogni attività descritta in questo documento.

Autorizzazioni obbligatorie

Per caricare i dati in BigQuery, devi disporre delle autorizzazioni IAM per eseguire un job di caricamento e caricare i dati nelle tabelle e nelle partizioni BigQuery. Se carichi i dati da Cloud Storage, devi disporre anche delle autorizzazioni IAM per accedere al bucket contenente i dati.

Autorizzazioni per caricare i dati in BigQuery

Per caricare i dati in una nuova tabella o partizione BigQuery o per aggiungere o sovrascrivere una tabella o partizione esistente, devi disporre delle seguenti autorizzazioni IAM:

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

Ognuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per caricare i dati in una tabella BigQuery o partizione:

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin (include l'autorizzazione bigquery.jobs.create)
  • bigquery.user (include l'autorizzazione bigquery.jobs.create)
  • bigquery.jobUser (include l'autorizzazione bigquery.jobs.create)

Inoltre, se disponi dell'autorizzazione bigquery.datasets.create, puoi creare e aggiornare le tabelle utilizzando un job di caricamento nei set di dati che crei.

Per saperne di più sui ruoli e sulle autorizzazioni IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

Autorizzazioni per caricare i dati da Cloud Storage

Per ottenere le autorizzazioni necessarie per caricare i dati da un bucket Cloud Storage, chiedi all'amministratore di concederti il ruolo IAM Storage Admin (roles/storage.admin) sul bucket. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per caricare i dati da un bucket Cloud Storage. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per caricare i dati da un bucket Cloud Storage sono necessarie le seguenti autorizzazioni:

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

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Caricamento dei dati del servizio di esportazione di Firestore

Puoi caricare i dati da un file di metadati di esportazione di Firestore utilizzando la Google Cloud console, lo strumento a riga di comando bq, or API.

A volte la terminologia di Datastore viene utilizzata nella Google Cloud console e nello strumento a riga di comando bq, ma le seguenti procedure sono compatibili con i file di esportazione di Firestore. Firestore e Datastore condividono un formato di esportazione.

Console

  1. Nella Google Cloud console, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nel riquadro a sinistra, fai clic su Spazio di esplorazione.
  3. Nel riquadro Spazio di esplorazione , espandi il progetto, fai clic su Set di dati e seleziona un set di dati.
  4. Nella sezione Informazioni sul set di dati, fai clic su Crea tabella.
  5. Nel riquadro Crea tabella, specifica i seguenti dettagli:
    1. Nella sezione Origine, seleziona Google Cloud Storage nell'elenco Crea tabella da. Quindi, procedi nel seguente modo:
      1. Seleziona un file dal bucket Cloud Storage o inserisci l'URI Cloud Storage. Non puoi includere più URI nella Google Cloud console, ma i caratteri jolly sono supportati. Il bucket Cloud Storage deve trovarsi nella stessa località del set di dati contenente la tabella che vuoi creare, aggiungere o sovrascrivere.
        L'URI del file di esportazione di Firestore deve terminare con KIND_COLLECTION_ID.export_metadata. Ad esempio, in default_namespace_kind_Book.export_metadata, Book è l'ID raccolta e default_namespace_kind_Book è il nome del file generato da Firestore. Se l'URI non termina con KIND_COLLECTION_ID.export_metadata, viene visualizzato il seguente messaggio di errore: does not contain valid backup metadata. (error code: invalid). seleziona il file di origine per creare una tabella BigQuery
      2. In Formato file, seleziona Backup di Cloud Datastore. Firestore e Datastore condividono il formato di esportazione.
    2. Nella sezione Destinazione, specifica i seguenti dettagli:
      1. In Set di dati, seleziona il set di dati in cui vuoi creare la tabella.
      2. Nel campo Tabella, inserisci il nome della tabella che vuoi creare.
      3. Verifica che il campo Tipo di tabella sia impostato su Tabella nativa.
    3. Nella sezione Schema, non è necessaria alcuna azione. Lo schema viene dedotto per un' esportazione di Firestore.
    4. (Facoltativo) Specifica le Impostazioni di partizionamento e clustering. Per saperne di più, consulta Creazione di tabelle partizionate e Creazione e utilizzo di tabelle in cluster.
    5. Fai clic su Opzioni avanzate e segui questi passaggi:
      • In Preferenza di scrittura, lascia selezionata l'opzione Scrivi se vuota. Questa opzione crea una nuova tabella e carica i dati al suo interno.
      • Se vuoi ignorare i valori in una riga che non sono presenti nello schema della tabella, allora seleziona Valori sconosciuti.
      • In Crittografia, fai clic su Chiave gestita dal cliente per utilizzare una chiave Cloud Key Management Service. Se lasci l'impostazione Google-managed key, BigQuery crittografa i dati at-rest.
    6. Fai clic su Crea tabella.

bq

Utilizza il bq load comando con source_format impostato su DATASTORE_BACKUP. Fornisci il --location flag e imposta il valore sulla tua località. Se stai sovrascrivendo una tabella esistente, aggiungi il flag --replace.

Per caricare solo campi specifici, utilizza il flag --projection_fields.

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

Sostituisci quanto segue:

  • LOCATION: la tua località. Il flag --location è facoltativo.
  • FORMAT: DATASTORE_BACKUP. Backup di Datastore è l'opzione corretta per Firestore. Firestore e Datastore condividono un formato di esportazione.
  • DATASET: il set di dati contenente la tabella in cui stai caricando i dati.
  • TABLE: la tabella in cui stai caricando i dati. Se la tabella non esiste, viene creata.
  • PATH_TO_SOURCE: l' URI Cloud Storage.

Ad esempio, il seguente comando carica il file di esportazione di Firestore gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata in una tabella denominata book_data. mybucket e mydataset sono stati creati nella località multi-regione US.

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

Imposta le seguenti proprietà per caricare i dati di esportazione di Firestore utilizzando l'API.

  1. Crea una configurazione del job load che rimandi ai dati di origine in Cloud Storage.

  2. Specifica la tua località nella location proprietà nella sezione jobReference della risorsa job.

  3. Gli sourceUris devono essere completi, nel formato gs://BUCKET/OBJECT nella configurazione del job di caricamento. Il nome del file (oggetto) deve terminare con KIND_NAME.export_metadata. È consentito un solo URI per le esportazioni di Firestore e non puoi utilizzare un carattere jolly.

  4. Specifica il formato dei dati impostando la proprietà sourceFormat su DATASTORE_BACKUP nella configurazione del job di caricamento. Backup di Datastore è l'opzione corretta per Firestore. Firestore e Datastore condividono un formato di esportazione.

  5. Per caricare solo campi specifici, imposta la proprietà projectionFields.

  6. Se stai sovrascrivendo una tabella esistente, specifica la disposizione di scrittura impostando la proprietà writeDisposition su WRITE_TRUNCATE.

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API di BigQuery.Python

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Opzioni di Firestore

Per modificare il modo in cui BigQuery analizza i dati di esportazione di Firestore, specifica la seguente opzione:

Google Cloud Opzione della console Flag `bq` Proprietà dell'API BigQuery Descrizione
Non disponibile --projection_fields projectionFields (Java, Python) (Facoltativo) Un elenco separato da virgole che indica i campi del documento da caricare da un'esportazione di Firestore. Per impostazione predefinita, BigQuery carica tutti i campi. I nomi dei campi fanno distinzione tra maiuscole e minuscole e devono essere presenti nell'esportazione. Non puoi specificare i percorsi dei campi all'interno di un campo mappa, ad esempio map.foo.

Conversione dei tipi di dati

BigQuery converte i dati di ogni documento nei file di esportazione di Firestore in tipi di dati BigQuery . La tabella seguente descrive la conversione tra i tipi di dati supportati.

Tipo di dati Firestore Tipo di dati BigQuery
Array RECORD
Booleano BOOLEANO
Riferimento RECORD
Data e ora TIMESTAMP
Mappa RECORD
Numero in virgola mobile FLOAT
Punto geografico

RECORD

[{"lat","FLOAT"},
 {"long","FLOAT"}]
Numero intero INTEGER
Stringa STRINGA (troncata a 64 KB)

Proprietà della chiave di Firestore

Ogni documento in Firestore ha una chiave univoca che contiene informazioni come l'ID e il percorso del documento. BigQuery crea un tipo di dati RECORD (noto anche come STRUCT) per la chiave, con campi nidificati per ogni informazione, come descritto nella tabella seguente.

Proprietà della chiave Descrizione Tipo di dati BigQuery
__key__.app Il nome dell'app Firestore. STRING
__key__.id L'ID del documento o null se __key__.name è impostato. INTEGER
__key__.kind L'ID raccolta del documento. STRING
__key__.name Il nome del documento o null se __key__.id è impostato. STRING
__key__.namespace Firestore non supporta gli spazi dei nomi personalizzati. Lo spazio dei nomi predefinito è rappresentato da una stringa vuota. STRING
__key__.path Il percorso del documento: la sequenza di coppie di documenti e raccolte dalla raccolta principale. Ad esempio: "Country", "USA", "PostalCode", 10011, "Route", 1234. STRING