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.

  1. 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.

  2. Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

    Vai al selettore progetti

    3.

  3. Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

    Vai al selettore progetti

    4.
  4. BigQuery viene abilitato automaticamente nei nuovi progetti. Per attivare BigQuery in un progetto preesistente, vai a

    Attiva l'API BigQuery.

    Abilita l'API

  5. (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.

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 comando
  • ARGUMENT: 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:

  1. Includi la query in un comando bq query come segue: bq query --use_legacy_sql=false 'QUERY'. Sostituisci QUERY con la query.
  2. Sostituisci tutte le virgolette singole (') all'interno della query con virgolette doppie ("). Verifica che la query sia racchiusa tra virgolette singole (').
  3. 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 su stdout per stampare l'output di debug sulla console Google Cloud.
  • Il flag globale --format è impostato su prettyjson per visualizzare l'output comando in formato JSON leggibile.
  • Il flag globale --location è impostato sulla località con più regioni US.

  • Il flag specifico del comando query --use_legacy_sql è impostato su false per rendere GoogleSQL la sintassi delle query predefinita.

  • Il flag specifico del comando query --max_rows è impostato su 100 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 su projects/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:

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:

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:

Caricamento dei dati

Per informazioni sull'utilizzo dello strumento a riga di comando bq per caricare i dati, consulta quanto segue:

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:

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:

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. Sostituisci PATH_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 - o stdout anziché un percorso, il log viene stampato nella console Google Cloud. L'impostazione di --apilog su stderr restituisce il file di errori standard. Per registrare altre richieste, utilizza il flag --httplib2_debuglevel=LOG_LEVEL. Un valore LOG_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.