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 usare nella 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.

    Go to project selector

    3.

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

    Go to project selector

    4.
  4. BigQuery viene attivato automaticamente nei nuovi progetti. Per attivare BigQuery in un progetto preesistente, 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 continuano a funzionare. BigQuery ti fornisce una sandbox per eseguire i passaggi. Per ulteriori informazioni, vedi Attiva 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.

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 del comando 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 in gli 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: argomento del flag

Alcuni comandi richiedono l'utilizzo di virgolette singole o doppie per gli argomenti. Questo si verifica spesso quando l'argomento contiene spazi, virgole o altri spazi caratteri. 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 davanti alla bandiera:

bq query --nouse_legacy_sql \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

In alternativa, per specificare false come argomento del flag, puoi inserire il seguenti:

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 lo 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, che prevede l'utilizzo le virgolette doppie per indicare i valori letterali stringa nella query, quindi racchiudi la query 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 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, vedi 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 di flag globali, inserisci bq --help.
  • Per ricevere assistenza per 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 che ti serve aiuto con.

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 editor di testo preferito per creare il file. Dopo aver creato .bigqueryrc puoi specificare il percorso del file utilizzando il flag globale --bigqueryrc.

Se il flag --bigqueryrc non è specificato, l'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 per i 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 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 in un formato JSON leggibile.
  • Il flag globale --location è impostato sulla località multiregionale US.

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

  • Il flag specifico del comando query --max_rows è impostato su 100 per controllare le 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 le query che leggono più di 10 MB di e i dati di Google Cloud.

  • Il flag specifico per il comando load --destination_kms_key impostata a 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 premettere 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, 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 di 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 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 di righe di comando nelle guide illustrative. della documentazione di BigQuery. Questa sezione elenca i link alle attività a riga di comando, come la creazione, il recupero, l'elenco, l'eliminazione e la modifica di risorse BigQuery.

Crea le risorse

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

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

Visualizzare le informazioni sulle risorse

Per informazioni sull'uso dello strumento a riga di comando bq per ottenere informazioni vedi le risorse seguenti:

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 di 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 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 di Google Cloud CLI, assicurati di hai le ultime novità funzionalità e correzioni per lo strumento a riga di comando bq mantenendo gcloud CLI dell'installazione aggiornata. Per verificare se stai eseguendo la versione più recente di gcloud CLI, inserisci questo comando in Cloud Shell:

gcloud components list

Le prime due righe dell'output mostrano il numero di versione l'installazione di gcloud CLI e il numero di versione del con gcloud CLI. 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

Puoi inserire i seguenti comandi per eseguire il debug dello strumento a riga di comando bq:

  • Visualizzare le richieste inviate e ricevute. Aggiungi il parametro 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 stai segnalando dei problemi. Se utilizzi - o stdout al posto di un percorso, il log viene stampato alla console Google Cloud. L'impostazione di --apilog su stderr genera output nel file di errori standard. Per registrare altre richieste, utilizza --httplib2_debuglevel=LOG_LEVEL flag. Un valore LOG_LEVEL più elevato registra più informazioni sulle richieste HTTP.

  • Risolvere gli errori. Inserisci il flag --format=prettyjson quando ricevi un stato del job o quando visualizzi i dettagli e informazioni 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.