Esplorare 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 la documentazione di 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
- 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.
Inserendo i 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:
- I flag globali possono essere utilizzati in tutti i comandi.
- I flag specifici del comando si applicano a un comando specifico.
Per un elenco dei flag globali e specifici dei comandi disponibili, consulta la documentazione di riferimento per lo strumento a riga di comando bq.
Posiziona eventuali flag globali prima del comando bq
e includi i flag specifici del comando. Puoi includere più flag globali o
specifici per 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 per il comandoARGUMENT
: argomento del flag
Alcuni comandi richiedono l'utilizzo di virgolette singole o doppie intorno agli argomenti. Questo si verifica spesso 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
davanti al 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.Formatta la stringa di query.
Se nella query devi utilizzare valori letterali stringa aggiuntivi, devi seguire le regole di citazione per la shell in uso, ad esempio Bash o PowerShell.
L'esempio seguente mostra un approccio tipico in Bash, che consiste nell'utilizzare le virgolette doppie per indicare i valori letterali stringa nella query, quindi racchiudere la query stessa tra virgolette singole:
'SELECT * FROM mydataset.mytable WHERE column1 = "value";'
Se stai copiando la query da un'altra posizione, devi rimuovere anche eventuali commenti nella query.
Ad esempio, trasforma la seguente query sulla 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 sullo 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 ulteriori informazioni, consulta Esecuzione di job di query interattivi e batch.
Assistenza
Per ricevere assistenza per lo strumento a riga di comando bq, puoi inserire questi 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 segnalazioni globali, inserisci
bq --help
. - Per ricevere assistenza per un comando specifico, inserisci
bq help COMMAND
. - Per ricevere assistenza per un comando specifico e 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
. Per creare il file, puoi utilizzare
il tuo editor di testo preferito. Dopo aver creato il file .bigqueryrc
, puoi specificare il percorso del file utilizzando il flag globale --bigqueryrc
.
Se il flag --bigqueryrc
non viene 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
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 valori predefiniti per i seguenti flag:
- Il flag globale
--apilog
è impostato sustdout
per eseguire il debug della stampa sulla console Google Cloud. - Il flag globale
--format
è impostato suprettyjson
per visualizzare l'output comando in un formato JSON leggibile. - Il flag globale
--location
è impostato sulla località multiregionaleUS
. 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 di byte (10 MB) per non avere esito positivo per le 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
prefissare i comandi con bq
. Per avviare la modalità interattiva, inserisci bq shell
.
Dopo l'avvio della shell, il prompt cambia nell'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, proprio come faresti con un
comando 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 di 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 maggiori informazioni, consulta gcloud auth activate-service-account.
Per iniziare a eseguire i comandi bq
utilizzando la rappresentazione 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 di riga di comando nella sezione delle guide illustrative della documentazione di BigQuery. Questa sezione elenca i link ad attività comuni a riga di comando 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:
- Creazione di un set di dati
- Creazione di una tabella vuota con una definizione di schema
- Creazione di una tabella dal risultato di una query
- Creazione di una tabella partizionata per data di importazione
- Creazione di una vista
Per esempi di creazione di una tabella utilizzando un file di dati, consulta Caricamento di dati.
Recupero di informazioni sulle risorse
Per informazioni sull'uso dello strumento a riga di comando bq per ottenere informazioni sulle risorse, consulta quanto segue:
- Recupero di informazioni sui set di dati
- Recupero di 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:
- 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 le seguenti risorse:
- Caricamento di dati Avro da Cloud Storage
- Caricamento di dati JSON da Cloud Storage
- Caricare dati CSV da Cloud Storage
- Caricamento di dati da un file locale
Esecuzione di query sui dati
Per informazioni sull'uso 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 utilizzando un file di schema JSON
- Esecuzione di query sui dati Bigtable utilizzando tabelle esterne permanenti
- Esecuzione di query sui dati di Cloud Storage utilizzando tabelle esterne permanenti
- Interrogare i 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
- Configurare un trasferimento di Campaign Manager
- Configurare un trasferimento in Cloud Storage
- Configurare un trasferimento da Google Ad Manager
- Configurare un trasferimento di Google Ads
- Configurare un trasferimento da Google Merchant Center (beta)
- Configurare un trasferimento da Google Play
- Impostare un trasferimento di Search Ads 360 (beta)
- Impostare il trasferimento di un canale YouTube
- Configurare il trasferimento del 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 relativi allo 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 mantenendo 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:
Visualizzare 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 esegue chiamate API standard basate su REST, che possono essere utili. È utile anche allegare questo log quando segnali dei problemi. Se utilizzi-
ostdout
invece di un percorso, il log viene visualizzato nella console Google Cloud. Se imposti--apilog
sustderr
, gli output vengono restituiti al file di errore standard. Per registrare altre richieste, utilizza il flag--httplib2_debuglevel=LOG_LEVEL
. Un valoreLOG_LEVEL
più alto registra 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 cercare i passaggi per la risoluzione dei problemi. Per ulteriori informazioni su eventuali errori durante l'esecuzione, utilizza il flag--debug_mode
.