Como usar a ferramenta de linha de comando bq

bq é uma ferramenta de linha de comando baseada em Python para o BigQuery. Nesta página, fornecemos informações gerais sobre o uso da bq.

Para ver uma lista completa de todos os comandos e sinalizações da bq, consulte a referência da ferramenta de linha de comando bq.

Antes de começar

Antes de utilizar a ferramenta de linha de comando do BigQuery, é preciso usar o Console do Google Cloud Platform para criar ou selecionar um projeto e instalar o SDK do Cloud.

  1. Faça login na sua Conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. Selecione ou crie um projeto do Google Cloud Platform.

    Acessar a página Gerenciar recursos

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

    Ativar 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 neste 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.

Uso geral

Posicionamento da sinalização

A bq é compatível com dois tipos de sinalizações: globais e de comando. Elas precisam ser usadas na ordem mostrada aqui:

bq --global_flag argument bq_command --command-specific_flag argument
  • Sinalizações globais (ou comuns) podem ser usadas em todos os comandos.
  • Sinalizações específicas para o comando se aplicam a um determinado comando.

Separe várias sinalizações globais ou específicas de comandos usando um espaço. Por exemplo:

bq \
--global_flag argument \
--global_flag argument \
bq_command \
--command-specific_flag argument \
--command-specific_flag argument

Para especificar argumentos de comando, siga um destes métodos:

  • --flag=argument
  • --flag='argument'
  • --flag="argument"
  • --flag argument
  • --flag 'argument'
  • --flag "argument"

Cada um deles é usado em toda a documentação do BigQuery.

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 especificar =argument.

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

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

É possível também especificar false como argumento da sinalização. Basta usar:

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

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

Como receber ajuda

Insira os seguintes comandos para receber ajuda sobre a ferramenta de linha de comando bq:

  • Para a versão instalada do bq, insira bq version.
  • Para uma lista completa de comandos, insira bq help.
  • Para uma lista de sinalizações globais, insira bq --help.
  • Para receber ajuda sobre um comando específico, insira bq help command.
  • Para receber ajuda sobre um comando específico e uma lista de sinalizações globais, insira bq command --help.

Como fazer a depuração

Você pode inserir os seguintes comandos para depurar bq:

  • Para ver as solicitações enviadas e recebidas
    Adicione a sinalização --apilog=path_to_file para salvar um registro de operações em um arquivo local. bq faz 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 de arquivo imprimirá o registro no console. Configurar --apilog como stderr resulta no arquivo de erro padrão.
  • Para ajudar a solucionar erros
    Insira a sinalização --format=prettyjson ao receber o status de um job ou visualizar informações detalhadas sobre recursos como tabelas e conjuntos de dados. O uso dessa sinalização gera a resposta no formato JSON, incluindo a propriedade reason. Use a propriedade reason para pesquisar as 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 da ferramenta de linha de comando .bigqueryrc. Antes de configurar suas opções padrão, primeiro crie um arquivo .bigqueryrc. Você pode 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.

Como adicionar sinalizações ao .bigqueryrc

Veja como adicionar valores padrão para sinalizadores de linha de comando ao .bigqueryrc:

command
--command-specific_flag=argument
--command-specific_flag=argument

Quando você insere uma sinalização de linha de comando no .bigqueryrc, é preciso especificar o argumento dela no seguinte formato =argument.

.bigqueryrc é lido toda vez que você executa bq. Por isso, as mudanças são atualizadas imediatamente. Quando você executa "bq" no modo interativo (bq shell), é necessário reiniciar o shell para que as mudanças entrem em vigor.

Exemplo

Este exemplo define valores padrão para as seguintes sinalizações globais:

  • --apilog está configurado como stdout para imprimir a saída de depuração no console.
  • --format é configurado como prettyjson para exibir a saída do comando em um formato JSON legível por humanos.
  • --location é definido como a multirregião US.

Este exemplo define valores padrão para as seguintes sinalizações específicas do comando query:

  • --use_legacy_sql é definido como false para tornar o SQL padrão a sintaxe de consulta padrão.

  • --max_rows é definido como 100 para controlar o número de linhas na saída da consulta.

  • --maximum_bytes_billed é definido como 10.000.000 de bytes (10 MB) para consultas com falha que leem mais de 10 MB de dados.

Este exemplo define um valor padrão para a seguinte sinalização específica do comando load:

  • --destination_kms_key é definido como projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey.
credential_file = path_to_credential_file
--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

Para confirmar suas configurações, digite o seguinte comando:

cat ~/.bigqueryrc

Como executar bq em um shell interativo

Você pode executar o bq em um shell interativo em que não é preciso prefixar os comandos com bq. Para iniciar o modo interativo, digite bq shell. Após o lançamento do shell, o prompt muda para o código do seu projeto padrão. Para sair do modo interativo, digite exit.

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.

Como criar recursos

Para saber informações sobre como usar a ferramenta de linha de comando 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 para encontrar informações sobre recursos, consulte:

Como listar recursos

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

Como atualizar recursos

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

Como carregar dados

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

Como consultar dados

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

Como usar fontes de dados externas

Para encontrar informações sobre como usar a ferramenta de linha de comando para consultar dados em fontes de dados externas, veja:

Como exportar dados

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

Como usar o BigQuery Data Transfer Service

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

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.