Como usar a ferramenta de linha de comando bq

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 referência da ferramenta de linha de comando .

Antes de começar

Antes de usar a ferramenta de linha de comando do BigQuery, 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.

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

  2. No Console do GCP, na página do seletor de projetos, selecione ou crie um projeto do GCP.

    Acesse a página do 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 já existente, acesse Ative a(s) BigQuery API necessária(s).

    Ativar a(s) API

  5. Se você não quiser informar um cartão de crédito ou ativar o faturamento do seu projeto, use o sandbox fornecido pelo BigQuery. É 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

bq suporta dois tipos de sinalizações: sinalizadores globais e sinalizadores 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 para o comando 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, deverá especificar =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:

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

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.

Como receber ajuda

Você pode inserir os seguintes comandos para obter ajuda para a ferramenta de linha de comando bq:

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

Depuração

Você pode digitar 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 funciona fazendo chamadas de API baseadas em REST padrão, que podem ser úteis para ver. 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. Definindo --apilog a stderr saídas para o arquivo de erro padrão.
  • Para ajudar a solucionar 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 os sinalizadores de linha de comando incluindo-os no arquivo de configuração da ferramenta de linha de comando - .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 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:

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

Quando você insere sinalizações de linha de comando em .bigqueryrc, você deve especificar o argumento da sinalização no seguinte formato =argument.

.bigqueryrc é lido sempre que você executa bq, então as alterações devem ser atualizadas imediatamente. Ao executar o bq no modo interativo (bq shell), você deve reiniciar o shell para que as alterações entrem em vigor.

Exemplo

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

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

Este exemplo define valores padrão para os seguintes sinalizadores específicos de comando query:

  • --use_legacy_sql está 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 bytes (10 MB) para falhas em consultas que leem mais de 10 MB de dados.

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

  • --destination_kms_key está definida 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

Gerando bq em um shell interativo

Você pode gerar bq em um shell interativo que não solicite os comandos com prefixados. 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.

Exemplos

É possível encontrar exemplos de linha de comando na seção Guias de instruções da 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 encontrar 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 os 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 os 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, consulte:

Como exportar dados

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

Como usar o serviço de transferência de dados do BigQuery

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