Como usar 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 sinalizações bq, consulte a bq referência da ferramenta de linha de comando .

Antes de começar

Antes de usar a ferramenta de linha de comando bq, você precisa usar o Console do Google Cloud para criar ou selecionar um projeto e instalar o SDK do Cloud.

  1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
  2. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  3. Instale e inicialize o SDK do Cloud..
  4. O BigQuery é ativado automaticamente em novos projetos. Para ativar o BigQuery em um projeto preexistente, acesse Ative a API BigQuery.

    Ative a API

  5. Se você não quiser informar um cartão de crédito ou ativar o faturamento do seu projeto, o BigQuery fornece um sandbox. É possível seguir as etapas deste tópico mesmo que seu projeto não tenha o faturamento ativado. Se quiser ativá-lo, consulte Saiba como ativar o faturamento.

Em vez de fazer o download e instalar o SDK do Cloud, use uma versão pré-instalada dele no Google Cloud Shell.

Como posicionar sinalizações e argumentos

A ferramenta de linha de comando bq é compatível com dois tipos de sinalizações:

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

Para obter uma lista de sinalizações globais e específicas de comandos disponíveis, consulte a bqreferência de ferramenta de linha de comando.

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. Substitua as aspas simples (') na consulta por aspas duplas (").
  3. Remova os comentários 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 depurar

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

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

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 (.bigqueryrc) da ferramenta de linha de comandobq. 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 isso não for especificado, 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 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 query específica do comando --use_legacy_sql está definida como false para tornar o SQL padrão 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 da forma como você executaria um comando da ferramenta de linha de comando gcloud. 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'

Exemplos

É possível encontrar exemplos de linha de comando na seção Guias de instruções na documentação do BigQuery. Abaixo, há links para tarefas comuns de linha de comando, 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 :

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:

Listagem de recursos

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

Como atualizar recursos

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

Carregando dados

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

Como consultar dados

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

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:

Exportação de dados

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

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: