Esplora lo strumento a riga di comando bq
Lo strumento a riga di comando bq è uno strumento a riga di comando basato su Python per BigQuery. Questa pagina contiene informazioni generali sull'uso dello strumento a riga di comando bq.
Per un riferimento completo di tutti i comandi e i flag bq
, consulta il riferimento dello strumento a riga di comando bq.
Prima di iniziare
Prima di poter utilizzare lo strumento a riga di comando bq, devi utilizzare la console Google Cloud per creare o selezionare un progetto.
- Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.
-
Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.
-
Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.
- BigQuery viene abilitato automaticamente nei nuovi progetti.
Per attivare BigQuery in un progetto preesistente, vai a
Attiva l'API BigQuery.
- (Facoltativo) Abilita la fatturazione per il progetto. Se non vuoi abilitare la fatturazione o fornire una carta di credito, i passaggi descritti in questo documento continueranno a funzionare. BigQuery fornisce una sandbox per eseguire i passaggi. Per maggiori informazioni, consulta Attivare la sandbox di BigQuery.
Inserimento dei comandi bq
in Cloud Shell
Puoi inserire i comandi dello strumento a riga di comando bq in Cloud Shell dalla console Google Cloud o da Google Cloud CLI.
Per utilizzare lo strumento a riga di comando bq dalla console Google Cloud, attiva Cloud Shell:
Per utilizzare lo strumento a riga di comando bq da gcloud CLI, installa e configura gcloud CLI.
Posizionamento di flag e argomenti
Lo strumento a riga di comando bq supporta due tipi di flag:
- È possibile utilizzare i flag globali in tutti i comandi.
- I flag specifici del comando si applicano a un comando specifico.
Per un elenco dei flag globali e specifici del comando, consulta la documentazione di riferimento dello strumento a riga di comando bq.
Posiziona eventuali flag globali prima del comando bq
, quindi includi flag specifici del comando. Puoi includere più flag globali
o specifici del comando. Ad esempio:
bq --location=us mk --reservation --project_id=project reservation_name
Puoi specificare gli argomenti dei comandi nei seguenti modi:
--FLAG ARGUMENT
(come mostrato negli esempi precedenti)--FLAG=ARGUMENT
--FLAG='ARGUMENT'
--FLAG="ARGUMENT"
--FLAG 'ARGUMENT'
--FLAG "ARGUMENT"
Sostituisci quanto segue:
FLAG
: un flag globale o specifico del comandoARGUMENT
: l'argomento del flag
Alcuni comandi richiedono l'utilizzo di virgolette singole o doppie per gli argomenti. Spesso questo è vero quando l'argomento contiene spazi, virgole o altri caratteri speciali. Ad esempio:
bq query --nouse_legacy_sql \ 'SELECT COUNT(*) FROM `bigquery-public-data`.samples.shakespeare'
I flag con valori booleani possono essere specificati senza argomento. Se specifichi
true
o false
, devi utilizzare il formato
FLAG=ARGUMENT
.
Ad esempio, questo comando specifica false per il flag booleano --use_legacy_sql
posizionando no
all'inizio del flag:
bq query --nouse_legacy_sql \ 'SELECT COUNT(*) FROM `bigquery-public-data`.samples.shakespeare'
In alternativa, per specificare false
come argomento del flag, puoi inserire quanto segue:
bq query --use_legacy_sql=false \ 'SELECT COUNT(*) FROM `bigquery-public-data`.samples.shakespeare'
Esecuzione di query dallo strumento a riga di comando bq
Per eseguire una query sviluppata nella console Google Cloud ed eseguirla dallo strumento a riga di comando bq, segui questi passaggi:
- Includi la query in un comando
bq query
come segue:bq query --use_legacy_sql=false 'QUERY'
. SostituisciQUERY
con la query. - Sostituisci tutte le virgolette singole (
'
) all'interno della query con virgolette doppie ("
). Verifica che la query sia racchiusa tra virgolette singole ('
). - Rimuovere i commenti dalla query.
Ad esempio, trasforma la seguente query nella console Google Cloud:
-- count Shakespeare's use of the string "raisin"
SELECT
word,
SUM(word_count) AS count
FROM
`bigquery-public-data`.samples.shakespeare
WHERE
word LIKE '%raisin%'
GROUP BY
word
in una query dello strumento a riga di comando bq, come segue:
bq query --use_legacy_sql=false \
'SELECT
word,
SUM(word_count) AS count
FROM
`bigquery-public-data`.samples.shakespeare
WHERE
word LIKE "%raisin%"
GROUP BY
word'
Per maggiori informazioni, consulta Esecuzione di job di query interattivi e batch.
Assistenza
Per richiedere assistenza per lo strumento a riga di comando bq, puoi inserire i seguenti comandi:
- Per la versione installata dello strumento a riga di comando bq, inserisci
bq version
. - Per un elenco completo dei comandi, inserisci
bq help
. - Per un elenco di flag globali, inserisci
bq --help
. - Per ricevere assistenza su un comando specifico, inserisci
bq help COMMAND
. - Per ricevere assistenza per un comando specifico e per un elenco di flag globali, inserisci
bq COMMAND --help
.
Sostituisci COMMAND
con il comando per il quale hai bisogno di assistenza.
Impostazione dei valori predefiniti per i flag della riga di comando
Puoi impostare valori predefiniti per i flag della riga di comando includendoli nel file di configurazione dello strumento a riga di comando bq, .bigqueryrc
. Prima di configurare le opzioni predefinite, devi creare un file .bigqueryrc
. Puoi utilizzare il tuo
editor di testo preferito per creare il file. Dopo aver creato il file .bigqueryrc
, puoi specificare il percorso del file utilizzando il flag globale --bigqueryrc
.
Se il flag --bigqueryrc
non è specificato, viene utilizzata la variabile di ambiente BIGQUERYRC
. Se non è specificato, viene utilizzato il percorso ~/.bigqueryrc
. Il percorso predefinito è $HOME/.bigqueryrc
.
Aggiunta di flag a .bigqueryrc
in corso...
Per aggiungere valori predefiniti per i flag della riga di comando a .bigqueryrc
:
- Posiziona i flag globali nella parte superiore del file senza intestazione.
- Per i flag specifici del comando, inserisci il nome del comando (tra parentesi) e aggiungi i flag specifici del comando (uno per riga) dopo il nome del comando.
Ad esempio:
--apilog=stdout --format=prettyjson --location=US [query] --use_legacy_sql=false --max_rows=100 --maximum_bytes_billed=10000000 [load] --destination_kms_key=projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey
L'esempio precedente imposta i valori predefiniti per i seguenti flag:
- Il flag globale
--apilog
è impostato sustdout
per stampare l'output di debug sulla console Google Cloud. - Il flag globale
--format
è impostato suprettyjson
per visualizzare l'output comando in formato JSON leggibile. - Il flag globale
--location
è impostato sulla località con più regioniUS
. Il flag specifico del comando
query
--use_legacy_sql
è impostato sufalse
per rendere GoogleSQL la sintassi delle query predefinita.Il flag specifico del comando
query
--max_rows
è impostato su100
per controllare il numero di righe nell'output della query.Il flag specifico del comando
query
--maximum_bytes_billed
è impostato su 10.000.000 byte (10 MB) per non riuscire a eseguire query che leggono più di 10 MB di dati.Il flag specifico del comando
load
--destination_kms_key
è impostato suprojects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey
.
Esecuzione dello strumento a riga di comando bq in una shell interattiva
Puoi eseguire lo strumento a riga di comando bq in una shell interattiva in cui non è necessario
precedere i comandi con bq
. Per avviare la modalità interattiva, inserisci bq shell
.
Dopo l'avvio della shell, il prompt diventa l'ID del progetto predefinito.
Per uscire dalla modalità interattiva, inserisci exit
.
Esecuzione dello strumento a riga di comando bq in uno script
Puoi eseguire lo strumento a riga di comando bq in uno script, come faresti con un comando di Google Cloud CLI. Di seguito è riportato un esempio dei comandi gcloud
e bq
in uno script bash:
#!/bin/bash
gcloud config set project myProject
bq query --use_legacy_sql=false --destination_table=myDataset.myTable \
'SELECT
word,
SUM(word_count) AS count
FROM
`bigquery-public-data`.samples.shakespeare
WHERE
word LIKE "%raisin%"
GROUP BY
word'
Esecuzione dei comandi bq
da un account di servizio
Puoi utilizzare un account di servizio per effettuare chiamate API autorizzate o eseguire job di query per tuo conto. Per utilizzare un account di servizio nello strumento a riga di comando bq, autorizza l'accesso a Google Cloud dall'account di servizio. Per ulteriori informazioni, consulta gcloud auth activate-service-account.
Per iniziare a eseguire i comandi bq
utilizzando la impersonificazione degli account di servizio, esegui questo comando:
gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_NAME
Sostituisci SERVICE_ACCOUNT_NAME
con il nome del tuo account di servizio.
I comandi bq
che esegui ora utilizzano le credenziali dell'account di servizio.
Per interrompere l'esecuzione dei comandi bq
da un account di servizio, esegui questo comando:
gcloud config unset auth/impersonate_service_account
Esempi
Puoi trovare esempi delle righe di comando nella sezione Guide illustrative della documentazione di BigQuery. Questa sezione elenca i link ad attività a riga di comando comuni, come la creazione, il recupero, l'elenco, l'eliminazione e la modifica delle risorse BigQuery.
Crea le risorse
Per informazioni sull'utilizzo dello strumento a riga di comando bq per creare risorse, consulta quanto segue:
- Creazione di un set di dati
- Creazione di una tabella vuota con una definizione di schema
- Creare una tabella dal risultato di una query
- Creazione di una tabella partizionata per la fase di importazione
- Creazione di una vista
Per esempi sulla creazione di una tabella utilizzando un file di dati, vedi Caricamento di dati.
Ottenere informazioni sulle risorse
Per informazioni sull'utilizzo dello strumento a riga di comando bq per ottenere informazioni sulle risorse, consulta quanto segue:
- Ottenere informazioni sui set di dati
- Ottenere informazioni sulle tabelle
- Ottenere informazioni sulle viste
Elenco delle risorse
Per informazioni sull'utilizzo dello strumento a riga di comando bq per elencare le risorse, consulta quanto segue:
Elenco offerte di lavoro
Per informazioni sull'utilizzo dello strumento a riga di comando bq per elencare i job, consulta quanto segue:
Aggiornamento delle risorse
Per informazioni sull'utilizzo dello strumento a riga di comando bq per aggiornare le risorse, consulta quanto segue:
- Aggiornare le proprietà del set di dati
- Aggiornare le proprietà della tabella
- Aggiornare le proprietà delle viste
Caricamento dei dati
Per informazioni sull'utilizzo dello strumento a riga di comando bq per caricare i dati, consulta quanto segue:
- Caricamento di dati Avro da Cloud Storage
- Caricamento di dati JSON da Cloud Storage
- Caricamento dei dati CSV da Cloud Storage
- Caricamento di dati da un file locale
Esecuzione di query sui dati
Per informazioni sull'utilizzo dello strumento a riga di comando bq per eseguire query sui dati, consulta quanto segue:
Utilizzo di origini dati esterne
Per informazioni sull'utilizzo dello strumento a riga di comando bq per eseguire query sui dati in origini dati esterne, consulta quanto segue:
- Creazione di una definizione di tabella mediante un file di schema JSON
- Esecuzione di query sui dati di Bigtable utilizzando tabelle esterne permanenti
- Esecuzione di query sui dati di Cloud Storage utilizzando tabelle esterne permanenti
- Esecuzione di query sui dati di Google Drive utilizzando tabelle esterne permanenti
Esportazione di dati
Per informazioni sull'utilizzo dello strumento a riga di comando bq per esportare i dati, consulta quanto segue:
Utilizzo di BigQuery Data Transfer Service
Per informazioni sull'utilizzo dello strumento a riga di comando bq con BigQuery Data Transfer Service, consulta quanto segue:
- Configurazione di un trasferimento Amazon S3
- Impostare un trasferimento di Campaign Manager
- Configura un trasferimento in Cloud Storage
- Configurare un trasferimento di Google Ad Manager
- Configurare un trasferimento di Google Ads
- Configurare un trasferimento da Google Merchant Center (beta)
- Configurare un trasferimento da Google Play
- Configurare un trasferimento a Search Ads 360 (beta)
- Configurare il trasferimento di un canale YouTube
- Impostare un trasferimento di proprietario dei contenuti di YouTube
- Eseguire la migrazione dei dati da Amazon Redshift
- Eseguire la migrazione dei dati da Teradata
- Ottenere informazioni sulle configurazioni di trasferimento
- Elenco delle configurazioni di trasferimento
- Visualizzazione della cronologia delle esecuzioni
- Visualizzazione dei dettagli dell'esecuzione del trasferimento e dei messaggi di log
- Aggiornare le configurazioni di trasferimento
Risoluzione dei problemi dello strumento a riga di comando bq
Questa sezione mostra come risolvere i problemi relativi allo strumento a riga di comando bq.
Mantieni aggiornata gcloud CLI
Se utilizzi lo strumento a riga di comando bq di Google Cloud CLI, assicurati di disporre delle funzionalità e delle correzioni più recenti per lo strumento a riga di comando bq tenendo aggiornata l'installazione di gcloud CLI. Per verificare se stai eseguendo la versione più recente di gcloud CLI, inserisci il seguente comando in Cloud Shell:
gcloud components list
Le prime due righe dell'output mostrano il numero di versione dell'attuale installazione di gcloud CLI e il numero di versione dell'interfaccia a riga di comando più recente. Se scopri che la tua versione non è aggiornata, puoi aggiornare l'installazione di gcloud CLI alla versione più recente inserendo il seguente comando in Cloud Shell:
gcloud components update
Debug
Puoi inserire i seguenti comandi per eseguire il debug dello strumento a riga di comando bq:
Visualizza le richieste inviate e ricevute. Aggiungi il flag
--apilog=PATH_TO_FILE
per salvare un log delle operazioni in un file locale. SostituisciPATH_TO_FILE
con il percorso in cui vuoi salvare il log. Lo strumento a riga di comando bq effettua chiamate API standard basate su REST, cosa che può essere utile. È utile anche allegare questo log quando segnali un problema. Se utilizzi-
ostdout
anziché un percorso, il log viene stampato nella console Google Cloud. L'impostazione di--apilog
sustderr
restituisce il file di errori standard. Per registrare altre richieste, utilizza il flag--httplib2_debuglevel=LOG_LEVEL
. Un valoreLOG_LEVEL
superiore genera ulteriori informazioni sulle richieste http.Risolvi gli errori. Inserisci il flag
--format=prettyjson
quando ottieni lo stato di un job o quando visualizzi informazioni dettagliate su risorse come tabelle e set di dati. L'utilizzo di questo flag restituisce la risposta in formato JSON, inclusa la proprietàreason
. Puoi utilizzare la proprietàreason
per consultare i passaggi per la risoluzione dei problemi. Per ulteriori informazioni su eventuali errori durante l'esecuzione, utilizza il flag--debug_mode
.