Explorar a ferramenta de linha de comando bq

A ferramenta de linha de comando bq é uma ferramenta de linha de comando baseada em Python para o BigQuery. Esta página contém informações gerais sobre como usar a ferramenta de linha de comando bq.

Para obter uma referência completa de todos os comandos e flags bq, consulte a referência da ferramenta de linha de comando bq.

Antes de começar

Antes de usar a ferramenta de linha de comando bq, use o console do Google Cloud para criar ou selecionar um projeto.

  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. O BigQuery é ativado automaticamente em novos projetos. Para ativar o BigQuery em um projeto preexistente, acesse

    Enable the BigQuery API.

    Enable the API

  5. Opcional: ative o faturamento do projeto. Se você não quiser ativar o faturamento ou informar um cartão de crédito, as etapas deste documento ainda funcionarão. O BigQuery fornece um sandbox para executar as etapas. Para mais informações, consulte Ativar o sandbox do BigQuery.

Como inserir comandos bq no Cloud Shell

É possível inserir comandos da ferramenta de linha de comando bq no Cloud Shell pelo console do Google Cloud ou pela CLI do Google Cloud.

Como posicionar sinalizações e argumentos

A ferramenta de linha de comando bq é compatível com dois tipos de flags:

  • Sinalizações globais podem ser usadas em todos os comandos.
  • Sinalizações específicas para o comando se aplicam a um determinado comando.

Para ver uma lista de sinalizadores globais e específicos de comandos disponíveis, consulte a referência da ferramenta de linha de comando bq.

Coloque todas as sinalizações globais antes do comando bq e, em seguida, inclua as sinalizações específicas do comando. É possível incluir várias sinalizações globais ou específicas de comando. Exemplo:

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

É possível especificar argumentos de comando das seguintes maneiras:

  • --FLAG ARGUMENT (como mostrado nos exemplos anteriores)
  • --FLAG=ARGUMENT
  • --FLAG='ARGUMENT'
  • --FLAG="ARGUMENT"
  • --FLAG 'ARGUMENT'
  • --FLAG "ARGUMENT"

Substitua:

  • FLAG: uma sinalização global ou específica de comando
  • ARGUMENT: o argumento da sinalização

Para alguns comandos, é necessário usar aspas simples ou duplas em torno dos argumentos. Isso geralmente ocorre quando o argumento contém espaços, vírgulas ou outros caracteres especiais. Por exemplo:

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

Sinalizações com valores booleanos podem ser especificados sem um argumento. Se você especificar true ou false, será necessário usar o formato FLAG=ARGUMENT.

Por exemplo, este comando especifica false para a sinalização booleana --use_legacy_sql posicionando no na frente da sinalização:

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

Como alternativa, para especificar false como o argumento da sinalização, insira o seguinte:

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

Como executar consultas usando a ferramenta de linha de comando bq

Para executar uma consulta desenvolvida no console do Google Cloud e executá-la na ferramenta de linha de comando bq, faça o seguinte:

  1. Inclua a consulta em um comando bq query da seguinte maneira: bq query --use_legacy_sql=false 'QUERY'. Substitua QUERY pela consulta.

  2. Formate a string de consulta.

    Se você precisar usar literais de string adicionais na consulta, deve seguir as regras de aspas para o shell que você está usando, como Bash ou PowerShell.

    O exemplo a seguir mostra uma abordagem típica no Bash, que é usar aspas duplas para denotar os literais de string na consulta e depois coloque a consulta entre aspas simples:

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

    Se você estiver copiando a consulta de outro local, remova também qualquer comentário na consulta.

    Por exemplo, transforme a seguinte consulta do console do 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

    em uma consulta da ferramenta de linha de comando bq. Para isso, faça o seguinte:

    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'

Para mais informações, consulte Como executar jobs de consulta interativos e em lote.

Como receber ajuda

Para receber ajuda com a ferramenta de linha de comando bq, digite os seguintes comandos:

  • Para a versão instalada da ferramenta de linha de comando bq, digite bq version.
  • Para uma lista completa de comandos, insira bq help.
  • Para obter uma lista de sinalizações globais, insira bq --help.
  • Para obter ajuda com um comando específico, insira bq help COMMAND.
  • Para ajuda com um comando específico e uma lista de sinalizações globais, insira bq COMMAND --help.

Substitua COMMAND pelo comando que você precisa de ajuda.

Como configurar valores padrão para sinalizações de linha de comando

Você pode definir valores padrão para as sinalizações de linha de comando incluindo-as no arquivo de configuração da ferramenta de linha de comando bq, .bigqueryrc. Antes de configurar as opções padrão, você deve primeiro criar um arquivo .bigqueryrc. É possível usar seu editor de texto preferido para criar o arquivo. Depois de criar o arquivo .bigqueryrc, você pode especificar o caminho para o arquivo usando a sinalização global --bigqueryrc.

Se a sinalização --bigqueryrc não for especificada, a variável de ambiente BIGQUERYRC será usada. Se não for especificada, o caminho ~/.bigqueryrc será usado. O caminho padrão é $HOME/.bigqueryrc.

Adicionando sinalizações a .bigqueryrc

Para adicionar valores padrão para sinalizações de linha de comando a .bigqueryrc:

Exemplo:

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

