Scrittura dei risultati delle query
Questo documento descrive come scrivere i risultati delle query in tabelle temporanee o permanenti.
Tabelle temporanee e permanenti
BigQuery salva tutti i risultati delle query in una tabella, che può essere permanente o temporanea.
BigQuery utilizza tabelle temporanee per memorizzare nella cache i risultati delle query che non vengono scritti in una tabella permanente. Le tabelle vengono create in un set di dati speciale e denominate in modo casuale. Puoi anche creare tabelle temporanee per uso personale all'interno di query con più istruzioni e sessioni. Non vengono addebitati costi per le tabelle temporanee dei risultati delle query memorizzati nella cache. Ti vengono addebitati costi per le tabelle temporanee che non sono risultati della query memorizzati nella cache.
Al termine di una query, la tabella temporanea esiste per un massimo di 24 ore. Per visualizzare la struttura e i dati della tabella, vai alla console BigQuery, fai clic su Cronologia personale e scegli la query che ha creato la tabella temporanea. Quindi, nella riga Tabella di destinazione, fai clic su Tabella temporanea.
L'accesso ai dati della tabella temporanea è limitato all'utente o al service account che ha creato il job di query.
Non puoi condividere le tabelle temporanee e non sono visibili utilizzando nessuno dei metodi standard di elenco o di manipolazione delle tabelle. Le tabelle temporanee vengono create nella stessa regione della tabella o delle tabelle sottoposte a query.
Una tabella permanente può essere una tabella nuova o esistente in qualsiasi set di dati a cui hai accesso. Se scrivi i risultati della query in una nuova tabella, ti viene addebitato il costo di archiviazione dei dati. Quando scrivi i risultati della query in una tabella permanente, le tabelle su cui esegui query devono trovarsi nella stessa località del set di dati che contiene la tabella di destinazione.
Non puoi salvare i risultati della query in una tabella temporanea quando sono attivi i criteri dell'organizzazione con limitazioni del dominio. Come soluzione alternativa, disattiva temporaneamente il criterio dell'organizzazione con restrizioni del dominio, esegui la query e poi riattiva il criterio. In alternativa, puoi salvare i risultati della query in una tabella di destinazione.
Autorizzazioni obbligatorie
Come minimo, per scrivere i risultati della query in una tabella, devi disporre delle seguenti autorizzazioni:
- Autorizzazioni
bigquery.tables.create
per creare una nuova tabella bigquery.tables.updateData
per scrivere i dati in una nuova tabella, sovrascrivere una tabella o aggiungere dati a una tabellabigquery.jobs.create
per eseguire un job di query
Per accedere ai dati su cui stai eseguendo una query, potrebbero essere necessarie autorizzazioni aggiuntive, ad esempio bigquery.tables.getData
.
I seguenti ruoli IAM predefiniti includono le autorizzazioni
bigquery.tables.create
e bigquery.tables.updateData
:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
I seguenti ruoli IAM predefiniti includono le autorizzazioni bigquery.jobs.create
:
bigquery.user
bigquery.jobUser
bigquery.admin
Inoltre, se un utente dispone delle autorizzazioni bigquery.datasets.create
, quando crea un set di dati, gli viene concesso l'accesso bigquery.dataOwner
.
L'accesso bigquery.dataOwner
consente all'utente di creare e aggiornare tabelle nel set di dati.
Per saperne di più sui ruoli e sulle autorizzazioni IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.
Scrivere i risultati della query in una tabella permanente
Quando scrivi i risultati della query in una tabella permanente, puoi creare una nuova tabella, aggiungere i risultati a una tabella esistente o sovrascrivere una tabella esistente.
Scrittura dei risultati delle query
Utilizza la seguente procedura per scrivere i risultati della query in una tabella permanente. Per controllare i costi, puoi visualizzare l'anteprima dei dati prima di eseguire la query.
Console
Apri la pagina BigQuery nella console Google Cloud .
Nel riquadro Spazio di esplorazione, espandi il progetto e seleziona un set di dati.
Inserisci una query SQL valida.
Fai clic su Altro e poi seleziona Impostazioni query.
Seleziona l'opzione Imposta una tabella di destinazione per i risultati della query.
Nella sezione Destinazione, seleziona il set di dati in cui vuoi creare la tabella, quindi scegli un ID tabella.
Nella sezione Preferenza di scrittura per tabella di destinazione, scegli una delle seguenti opzioni:
- Scrivi se vuota: scrive i risultati della query nella tabella solo se la tabella è vuota.
- Aggiungi alla tabella: aggiunge i risultati della query a una tabella esistente.
- Sovrascrivi tabella: sovrascrive una tabella esistente con lo stesso nome utilizzando i risultati della query.
(Facoltativo) Per Località dei dati, scegli la tua località.
Per aggiornare le impostazioni della query, fai clic su Salva.
Fai clic su Esegui. Viene creato un job di query che scrive i risultati della query nella tabella specificata.
In alternativa, se dimentichi di specificare una tabella di destinazione prima di eseguire la query, puoi copiare la tabella dei risultati memorizzati nella cache in una tabella permanente facendo clic sul pulsante Salva risultati sopra l'editor.
SQL
L'esempio seguente utilizza l'istruzione CREATE TABLE
per creare la tabella trips
dai dati della tabella pubblica bikeshare_trips
:
Nella console Google Cloud , vai alla pagina BigQuery.
Nell'editor di query, inserisci la seguente istruzione:
CREATE TABLE mydataset.trips AS ( SELECT bike_id, start_time, duration_minutes FROM bigquery-public-data.austin_bikeshare.bikeshare_trips );
Fai clic su
Esegui.
Per maggiori informazioni su come eseguire le query, consulta Eseguire una query interattiva.
Per ulteriori informazioni, vedi Creare una nuova tabella da una tabella esistente.
bq
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Inserisci il comando
bq query
e specifica il flag--destination_table
per creare una tabella permanente in base ai risultati della query. Specifica il flaguse_legacy_sql=false
per utilizzare la sintassi GoogleSQL. Per scrivere i risultati della query in una tabella che non si trova nel tuo progetto predefinito, aggiungi l'ID progetto al nome del set di dati nel seguente formato:project_id:dataset
.(Facoltativo) Fornisci il flag
--location
e imposta il valore sulla tua posizione.Per controllare l'istruzione di scrittura per una tabella di destinazione esistente, specifica uno dei seguenti flag facoltativi:
--append_table
: se la tabella di destinazione esiste, i risultati della query vengono aggiunti.--replace
: se la tabella di destinazione esiste, viene sovrascritta con i risultati della query.bq --location=location query \ --destination_table project_id:dataset.table \ --use_legacy_sql=false 'query'
Sostituisci quanto segue:
location
è il nome della località utilizzata per elaborare la query. 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 posizione utilizzando il file.bigqueryrc
.project_id
è l'ID progetto.dataset
è il nome del set di dati che contiene la tabella in cui stai scrivendo i risultati della query.table
è il nome della tabella in cui vengono scritti i risultati della query.query
è una query nella sintassi GoogleSQL.Se non viene specificato alcun flag di disposizione di scrittura, il comportamento predefinito è scrivere i risultati nella tabella solo se è vuota. Se la tabella esiste e non è vuota, viene restituito il seguente errore:
BigQuery error in query operation: Error processing job project_id:bqjob_123abc456789_00000e1234f_1: Already Exists: Table project_id:dataset.table
.Esempi:
Inserisci il comando seguente per scrivere i risultati della query in una tabella di destinazione denominata
mytable
inmydataset
. Il set di dati si trova nel tuo progetto predefinito. Poiché nel comando non è specificato alcun flag di disposizione di scrittura, la tabella deve essere nuova o vuota. In caso contrario, viene restituito un erroreAlready exists
. La query recupera i dati dal set di dati pubblico USA Name Data.bq query \ --destination_table mydataset.mytable \ --use_legacy_sql=false \ 'SELECT name, number FROM `bigquery-public-data`.usa_names.usa_1910_current WHERE gender = "M" ORDER BY number DESC'
Inserisci il seguente comando per utilizzare i risultati della query per sovrascrivere una tabella di destinazione denominata
mytable
inmydataset
. Il set di dati si trova nel tuo progetto predefinito. Il comando utilizza il flag--replace
per sovrascrivere la tabella di destinazione.bq query \ --destination_table mydataset.mytable \ --replace \ --use_legacy_sql=false \ 'SELECT name, number FROM `bigquery-public-data`.usa_names.usa_1910_current WHERE gender = "M" ORDER BY number DESC'
Inserisci il comando seguente per aggiungere i risultati della query a una tabella di destinazione denominata
mytable
inmydataset
. Il set di dati si trova inmy-other-project
, non nel tuo progetto predefinito. Il comando utilizza il flag--append_table
per aggiungere i risultati della query alla tabella di destinazione.bq query \ --append_table \ --use_legacy_sql=false \ --destination_table my-other-project:mydataset.mytable \ 'SELECT name, number FROM `bigquery-public-data`.usa_names.usa_1910_current WHERE gender = "M" ORDER BY number DESC'
L'output di ciascuno di questi esempi è simile al seguente. Per leggibilità, alcuni output sono troncati.
Waiting on bqjob_r123abc456_000001234567_1 ... (2s) Current status: DONE +---------+--------+ | name | number | +---------+--------+ | Robert | 10021 | | John | 9636 | | Robert | 9297 | | ... | +---------+--------+
API
Per salvare i risultati della query in una tabella permanente, chiama il metodo jobs.insert
, configura un job query
e includi un valore per la proprietà destinationTable
. Per controllare la disposizione di scrittura per una tabella di destinazione esistente, configura la proprietà writeDisposition
.
Per controllare la località di elaborazione del job di query, specifica la proprietà location
nella sezione jobReference
della risorsa job.
Vai
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Go.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Per salvare i risultati della query in una tabella permanente, imposta la tabella di destinazione sull'TableId desiderato in una QueryJobConfiguration.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
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 ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Per salvare i risultati della query in una tabella permanente, crea un QueryJobConfig e imposta la destinazione sul TableReference desiderato. Trasferisci la configurazione del job al metodo query.Scrivere risultati di query di grandi dimensioni
Normalmente, le query hanno una dimensione massima della risposta. Se prevedi di eseguire una query che potrebbe restituire risultati più grandi, puoi procedere in uno dei seguenti modi:
- In GoogleSQL, specifica una tabella di destinazione per i risultati della query.
- In SQL precedente, specifica una tabella di destinazione e imposta l'opzione
allowLargeResults
.
Quando specifichi una tabella di destinazione per i risultati di query di grandi dimensioni, ti viene addebitato il costo per l'archiviazione dei dati.
Limitazioni
In SQL precedente, la scrittura di risultati di grandi dimensioni è soggetta a queste limitazioni:
- Devi specificare una tabella di destinazione.
- Non puoi specificare una clausola
ORDER BY
,TOP
oLIMIT
di primo livello. In questo modo si annulla il vantaggio dell'utilizzo diallowLargeResults
, perché l'output della query non può più essere calcolato in parallelo. - Le funzioni finestra possono restituire
risultati di query di grandi dimensioni solo se utilizzate insieme a una clausola
PARTITION BY
.
Scrittura di risultati di grandi dimensioni utilizzando SQL precedente
Per scrivere set di risultati di grandi dimensioni utilizzando SQL precedente:
Console
Nella console Google Cloud , apri la pagina BigQuery.
Fai clic su Crea nuova query.
Inserisci una query SQL valida nell'area di testo Editor query. Utilizza il prefisso
#legacySQL
o assicurati di aver selezionato Utilizza SQL precedente nelle impostazioni della query.Fai clic su Altro e poi seleziona Impostazioni query.
Per Destinazione, seleziona Imposta una tabella di destinazione per i risultati della query.
Per Set di dati, scegli il set di dati in cui verrà archiviata la tabella.
Nel campo ID tabella, inserisci un nome di tabella.
Se stai scrivendo un set di risultati di grandi dimensioni in una tabella esistente, puoi utilizzare le opzioni Preferenza di scrittura per tabella di destinazione per controllare la disposizione di scrittura della tabella di destinazione:
- Scrivi se vuota:scrive i risultati della query nella tabella solo se la tabella è vuota.
- Aggiungi alla tabella:aggiunge i risultati della query a una tabella esistente.
- Sovrascrivi tabella:sovrascrive una tabella esistente con lo stesso nome utilizzando i risultati della query.
Per Dimensioni risultati, seleziona Consenti risultati di grandi dimensioni (nessun limite di dimensione).
(Facoltativo) Per Località dei dati, scegli la posizione dei tuoi dati.
Fai clic su Salva per aggiornare le impostazioni della query.
Fai clic su Esegui. Viene creato un job di query che scrive il set di risultati di grandi dimensioni nella tabella specificata.
bq
Utilizza il flag --allow_large_results
con il flag --destination_table
per
creare una tabella di destinazione per contenere il set di risultati di grandi dimensioni. Poiché l'opzione
--allow_large_results
si applica solo a SQL precedente, devi anche
specificare il flag --use_legacy_sql=true
. Per scrivere i risultati della query in una tabella che non si trova nel tuo progetto predefinito, aggiungi l'ID progetto al nome del set di dati nel seguente formato: PROJECT_ID:DATASET
.
Fornisci il flag --location
e imposta il valore sulla tua
posizione.
Per controllare la disposizione di scrittura per una tabella di destinazione esistente, specifica uno dei seguenti flag facoltativi:
--append_table
: se la tabella di destinazione esiste, i risultati della query vengono aggiunti.--replace
: se la tabella di destinazione esiste, viene sovrascritta con i risultati della query.
bq --location=location query \ --destination_table PROJECT_ID:DATASET.TABLE \ --use_legacy_sql=true \ --allow_large_results "QUERY"
Sostituisci quanto segue:
LOCATION
è il nome della località utilizzata per elaborare la query. 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 posizione utilizzando il file.bigqueryrc
.PROJECT_ID
è l'ID progetto.DATASET
è il nome del set di dati che contiene la tabella in cui stai scrivendo i risultati della query.TABLE
è il nome della tabella in cui vengono scritti i risultati della query.QUERY
è una query nella sintassi SQL precedente.
Esempi:
Inserisci il seguente comando per scrivere i risultati di query di grandi dimensioni in una tabella di destinazione denominata mytable
in mydataset
. Il set di dati si trova nel tuo progetto
predefinito. Poiché nel comando non è specificato alcun flag di disposizione di scrittura, la
tabella deve essere nuova o vuota. In caso contrario, viene restituito un errore Already exists
. La query recupera i dati dal set di dati pubblico Dati relativi ai nomi USA.
Questa query viene utilizzata solo a scopo esemplificativo. Il set di risultati restituito non
supera le dimensioni massime della risposta.
bq query \
--destination_table mydataset.mytable \
--use_legacy_sql=true \
--allow_large_results \
"SELECT
name,
number
FROM
[bigquery-public-data:usa_names.usa_1910_current]
WHERE
gender = 'M'
ORDER BY
number DESC"
Inserisci il seguente comando per utilizzare i risultati di query di grandi dimensioni per sovrascrivere una
tabella di destinazione denominata mytable
in mydataset
. Il set di dati si trova in
myotherproject
, non nel tuo progetto predefinito. Il comando utilizza il flag --replace
per sovrascrivere la tabella di destinazione.
bq query \
--destination_table mydataset.mytable \
--replace \
--use_legacy_sql=true \
--allow_large_results \
"SELECT
name,
number
FROM
[bigquery-public-data:usa_names.usa_1910_current]
WHERE
gender = 'M'
ORDER BY
number DESC"
Inserisci il seguente comando per aggiungere i risultati di query di grandi dimensioni a una tabella di destinazione denominata mytable
in mydataset
. Il set di dati si trova in myotherproject
,
non nel tuo progetto predefinito. Il comando utilizza il flag --append_table
per
aggiungere i risultati della query alla tabella di destinazione.
bq query \
--destination_table myotherproject:mydataset.mytable \
--append_table \
--use_legacy_sql=true \
--allow_large_results \
"SELECT
name,
number
FROM
[bigquery-public-data:usa_names.usa_1910_current]
WHERE
gender = 'M'
ORDER BY
number DESC"
API
Per scrivere risultati di grandi dimensioni in una tabella di destinazione, chiama il metodo
jobs.insert
, configura un job query
e imposta la proprietà allowLargeResults
su true
.
Specifica la tabella di destinazione utilizzando la proprietà destinationTable
. Per
controllare la disposizione di scrittura per una tabella di destinazione esistente, configura
la proprietà writeDisposition
.
Specifica la tua posizione nella proprietà location
nella sezione
jobReference
della risorsa job.
Vai
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Go.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Java
Per abilitare i risultati di grandi dimensioni, imposta allow large
results
su true
e imposta destination
table
sull'TableId
desiderato
in una
QueryJobConfiguration.
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
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 ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Download e salvataggio dei risultati delle query dalla console Google Cloud
Dopo aver eseguito una query SQL utilizzando la console Google Cloud , puoi salvare i risultati in un'altra posizione. Puoi utilizzare la console Google Cloud per scaricare i risultati delle query in un file locale, Fogli Google o Google Drive. Se prima ordini i risultati della query per colonna, l'ordine viene mantenuto nei dati scaricati. Il salvataggio dei risultati in un file locale, in Fogli Google o in Google Drive non è supportato dallo strumento a riga di comando bq o dall'API.
Limitazioni
Il download e il salvataggio dei risultati delle query sono soggetti alle seguenti limitazioni:
- Puoi scaricare i risultati delle query localmente solo in formato CSV o JSON delimitato da nuova riga.
- Non puoi salvare i risultati delle query contenenti dati nidificati e ripetuti in Fogli Google.
- Per salvare i risultati della query su Google Drive utilizzando la console Google Cloud , il set di risultati deve essere di 1 GB o meno. Se i risultati sono più grandi, puoi salvarli in una tabella.
- Quando salvi i risultati della query in un file CSV locale, le dimensioni massime del download sono
10 MB.
Le dimensioni massime del download si basano sulle dimensioni di ogni riga restituita nella risposta del metodo
tabledata.list
e possono variare in base allo schema dei risultati della query. Di conseguenza, le dimensioni del file CSV scaricato possono variare e potrebbero essere inferiori al limite massimo di download. - Puoi salvare i risultati delle query su Google Drive solo in formato CSV o JSON delimitato da nuova riga.
Passaggi successivi
- Scopri come esportare una tabella in un file JSON in modo programmatico.
- Scopri di più sulle quote per i job di query.
- Scopri di più sui prezzi di archiviazione di BigQuery.