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

Per un riferimento completo di tutti i comandi e i flag bq, consulta il riferimento allo 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. 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.

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

   Enable the BigQuery API.

   Enable the API

5. (Facoltativo) Attiva 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 fornisce una sandbox per eseguire i passaggi. Per ulteriori informazioni, consulta Attiva la sandbox di BigQuery.
   Nota: se il tuo progetto ha un account di fatturazione e vuoi utilizzare la sandbox di BigQuery, disattiva la fatturazione per il progetto.

Inserire 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:

  Attivare 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 i comandi si applicano a un comando specifico.

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

Inserisci eventuali flag globali prima del comando bq, quindi includi i flag specifici del comando. Puoi includere più flag globali o specifici per i comandi. 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 per gli argomenti. Ciò accade 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 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 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'

Eseguire query dallo strumento a riga di comando bq

Per prendere 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. Formatta la stringa di query.

   Se devi utilizzare stringhe letterali aggiuntive all'interno della query, devi seguire le regole di virgole per la shell che stai utilizzando, ad esempio Bash o PowerShell.

   L'esempio seguente mostra un approccio tipico in Bash, ovvero l'utilizzo di virgolette doppie per indicare le stringhe letterali nella query e poi l'inclusione della 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 al suo interno.

   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 Eseguire job di query interattive 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 di flag globali, inserisci bq --help.
• Per assistenza su un comando specifico, inserisci bq help COMMAND.
• Per assistenza su un comando specifico e per 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 valori predefiniti per i flag della riga di comando includendoli nel file di configurazione .bigqueryrc dello strumento a riga di comando bq. Prima di configurare le opzioni predefinite, devi creare un file .bigqueryrc. Puoi utilizzare 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 viene specificato, viene utilizzato il percorso ~/.bigqueryrc. Il percorso predefinito è $HOME/.bigqueryrc.

Nota: la creazione di un file .bigqueryrc utilizzando il comando bq init non è consigliata.

Aggiunta di flag a .bigqueryrc

Per aggiungere valori predefiniti per i flag della riga di comando a .bigqueryrc:

• Inserisci flag globali nella parte superiore del file senza un'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 nella console Google Cloud.
• Il flag globale --format è impostato su prettyjson per visualizzare l'output comando in un formato JSON leggibile.
• L'indicatore globale --location è impostato sulla località multiregione US.

• Il flag query specifico del comando --use_legacy_sql è impostato su false per impostare GoogleSQL come sintassi di query predefinita.

  Nota: non puoi utilizzare --nouse_legacy_sql in .bigqueryrc.

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

• Il query flag specifico del comando --maximum_bytes_billed è impostato su 10.000.000 byte (10 MB) per interrompere le 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.

Eseguire lo 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 premettere i comandi con bq. Per avviare la modalità interattiva, inserisci bq shell. Dopo aver lanciato la shell, il prompt cambia in base all'ID del progetto predefinito. Per uscire dalla modalità interattiva, inserisci exit.

Eseguire lo 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 della CLI di Google Cloud. 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'

Eseguire 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 l'inganno dell'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 il seguente 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à comuni della riga di comando, 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:

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

Per esempi di creazione di una tabella utilizzando un file di dati, consulta Caricare i dati.

Visualizzare le 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 visualizzazioni

Elenco delle risorse

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

• Set di dati delle schede
• Tabelle delle schede
• Visualizzazioni della scheda

Job di elenco

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

• Pubblicazione di annunci

Aggiornamento delle risorse

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

• Aggiornare le proprietà dei set di dati
• Aggiornare le proprietà della tabella
• Aggiornare le proprietà delle viste

Caricamento di dati

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

• Caricare dati Avro da Cloud Storage
• Caricare dati JSON da Cloud Storage
• Caricare i dati CSV da Cloud Storage
• Caricare i 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
• Eseguire 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:

• Creare una definizione di tabella utilizzando un file di schema JSON
• Eseguire query sui dati Bigtable
• Eseguire 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:

• Configurare un trasferimento di Amazon S3
• Configurare un trasferimento di Campaign Manager
• Configurare un trasferimento di Cloud Storage
• Configurare un trasferimento di Google Ad Manager
• Configurare un trasferimento di Google Ads
• Configurare un trasferimento di Google Merchant Center (beta)
• Configurare un trasferimento da Google Play
• Configurare un trasferimento di Search Ads 360 (beta)
• Configurare il trasferimento di un canale YouTube
• Configurare un trasferimento del proprietario dei contenuti di YouTube
• Eseguire la migrazione dei dati da Amazon Redshift
• Eseguire la migrazione dei dati da Teradata

• Gestire i trasferimenti

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.

Mantenere aggiornata l'interfaccia a riga di comando gcloud

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 utilizzando la versione più recente dellgcloud 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 dell'interfaccia alla gcloud CLI e il numero di versione dell'interfaccia a gcloud CLI più recente. Se scopri che la tua versione è obsoleta, puoi aggiornare l'installazione di gcloud CLI alla versione più recente inserendo il seguente comando in Cloud Shell:

gcloud components update

Debug

Per eseguire il debug dello strumento a riga di comando bq, puoi inserire i seguenti comandi:

• 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 basate su REST standard, che possono essere utili da vedere. È utile anche allegare questo log quando segnali problemi. Se utilizzi - o stdout anziché un percorso, il log viene stampato nella console Google Cloud. L'impostazione di --apilog su stderr genera output nel file di errori standard. Per registrare più richieste, utilizza il flag --httplib2_debuglevel=LOG_LEVEL. Un valore LOG_LEVEL più elevato registra più informazioni sulle richieste HTTP.

• Risolvere 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 genera 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.