O exemplo anterior define os valores padrão para as seguintes sinalizações:

  • A sinalização global --apilog está definida como stdout para imprimir a saída de depuração no console do Google Cloud.
  • A sinalização global --format está definida como prettyjson para exibir a resposta do comando em um formato JSON legível por humanos.
  • A sinalização global --location está definida como o local multirregional US.

  • A sinalização --use_legacy_sql específica do comando query é definida como false para tornar o GoogleSQL a sintaxe de consulta padrão.

  • A sinalização query específica do comando --max_rows está definida como 100 para controlar o número de linhas na saída da consulta.

  • A sinalização query específica do comando --maximum_bytes_billed é definida como 10.000.000 bytes (10 MB) para apresentar falha em consultas que leem mais de 10 MB de dados.

  • A sinalização load específica do comando --destination_kms_key está definida como projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey.

Como executar a ferramenta de linha de comando bq em um shell interativo

É possível executar a ferramenta de linha de comando bq em um shell interativo que não solicite prefixar os comandos com bq. Para iniciar o modo interativo, insira bq shell. Depois de executar o shell, o prompt muda para o ID de seu projeto padrão. Para sair do modo interativo, digite exit.

Como executar a ferramenta de linha de comando bq em um script

É possível executar a ferramenta de linha de comando bq em um script, assim como executaria um comando da CLI do Google Cloud. Veja a seguir um exemplo de comandos gcloud e bq em um 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'

Como executar comandos bq de uma conta de serviço

Use uma conta de serviço para fazer chamadas de API autorizadas ou executar jobs de consulta em seu nome. Para usar uma conta de serviço na ferramenta de linha de comando bq, autorize o acesso ao Google Cloud pela conta de serviço. Para mais informações, consulte gcloud auth activate-service-account.

Para começar a executar comandos bq usando a representação da conta de serviço, execute o seguinte:

gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_NAME

Substitua SERVICE_ACCOUNT_NAME pelo nome da conta de serviço.

Os comandos bq que você executa agora usam as credenciais da conta de serviço.

Para interromper a execução de comandos bq de uma conta de serviço, execute o seguinte comando:

gcloud config unset auth/impersonate_service_account

Exemplos

É possível encontrar exemplos de linha de comando na seção Guias de instruções na documentação do BigQuery. Esta seção lista links para tarefas de linha de comando comuns, como criar, receber, listar, excluir e modificar recursos do BigQuery.

Criação de recursos

Para informações sobre como usar a ferramenta de linha de comando bq para criar recursos, consulte o seguinte:

Para ver exemplos de como criar uma tabela usando um arquivo de dados, consulte Como carregar dados.

Como encontrar informações sobre recursos

Para saber como usar a ferramenta de linha de comando bq para conseguir informações sobre recursos, consulte o seguinte:

Como listar recursos

Para saber como usar a ferramenta de linha de comando bq para listar recursos, consulte o seguinte:

Listar jobs

Para saber como usar a ferramenta de linha de comando bq para listar jobs, consulte o seguinte:

Como atualizar recursos

Para informações sobre como usar a ferramenta de linha de comando bq para atualizar recursos, consulte o seguinte:

Carregando dados

Para informações sobre como usar a ferramenta de linha de comando bq para carregar dados, consulte o seguinte:

Como consultar dados

Para informações sobre como usar a ferramenta de linha de comando bq para consultar dados, consulte o seguinte:

Como usar fontes de dados externas

Para informações sobre como usar a ferramenta de linha de comando bq para consultar dados em fontes de dados externas, consulte o seguinte:

Exportação de dados

Para informações sobre como usar a ferramenta de linha de comando bq para exportar dados, consulte o seguinte:

Como usar o BigQuery Data Transfer Service

Para informações sobre como usar a ferramenta de linha de comando bq com o serviço de transferência de dados do BigQuery, consulte o seguinte:

Solução de problemas da ferramenta de linha de comando bq

Esta seção mostra como resolver problemas com a ferramenta de linha de comando bq.

Manter a CLI gcloud atualizada

Se você estiver usando a ferramenta de linha de comando bq da CLI do Google Cloud, verifique se tem as funcionalidades e correções mais recentes para a ferramenta de linha de comando bq, mantendo sua instalação da CLI gcloud ativada até o momento. Para ver se você está executando a versão mais recente da gcloud CLI, digite o seguinte comando no Cloud Shell:

gcloud components list

As duas primeiras linhas do resultado mostram o número da versão da instalação atual da gcloud CLI e o número da versão da gcloud CLI mais recente. Se você descobrir que sua versão está desatualizada, será possível atualizar a instalação da gcloud CLI para a versão mais recente inserindo o seguinte comando no Cloud Shell:

gcloud components update

Depuração

É possível inserir os seguintes comandos para depurar a ferramenta de linha de comando bq:

  • Ver solicitações enviadas e recebidas. Adicione a sinalização --apilog=PATH_TO_FILE para salvar um registro de operações em um arquivo local. Substitua PATH_TO_FILE pelo caminho em que você quer salvar o registro. A ferramenta de linha de comando bq funciona fazendo chamadas de API padrão baseadas em REST, que podem ser úteis para visualização. Também é recomendável anexar esse registro ao relatar problemas. Usar - ou stdout em vez de um caminho imprime o registro no Console do Google Cloud. Definir --apilog para stderr gera a resposta no arquivo de erro padrão. Para registrar mais solicitações, use a flag --httplib2_debuglevel=LOG_LEVEL. Um LOG_LEVEL superior registra mais informações sobre as solicitações HTTP.

  • Solucionar problemas de erros. Insira a sinalização --format=prettyjson ao receber um status de tarefa ou ao visualizar informações detalhadas sobre recursos, como tabelas e conjuntos de dados. Usar essa sinalização gera a resposta no formato JSON, incluindo a propriedade reason. Você pode usar a propriedade reason para pesquisar etapas de solução de problemas. Para mais informações sobre erros durante a execução, use a flag --debug_mode.