Caricamento dei dati dalle esportazioni di Datastore
BigQuery supporta il caricamento dei dati dalle esportazioni di Datastore create utilizzando il servizio di importazione ed esportazione gestito di Datastore. Puoi utilizzare il servizio di importazione ed esportazione gestito per esportare le entità Datastore in un bucket Cloud Storage. Puoi quindi caricare l'esportazione in BigQuery come tabella.
Per scoprire come creare un file di esportazione Datastore, consulta Esportazione e importazione di entità nella documentazione di Datastore. Per informazioni sulla pianificazione delle esportazioni, vedi Pianificare un'esportazione.
Puoi controllare le proprietà che BigQuery deve caricare impostando
la proprietà projectionFields
nell'API o utilizzando il flag --projection_fields
nello strumento a riga di comando bq.
Se preferisci saltare il processo di caricamento, puoi eseguire query sull'esportazione direttamente configurandola come origine dati esterna. Per saperne di più, consulta Origini dati esterne.
Quando carichi i dati da Cloud Storage in una tabella BigQuery, il set di dati che contiene la tabella deve trovarsi nella stessa regione o multiregione del bucket Cloud Storage.
Limitazioni
Quando carichi i dati in BigQuery da un'esportazione di Datastore, tieni presente le seguenti limitazioni:
- Non puoi utilizzare un carattere jolly nell'URI Cloud Storage quando specifichi un file di esportazione Datastore.
- Quando carichi i dati dalle esportazioni di Datastore, puoi specificare un solo URI Cloud Storage.
- Non puoi aggiungere i dati di esportazione di Datastore a una tabella esistente con uno schema definito.
- Perché un'esportazione Datastore venga caricata correttamente, le entità nei dati di esportazione devono condividere uno schema coerente con meno di 10.000 nomi di proprietà unici.
- I dati esportati senza specificare un filtro entità non possono essere caricati in BigQuery. La richiesta di esportazione deve includere uno o più nomi di tipi nel filtro entità.
- La dimensione massima del campo per le esportazioni Datastore è 64 KB. Quando carichi un'esportazione di Datastore, qualsiasi campo più grande di 64 KB viene troncato.
Prima di iniziare
Concedi ruoli IAM (Identity and Access Management) 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 in tabelle e partizioni BigQuery. Se carichi i dati da Cloud Storage, devi disporre anche delle autorizzazioni IAM per accedere al bucket che contiene i tuoi dati.
Autorizzazioni per caricare dati in BigQuery
Per caricare i dati in una nuova tabella o partizione BigQuery oppure 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
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 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 Amministratore archiviazione (roles/storage.admin
) nel 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 Datastore
Per caricare i dati da un file di metadati di esportazione di Datastore:
Console
Nella console Google Cloud , vai alla pagina BigQuery.
- Nel riquadro Explorer, espandi il progetto e 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, procedi nel seguente modo:
- 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
posizione del set di dati che contiene la tabella che vuoi creare, aggiungere o
sovrascrivere.
L'URI del file di esportazione di Datastore deve terminare conKIND_NAME.export_metadata
oexport[NUM].export_metadata
. Ad esempio, indefault_namespace_kind_Book.export_metadata
,Book
è il nome del tipo edefault_namespace_kind_Book
è il nome del file generato da Datastore. - Per Formato file, seleziona Backup di Cloud Datastore.
- 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
posizione del set di dati che contiene la tabella che vuoi creare, aggiungere o
sovrascrivere.
- Nella sezione Destinazione, specifica i seguenti dettagli:
- Per Set di dati, seleziona il set di dati in cui vuoi creare la tabella.
- Nel campo Table (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 Datastore.
- (Facoltativo) Specifica le impostazioni di partizionamento e clustering. Per ulteriori informazioni, vedi Creazione di tabelle partizionate e Creazione e utilizzo di tabelle in cluster.
- 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 di una riga che non sono presenti nello schema della tabella, seleziona Valori sconosciuti.
- Per la crittografia, fai clic su Chiave gestita dal cliente per utilizzare una chiave Cloud Key Management Service. Se lasci l'impostazione Google-managed key, BigQuery cripta i dati at rest. Per informazioni sulle opzioni disponibili, consulta Opzioni del datastore.
- 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 posizione.
bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE
Sostituisci quanto segue:
LOCATION
: la tua posizione. Il flag--location
è facoltativo. Ad esempio, se utilizzi BigQuery nella regione di Tokyo, puoi impostare il valore del flag suasia-northeast1
. Puoi impostare un valore predefinito per la località utilizzando il file.bigqueryrc.FORMAT
:DATASTORE_BACKUP
.DATASET
: il set di dati che contiene la tabella in cui carichi i dati.TABLE
: la tabella in cui carichi i dati. Se la tabella non esiste, viene creata.PATH_TO_SOURCE
: l'URI Cloud Storage.
Ad esempio, il seguente comando carica il
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata
file di esportazione Datastore in una tabella denominata book_data
.
mybucket
e mydataset
sono stati creati nella località multiregionale 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 Datastore utilizzando l'API.
Crea un job di caricamento che rimanda ai dati di origine in Cloud Storage.
Specifica la località nella proprietà
location
della sezionejobReference
della risorsa di lavoro.Gli URI di origine devono essere completi, nel formato gs://[BUCKET]/[OBJECT]. Il nome del file (oggetto) deve terminare con
[KIND_NAME].export_metadata
. È consentito un solo URI per le esportazioni Datastore e non puoi utilizzare un carattere jolly.Specifica il formato dei dati impostando la proprietà
JobConfigurationLoad.sourceFormat
suDATASTORE_BACKUP
.
Aggiunta o sovrascrittura di una tabella con dati Datastore
Quando carichi i dati di esportazione di Datastore in BigQuery, puoi creare una nuova tabella per archiviarli oppure puoi sovrascrivere una tabella esistente. Non puoi aggiungere i dati di esportazione di Datastore a una tabella esistente.
Se tenti di aggiungere dati di esportazione di Datastore a una tabella esistente, viene visualizzato il seguente errore: Cannot append a datastore backup to a table
that already has a schema. Try using the WRITE_TRUNCATE write disposition to
replace the existing table
.
Per sovrascrivere una tabella esistente con i dati di esportazione di Datastore:
Console
Nella console Google Cloud , vai alla pagina BigQuery.
- Nel riquadro Explorer, espandi il progetto e 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, procedi nel seguente modo:
- 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
posizione del set di dati che contiene la tabella che vuoi creare, aggiungere o
sovrascrivere.
L'URI del file di esportazione di Datastore deve terminare conKIND_NAME.export_metadata
oexport[NUM].export_metadata
. Ad esempio, indefault_namespace_kind_Book.export_metadata
,Book
è il nome del tipo edefault_namespace_kind_Book
è il nome del file generato da Datastore. - Per Formato file, seleziona Backup di Cloud Datastore.
- 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
posizione del set di dati che contiene la tabella che vuoi creare, aggiungere o
sovrascrivere.
- Nella sezione Destinazione, specifica i seguenti dettagli:
- Per Set di dati, seleziona il set di dati in cui vuoi creare la tabella.
- Nel campo Table (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 Datastore.
- (Facoltativo) Specifica le impostazioni di partizionamento e clustering. Per ulteriori informazioni, vedi Creazione di tabelle partizionate e Creazione e utilizzo di tabelle in cluster. Non puoi convertire una tabella in una tabella partizionata o in cluster aggiungendola o sovrascrivendola. La console Google Cloud non supporta l'aggiunta o la sovrascrittura di tabelle partizionate o in cluster in un job di caricamento.
- Fai clic su Opzioni avanzate e segui questi passaggi:
- In Preferenza di scrittura, scegli Aggiungi alla tabella o Sovrascrivi tabella.
- Se vuoi ignorare i valori di una riga che non sono presenti nello schema della tabella, seleziona Valori sconosciuti.
- Per la crittografia, fai clic su Chiave gestita dal cliente per utilizzare una chiave Cloud Key Management Service. Se lasci l'impostazione Google-managed key, BigQuery cripta i dati at rest. Per informazioni sulle opzioni disponibili, consulta Opzioni del datastore.
- Fai clic su Crea tabella.
bq
Utilizza il comando bq load
con il flag --replace
e con source_format
impostato su DATASTORE_BACKUP
. Fornisci il flag --location
e imposta il valore sulla tua posizione.
bq --location=LOCATION load \
--source_format=FORMAT \
--replace \
DATASET.TABLE \
PATH_TO_SOURCE
Sostituisci quanto segue:
LOCATION
: la tua posizione. Il flag--location
è facoltativo. Ad esempio, se utilizzi BigQuery nella regione di Tokyo, puoi impostare il valore del flag suasia-northeast1
. Puoi impostare un valore predefinito per la località utilizzando il file.bigqueryrc.FORMAT
:DATASTORE_BACKUP
.DATASET
: il set di dati contenente la tabella in cui carichi i dati.TABLE
: la tabella che stai sovrascrivendo.PATH_TO_SOURCE
: l'URI Cloud Storage.
Ad esempio, il seguente comando carica il
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata
file di esportazione Datastore e sovrascrive una tabella denominata
book_data
:
bq load --source_format=DATASTORE_BACKUP \
--replace \
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 dall'API.
Crea un job di caricamento che rimanda ai dati di origine in Cloud Storage.
Specifica la località nella proprietà
location
della sezionejobReference
della risorsa di lavoro.Gli URI di origine devono essere completi, nel formato gs://[BUCKET]/[OBJECT]. Il nome del file (oggetto) deve terminare con
[KIND_NAME].export_metadata
. È consentito un solo URI per le esportazioni Datastore e non puoi utilizzare un carattere jolly.Specifica il formato dei dati impostando la proprietà
JobConfigurationLoad.sourceFormat
suDATASTORE_BACKUP
.Specifica la disposizione scrittura impostando la proprietà
JobConfigurationLoad.writeDisposition
suWRITE_TRUNCATE
.
Opzioni Datastore
Per modificare il modo in cui BigQuery analizza i dati di esportazione di Datastore, specifica l'opzione seguente:
Opzione della console | Flag dello strumento bq | Proprietà API BigQuery | Descrizione |
---|---|---|---|
Non disponibile | --projection_fields |
projectionFields | Un elenco separato da virgole che indica quali proprietà dell'entità caricare in BigQuery da un'esportazione di Datastore. I nomi delle proprietà sono sensibili alle maiuscole e devono essere proprietà di primo livello. Se non vengono specificate proprietà, BigQuery carica tutte le proprietà. Se non viene trovata alcuna proprietà denominata nell'esportazione di Datastore, nel risultato del job viene restituito un errore non valido. Il valore predefinito è "". |
Conversione del tipo di dati
BigQuery converte i dati di ogni entità nei file di esportazione Datastore nei tipi di dati BigQuery. La tabella seguente descrive la conversione tra i tipi di dati.
Tipo di dati del datastore | Tipo di dati BigQuery |
---|---|
Array | ARRAY |
Blob | BYTES |
Booleano | BOOLEAN |
Data e ora | TIMESTAMP |
Entità incorporata | RECORD |
Numero in virgola mobile | FLOAT |
Punto geografico |
[{"lat","DOUBLE"}, {"long","DOUBLE"}] |
Numero intero | INTEGER |
Chiave | RECORD |
Null | STRING |
Stringa di testo | STRING (troncato a 64 KB) |
Proprietà chiave di Datastore
Ogni entità in Datastore ha una chiave univoca che contiene
informazioni come lo spazio dei nomi e il percorso. BigQuery crea
un tipo di dati RECORD
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 Datastore. | STRING |
__key__.id |
L'ID dell'entità o null se __key__.name è
impostato. |
INTEGER |
__key__.kind |
Il tipo di entità. | STRING |
__key__.name |
Il nome dell'entità o null se __key__.id è
impostato. |
STRING |
__key__.namespace |
Se l'app Datastore utilizza uno spazio dei nomi personalizzato, lo spazio dei nomi dell'entità. Altrimenti, lo spazio dei nomi predefinito è rappresentato da una stringa vuota. | STRING |
__key__.path |
Il percorso ancestrale dell'entità appiattito,
costituito dalla sequenza di coppie tipo-identificatore dall'entità base
all'entità stessa. Ad esempio: "Country", "USA", "PostalCode",
10011, "Route", 1234 . |
STRING |