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

Per un riferimento completo di tutti i comandi e i flag bq, consulta le Riferimento per lo 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. 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. 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 abilitato automaticamente nei nuovi progetti. Per attivare BigQuery in un progetto preesistente, vai a

   Attiva l'API BigQuery.

   Abilita l'API

5. (Facoltativo) Attiva fatturazione per il progetto. Se non vuoi abilitare la fatturazione o fornire una carta di credito, i passaggi descritti in questo documento continuano a funzionare. BigQuery mette a disposizione una sandbox per eseguire i passaggi. Per ulteriori informazioni, vedi Attiva la sandbox di BigQuery.
   Nota: se il progetto ha un account di fatturazione e vuoi utilizzare nella sandbox di BigQuery, quindi disabilita la fatturazione per il progetto.

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.

• 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 con gcloud CLI.

Posizionamento di flag e argomenti

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 per i comandi disponibili, vedi Riferimento per lo strumento a riga di comando bq.

Posiziona eventuali flag globali prima del comando bq e includi o altri flag specifici del comando. Puoi includere più query globali o specifiche e i flag facoltativi. 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 intorno agli 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 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 altri valori letterali stringa all'interno della query, devono seguire le regole di citazione per la shell in uso, come 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 questi 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 segnalazioni globali, inserisci bq --help.
• Per ricevere assistenza per un comando specifico, inserisci bq help COMMAND.
• Per ricevere assistenza per un comando specifico più 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 dello strumento a riga di comando bq, .bigqueryrc. Prima di configurare opzioni predefinite, devi prima 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 specificato, il percorso ~/.bigqueryrc è in uso. Il percorso predefinito è $HOME/.bigqueryrc.

Nota: la creazione di un file .bigqueryrc utilizzando il comando bq init consigliato.

Aggiunta di flag a .bigqueryrc

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

• Posizionare 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 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 eseguire il debug della stampa nell'output 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 specifico del comando query --use_legacy_sql è impostato su false per a GoogleSQL la sintassi predefinita delle query.

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

• 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 aggiungi il prefisso bq ai comandi. 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 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 account di servizio per effettuare di chiamate API autorizzate o di 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, vedi 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 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'uso dello strumento a riga di comando bq per creare risorse, consulta seguenti:

• Creazione di un set di dati
• Creazione di una tabella vuota con una definizione di schema
• Creazione di una tabella dal risultato di una query
• Creazione di una tabella partizionata per data di importazione
• Creazione di una vista

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

Recupero di informazioni sulle risorse

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

• Recupero di informazioni sui set di dati
• Recupero di informazioni sulle tabelle
• Ottenere informazioni sulle viste

Elenco delle risorse

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

• Elenco dei set di dati
• Tabelle di schede
• Visualizzazioni scheda

Elenco offerte di lavoro

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

• Elenco di offerte di lavoro

Aggiornamento delle risorse

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

• Aggiornare le proprietà del 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 le seguenti risorse:

• Caricamento di dati Avro da Cloud Storage
• Caricamento di dati JSON da Cloud Storage
• Caricare dati CSV da Cloud Storage
• Caricamento di dati da un file locale

Esecuzione di query sui dati

Per informazioni sull'uso dello strumento a riga di comando bq per eseguire query sui dati, consulta quanto segue:

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

Utilizzo di origini dati esterne

Per informazioni sull'uso dello strumento a riga di comando bq per eseguire query sui dati esterni di Google Analytics, vedi quanto segue:

• Creazione di una definizione di tabella utilizzando un file di schema JSON
• Esecuzione di query sui dati Bigtable utilizzando tabelle esterne permanenti
• Esecuzione di query sui dati di Cloud Storage utilizzando tabelle esterne permanenti
• Interrogare i dati di Google Drive utilizzando tabelle esterne permanenti

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'uso dello strumento a riga di comando bq con BigQuery Data Transfer Service, consulta seguenti:

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

• Ottenere informazioni sulle configurazioni di trasferimento
• Elenco delle configurazioni di trasferimento
• Visualizzazione della cronologia delle esecuzioni
• Visualizzazione dei dettagli dell'esecuzione del trasferimento e dei messaggi di log
• Aggiornare le configurazioni di trasferimento

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.

Mantieni aggiornata gcloud CLI

Se utilizzi lo strumento a riga di comando bq di Google Cloud CLI, assicurati di hai la versione più recente funzionalità e correzioni per lo strumento a riga di comando bq mantenendo gcloud CLI l'installazione aggiornata. 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 l'installazione di gcloud CLI e il numero di versione del con gcloud CLI. Se scopri che la tua versione è obsoleta, puoi aggiornare il l'installazione di gcloud CLI alla versione più recente inserendo il 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 rendendo standard Chiamate API, che possono essere utili. È 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. Impostazione di --apilog su stderr output sul valore standard del file degli errori. Per registrare altre richieste, utilizza --httplib2_debuglevel=LOG_LEVEL flag. R più in alto di LOG_LEVEL registra ulteriori informazioni sul protocollo http richieste.

• Risolvi 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 lo reason proprietà da cercare passaggi per la risoluzione dei problemi. Per ulteriori informazioni su eventuali errori durante l'esecuzione, utilizza il flag --debug_mode.