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 relação completa de todos os comandos e sinalizações do bq, consulte a referência da ferramenta de linha de comando.

Antes de começar

Antes de utilizar a ferramenta de linha de comando do BigQuery, você precisa usar o Console do Google Cloud Platform para criar ou selecionar um projeto e ativar o faturamento. Além disso, é necessário instalar o SDK do Google 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 GCP.

    Acessar a página Gerenciar recursos

  3. Verifique se o faturamento foi ativado para o projeto.

    Saiba como ativar o faturamento

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

    Ativar a API

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

O bq é compatível com dois tipos de sinalizadores: globais e de comando. Eles precisam ser usados na ordem mostrada aqui:

    bq --global_flag [ARGUMENT] bq_command --command-specific_flag [ARGUMENT]
  • Sinalizadores globais (ou comuns) podem ser usados em todos os comandos.
  • Sinalizadores específicos para o comando se aplicam a um determinado comando.

Separe vários sinalizadores globais ou específicos 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`'

Sinalizadores 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 o sinalizador booleano --use_legacy_sql colocando no na frente do sinalizador:

bq query --nouse_legacy_sql 'select count(*) from `bigquery-public-data.samples.shakespeare`'

Você também pode especificar false como argumento do sinalizador. Basta usar:

bq query --use_legacy_sql=false 'select count(*) from `bigquery-public-data.samples.shakespeare`'

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.

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.

Depuração

Você pode inserir os seguintes comandos para depurar bq:

  • Para ver as solicitações enviadas e recebidas
    Adicione o sinalizador --apilog=[PATH_TO_FILE] para salvar um registro de operações em um arquivo local. bq trabalha fazendo chamadas de API padrão baseadas em REST, que podem ser úteis para visualização. Também é útil 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 desse sinalizador 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 sinalizadores de linha de comando

Você pode definir valores padrão para os sinalizadores de linha de comando incluindo-os 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 o sinalizador global --bigqueryrc.

Se o sinalizador --bigqueryrc não for especificado, 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

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

  • Coloque sinalizações globais na parte superior do arquivo sem um cabeçalho
  • Para sinalizações específicas do comando, insira o nome do comando (entre parênteses) e adicione essas sinalizações (uma por linha) abaixo dele no seguinte formato:

    [COMMAND]
    --command-specific_flag=[ARGUMENT]
    --command-specific_flag=[ARGUMENT]
    

Quando você insere sinalizações de linha de comando no .bigqueryrc, é preciso especificar o argumento da sinalização no seguinte formato =[ARGUMENT].

.bigqueryrc é lido toda vez que você executa bq. Por isso, as mudanças são atualizadas imediatamente. Quando você executa o 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 os seguintes sinalizadores 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 dos US.

Este exemplo define valores padrão para os seguintes sinalizadores específicos 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.