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'utilizzo 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.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

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

   Enable the BigQuery API.

   Enable the API

2. (Facoltativo) Abilita la fatturazione per il progetto. Se non vuoi attivare la fatturazione o fornire una carta di credito, i passaggi descritti in questo documento funzionano comunque. BigQuery ti offre una sandbox per eseguire i passaggi. Per saperne di più, vedi Attiva 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:

  Attiva Cloud Shell

• Per utilizzare lo strumento a riga di comando bq da gcloud CLI, installa e configura gcloud 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.
• I flag specifici per il comando si applicano a un comando specifico.

Per un elenco dei flag globali e specifici dei comandi disponibili, consulta il riferimento allo strumento a riga di comando bq.

Posiziona i flag globali prima del comando bq, quindi includi i flag specifici del comando. Puoi includere più flag globali o specifici per il 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 comando
• ARGUMENT: l'argomento del flag

Alcuni comandi richiedono l'utilizzo di virgolette singole o doppie intorno agli argomenti. Questo è spesso 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 un 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 inserendo 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 prendere 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 nel seguente modo: bq query --use_legacy_sql=false 'QUERY'. Sostituisci QUERY con la query.

2. Formatta la stringa di query.

   Se devi utilizzare ulteriori stringhe letterali all'interno della query, devi rispettare le regole di citazione per la shell che utilizzi, ad esempio Bash o PowerShell.

   Il seguente esempio mostra un approccio tipico in Bash, ovvero l'utilizzo di virgolette doppie per indicare i valori letterali stringa nella query e poi racchiudere la query stessa tra virgolette singole:

   'SELECT * FROM mydataset.mytable WHERE column1 = "value";'
   

   Se copi la query da un'altra posizione, devi rimuovere anche eventuali commenti nella query.

   Ad esempio, trasforma la seguente query 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 la sezione Esecuzione di job di query interattivi e batch.

Assistenza

Per ricevere 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 dei flag globali, inserisci bq --help.
• Per assistenza su un comando specifico, inserisci bq help COMMAND.
• Per assistenza con un comando specifico e un elenco di flag globali, inserisci bq COMMAND --help.

Sostituisci COMMAND con il comando per cui hai bisogno di aiuto.

Impostazione dei valori predefiniti per i flag della riga di comando

Puoi impostare i 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 prima 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 viene 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 un'intestazione.
• Per i flag specifici dei comandi, 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 nella consoleGoogle 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à multiregionale US.

• Il queryflag specifico del comando --use_legacy_sql è impostato su false per rendere GoogleSQL la sintassi di 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 di byte (10 MB) per impedire l'esecuzione di 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 anteporre il prefisso bq ai comandi. Per avviare la modalità interattiva, inserisci bq shell. Dopo l'avvio della shell, il prompt cambia in ID del tuo 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 comandi bq da un account di servizio

Puoi utilizzare un service account 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 dalaccount di serviziot. Per maggiori informazioni, vedi gcloud auth activate-service-account.

Per iniziare a eseguire i comandi bq utilizzando l'impersonificazione del service account, 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 Guide pratiche della documentazione di BigQuery. Questa sezione elenca i link alle attività a riga di comando comuni, come la creazione, l'ottenimento, 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:

• Creare un set di dati
• Creazione di una tabella vuota con una definizione dello schema
• Creare una tabella da un risultato di query
• Creazione di una tabella partizionata per data di importazione
• Creare una visualizzazione

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

Recupero delle 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
• Recupero delle informazioni sulle visualizzazioni

Elenco delle risorse

Per informazioni sull'utilizzo dello strumento a riga di comando bq per elencare le risorse, consulta quanto segue:

• Elencare i set di dati
• Tabelle delle schede
• Visualizzazioni della scheda

Elenco dei job

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

• Elenco dei lavori

Aggiornamento delle risorse

Per informazioni sull'utilizzo dello strumento a riga di comando bq per aggiornare le risorse, consulta quanto segue:

• Aggiornamento delle proprietà dei set di dati
• Aggiornamento delle proprietà della tabella
• Aggiornamento delle proprietà delle viste

Caricamento di 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 dei 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:

• Esecuzione di query
• Scrittura dei risultati delle query
• Esecuzione di query con parametri

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
• Esegui una query sui dati Bigtable
• Esegui query sui dati di Cloud Storage
• Eseguire query sui dati di Google Drive

Esportazione di dati

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

• Esportazione dei dati archiviati in BigQuery

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:

• Configura un trasferimento da Amazon S3
• Configurare un trasferimento da Campaign Manager
• Configura un trasferimento da Cloud Storage
• Configurare un trasferimento da Google Ad Manager
• Configurare un trasferimento da Google Ads
• Configurare un trasferimento da Google Merchant Center (beta)
• Configurare un trasferimento da Google Play
• Configurare un trasferimento da Search Ads 360 (beta)
• Configurare un trasferimento dai canali YouTube
• Configurare un trasferimento dal proprietario dei contenuti YouTube
• Migrare i dati da Amazon Redshift
• Eseguire la migrazione dei dati da Teradata
• Gestire i trasferimenti

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.

Mantenere aggiornata la gcloud CLI

Se utilizzi lo strumento a riga di comando bq da 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 l'ultima versione di gcloud CLI, inserisci questo comando in Cloud Shell:

gcloud components list

Le prime due righe dell'output mostrano il numero di versione dell'installazione corrente dell'interfaccia alla gcloud CLI e il numero di versione dell'interfaccia a gcloud CLI 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. Sostituisci PATH_TO_FILE con il percorso in cui vuoi salvare il log. Lo strumento a riga di comando bq funziona effettuando chiamate API standard basate su REST, il che può essere utile da vedere. È utile allegare questo log anche quando segnali problemi. L'utilizzo di - o stdout anziché di un percorso stampa il log nella console Google Cloud . L'impostazione --apilog su stderr genera output nel file di errore standard. Per registrare più richieste, utilizza il flag --httplib2_debuglevel=LOG_LEVEL. Un valore LOG_LEVEL registra più informazioni sulle richieste http.

• Risolvi gli errori. Inserisci il flag --format=prettyjson quando ottieni lo stato di un job o quando visualizzi informazioni dettagliate sulle 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 sugli errori durante l'esecuzione, utilizza il flag --debug_mode.