Caricamento dei dati dalle esportazioni di Firestore
BigQuery supporta il caricamento dei dati dalle esportazioni di Firestore create utilizzando il servizio gestito di importazione ed esportazione di Firestore. Il servizio gestito di importazione ed esportazione esporta i documenti Firestore in un bucket Cloud Storage. Puoi quindi caricare i dati esportati in una tabella BigQuery.
Limitazioni
Quando carichi dati in BigQuery da un'esportazione Firestore, tieni presente le seguenti restrizioni:
- Il set di dati deve trovarsi nella stessa località del bucket Cloud Storage contenente i file di esportazione.
- Puoi specificare un solo URI Cloud Storage e non puoi utilizzare un carattere jolly URI.
- Affinché un'esportazione Firestore venga caricata correttamente, i documenti nei dati dell'esportazione devono condividere uno schema coerente con meno di 10.000 nomi di campi univoci.
- Puoi creare una nuova tabella per archiviare i dati o sovrascrivere una tabella esistente. Non puoi aggiungere dati delle esportazioni Firestore a una tabella esistente.
- Il comando di esportazione
deve specificare un filtro
collection-ids
. I dati esportati senza specificare un filtro ID raccolta non possono essere caricati in BigQuery.
Prima di iniziare
Concedi i ruoli IAM (Identity and Access Management) che concedono agli utenti le autorizzazioni necessarie per eseguire ogni attività nel documento.
Autorizzazioni obbligatorie
Per caricare dati in BigQuery, devi disporre delle autorizzazioni IAM per eseguire un job di caricamento e caricare i dati in tabelle e partizioni BigQuery. Se stai caricando i dati da Cloud Storage, devi avere anche le autorizzazioni IAM per accedere al bucket che contiene i tuoi dati.
Autorizzazioni per caricare i dati in BigQuery
Per caricare i dati in una nuova tabella o partizione BigQuery oppure per aggiungere o sovrascrivere una tabella o una partizione esistente, devi disporre delle seguenti autorizzazioni IAM:
bigquery.tables.create
bigquery.tables.updateData
bigquery.tables.update
bigquery.jobs.create
Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per caricare i dati in una tabella o partizione BigQuery:
roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin
(include l'autorizzazionebigquery.jobs.create
)bigquery.user
(include l'autorizzazionebigquery.jobs.create
)bigquery.jobUser
(include l'autorizzazionebigquery.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 ulteriori informazioni su ruoli e autorizzazioni IAM in BigQuery, consulta Autorizzazioni e ruoli 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
Amministratore Storage (roles/storage.admin
) per il bucket.
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.
Questo ruolo predefinito contiene le autorizzazioni necessarie per caricare i dati da un bucket Cloud Storage. Per visualizzare le autorizzazioni esatte necessarie, espandi la sezione Autorizzazioni richieste:
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 essere in grado di ottenere queste autorizzazioni con i 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 Firestore utilizzando la console Google Cloud, lo strumento a riga di comando bq o l'API.
A volte nella console Google Cloud e nello strumento a riga di comando bq viene utilizzata la terminologia Datastore, tuttavia le procedure che seguono sono compatibili con i file di esportazione di Firestore. Firestore e Datastore condividono un formato di esportazione.
Console
Nella console Google Cloud, vai alla pagina BigQuery.
- Nel riquadro Explorer, espandi il progetto, quindi seleziona un set di dati.
- Nella sezione Informazioni sul set di dati, fai clic su Crea tabella.
- Nel riquadro Crea tabella, specifica i seguenti dettagli:
- Nella sezione Origine, seleziona Google Cloud Storage nell'elenco Crea tabella da.
Poi esegui le seguenti operazioni:
- Seleziona un file dal bucket Cloud Storage o inserisci l'URI Cloud Storage.
Non puoi includere più URI nella console Google Cloud, ma sono supportati i caratteri jolly. Il bucket Cloud Storage deve trovarsi nella stessa località del set di dati contenente la tabella da creare, aggiungere o sovrascrivere.
L'URI del file di esportazione Firestore deve terminare conKIND_COLLECTION_ID.export_metadata
. Ad esempio, indefault_namespace_kind_Book.export_metadata
,Book
è l'ID raccolta edefault_namespace_kind_Book
è il nome del file generato da Firestore. Se l'URI non termina conKIND_COLLECTION_ID.export_metadata
, viene visualizzato il seguente messaggio di errore: non contiene metadati di backup validi. (codice di errore: non valido). - In Formato file, seleziona Backup di Cloud Datastore. Firestore e Datastore condividono il formato di esportazione.
- Seleziona un file dal bucket Cloud Storage o inserisci l'URI Cloud Storage.
Non puoi includere più URI nella console Google Cloud, ma sono supportati i caratteri jolly. Il bucket Cloud Storage deve trovarsi nella stessa località del set di dati contenente la tabella da creare, aggiungere o sovrascrivere.
- Nella sezione Destinazione, specifica i seguenti dettagli:
- In Set di dati, seleziona il set di dati in cui vuoi creare la tabella.
- Nel campo Tabella, inserisci il nome della tabella che vuoi creare.
- Verifica che il campo Tipo di tabella sia impostato su Tabella nativa.
- Nella sezione Schema non è necessaria alcuna azione. Lo schema viene dedotto per un'esportazione di Firestore.
- (Facoltativo) Specifica le impostazioni di partizione e cluster. Per saperne di più, consulta Creazione di tabelle partizionate e Creazione e utilizzo delle tabelle in cluster.
- Fai clic su Opzioni avanzate ed esegui le seguenti operazioni:
- In Preferenza di scrittura, lascia selezionata l'opzione Scrivi se vuoto. Questa opzione consente di creare una nuova tabella in cui caricare i dati.
- Se in una riga vuoi ignorare i valori che non sono presenti nello schema della tabella, seleziona Valori sconosciuti.
- In Crittografia, fai clic su Chiave gestita dal cliente per utilizzare una chiave Cloud Key Management Service. Se lasci l'impostazione Chiave gestita da Google, BigQuery cripta i dati at-rest.
- Fai clic su Crea tabella.
bq
Utilizza il comando bq load
con source_format
impostato su DATASTORE_BACKUP
.
Fornisci il flag --location
e imposta il valore sulla tua
località. Se stai eseguendo la sovrascrittura di 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 posizione. 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 vengono caricati 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 comando seguente carica il
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata
file di esportazione di Firestore in una tabella denominata book_data
.
mybucket
e mydataset
sono stati creati nella località a più regioni 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 proprietà seguenti per caricare i dati delle esportazioni di Firestore utilizzando l'API.
Crea una configurazione del job
load
che punta ai dati di origine in Cloud Storage.Specifica la tua località nella proprietà
location
nella sezionejobReference
della risorsa offerta di lavoro.L'elemento
sourceUris
deve essere completo, nel formatogs://BUCKET/OBJECT
nella configurazione del job di caricamento. Il nome del file (oggetto) deve terminare conKIND_NAME.export_metadata
. È consentito un solo URI per le esportazioni di Firestore e non è possibile utilizzare un carattere jolly.Specifica il formato dei dati impostando la proprietà
sourceFormat
suDATASTORE_BACKUP
nella configurazione del job di caricamento. Backup di Datastore è l'opzione corretta per Firestore. Firestore e Datastore condividono un formato di esportazione.Per caricare solo campi specifici, imposta la proprietà
projectionFields
.Se sovrascrivi una tabella esistente, specifica la disposizione di scrittura impostando la proprietà
writeDisposition
suWRITE_TRUNCATE
.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Opzioni di Firestore
Per cambiare il modo in cui BigQuery analizza i dati delle esportazioni di Firestore, specifica la seguente opzione:
Opzione della console Google Cloud | flag "bq" | Proprietà API BigQuery | Descrizione |
---|---|---|---|
Non disponibile | --projection_fields |
projectionFields
(Java,
Python) |
(Facoltativo) Un elenco separato da virgole che indica quali campi dei documenti caricare da un'esportazione di Firestore. Per impostazione predefinita, BigQuery carica tutti i campi. I nomi dei campi sono sensibili alle maiuscole e devono essere presenti nell'esportazione. Non puoi specificare i percorsi dei campi all'interno di un campo della mappa come map.foo .
|
Conversione del tipo di dati
BigQuery converte i dati di ogni documento presente 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 con virgola mobile | FLOAT |
Punto geografico |
RECORD [{"lat","FLOAT"}, {"long","FLOAT"}] |
Numero intero | INTEGER |
Stringa | STRING (troncato a 64 kB) |
Proprietà chiave Firestore
Ogni documento in Firestore ha una chiave univoca contenente
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 è impostato __key__.id . |
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 del documento e le coppie di raccolte dalla raccolta principale. Ad esempio: "Country",
"USA", "PostalCode", 10011, "Route", 1234 . |
STRING |