Usando 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'utilizzo dello strumento a riga di comando bq.

Per un riferimento completo di tutti i comandi e i flag bq, consulta il riferimento per lo 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 console di Google Cloud Console, nella pagina del selettore dei progetti, seleziona o crea un progetto Google Cloud.

    Vai al selettore progetti

    3.

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

    Vai al selettore progetti

    4.
  4. BigQuery è 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 funzionano comunque. BigQuery offre una sandbox per eseguire i passaggi. Per maggiori informazioni, vedi 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.

Flag e argomenti di posizionamento

Lo strumento a riga di comando bq supporta due tipi di flag:

  • I flag globali possono essere utilizzati in tutti i comandi.
  • A un comando specifico si applicano flag specifici.

Per un elenco dei flag globali e specifici per i comandi, consulta la documentazione di riferimento sullo strumento a riga di comando bq.

Inserisci eventuali flag globali prima del comando bq, quindi includi flag specifici per i comandi. Puoi includere più flag globali o specifici per i comandi. Ad esempio:

bq --location=us mk --reservation --project_id=project reservation_name

Puoi specificare argomenti di comando 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 comando
  • ARGUMENT: l'argomento della bandiera

Alcuni comandi richiedono l'uso di virgolette singole o doppie tra gli argomenti. Questo spesso si verifica 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 argomenti. 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 che hai sviluppato nella console Google Cloud ed eseguirla dallo strumento a riga di comando bq, procedi nel seguente modo:

  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 le virgolette singole (') nella query con virgolette doppie (").
  3. Rimuovi i commenti dalla query.

Ad esempio, trasforma la query seguente della 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 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 i comandi seguenti:

  • 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 bandiere 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 cui 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 usare l'editor di testo che preferisci 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

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 per i comandi, inserisci il nome del comando (tra parentesi) e aggiungi i flag specifici per il 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 nella console Google Cloud.
  • Il flag globale --format è impostato su prettyjson per visualizzare l'output comando in un formato JSON leggibile.
  • Il flag globale --location è impostato sulla località multiregione US.

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

  • Il flag --max_rows specifico per il comando query è impostato su 100 per controllare il numero di righe nell'output della query.

  • Il flag --maximum_bytes_billed specifico per il comando query è impostato su 10.000.000 byte (10 MB) per eseguire query non riuscite 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 aver avviato la shell, il prompt cambia all'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 Google Cloud CLI. Di seguito è riportato un esempio di 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 bq comandi 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 il furto d'identità degli account di servizio, esegui il seguente 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 della riga di comando nella sezione Guide illustrative della documentazione di BigQuery. Questa sezione elenca i link alle attività a riga di comando comuni, come la creazione, il recupero, l'elenco, l'eliminazione e la modifica delle risorse BigQuery.

Creazione delle risorse

Per informazioni sull'utilizzo dello strumento a riga di comando bq, crea quanto segue:

Per esempi di creazione di una tabella utilizzando un file di dati, vedi Caricamento dei dati.

Ottenere informazioni sulle risorse

Per informazioni sull'utilizzo dello strumento a riga di comando bq, consulta le risorse seguenti:

Elenco delle risorse

Per informazioni sull'utilizzo dello strumento a riga di comando bq, consulta le seguenti risorse:

Job in elenco

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, aggiorna quanto segue:

Caricamento dei dati

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

Esecuzione di query sui dati

Per informazioni sull'utilizzo dello strumento a riga di comando bq, esegui le query seguenti:

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, vedi:

Utilizzo di BigQuery Data Transfer Service

Per informazioni sull'utilizzo dello strumento a riga di comando bq con BigQuery Data Transfer Service, consulta:

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 aggiornato l'interfaccia a riga di comando gcloud

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 dell'interfaccia a riga di comando gcloud. Per verificare se stai eseguendo la versione più recente dell'interfaccia a riga di comando gcloud, inserisci il comando seguente in Cloud Shell:

gcloud components list

Le prime due righe dell'output mostrano il numero di versione dell'installazione dell'interfaccia a riga di comando gcloud attuale e il numero di versione dell'interfaccia a riga di comando gcloud più recente. Se scopri che la tua versione non è aggiornata, puoi aggiornare l'installazione dell'interfaccia a riga di comando gcloud alla versione più recente inserendo il comando seguente 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. Sostituisci PATH_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 da vedere. Inoltre, è utile allegare questo log per la segnalazione di problemi. L'utilizzo di - o stdout anziché un percorso stampa il log sulla console Google Cloud. L'impostazione di --apilog su stderr restituisce il file di errore standard.

  • 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. Se usi questo flag, la risposta viene restituita in formato JSON, inclusa la proprietà reason. Puoi utilizzare la proprietà reason per cercare i passaggi per la risoluzione dei problemi.