Explore a ferramenta de linhas de comando bq

A ferramenta de linhas de comando bq é uma ferramenta de linhas de comando baseada em Python para o BigQuery. Esta página contém informações gerais sobre a utilização da ferramenta de linhas de comando bq.

Para uma referência completa de todos os comandos e sinalizadores bq, consulte a referência da ferramenta de linhas de comando bq.

Antes de começar

Antes de poder usar a ferramenta de linhas de comando bq, tem de usar a Google Cloud consola 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.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

    4.
  4. O BigQuery é ativado automaticamente em novos projetos. Para ativar o BigQuery num projeto pré-existente, aceda a

    Enable the BigQuery API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. Opcional: Ative a faturação para o projeto. Se não quiser ativar a faturação nem fornecer um cartão de crédito, os passos neste documento continuam a funcionar. O BigQuery oferece-lhe um sandbox para realizar os passos. Para mais informações, consulte o artigo Ative o sandbox do BigQuery.

    6. Introduzir comandos bq no Cloud Shell

    Pode introduzir comandos da ferramenta de linha de comandos bq na Cloud Shell a partir da Google Cloud consola ou da CLI do Google Cloud.

    Sinalizações e argumentos de posicionamento

    A ferramenta de linhas de comando bq suporta dois tipos de sinalizadores:

    • Os sinalizadores globais podem ser usados em todos os comandos.
    • As flags específicas do comando aplicam-se a um comando específico.

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

    Coloque quaisquer sinalizadores globais antes do comando bq e, em seguida, inclua sinalizadores específicos do comando. Pode incluir várias flags globais ou específicas de comandos. Por exemplo:

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

    Pode especificar argumentos de comando das seguintes formas:

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

    Substitua o seguinte:

    • FLAG: uma marca global ou específica do comando
    • ARGUMENT: o argumento da flag

    Alguns comandos requerem a utilização de aspas simples ou duplas em torno dos argumentos. Isto é frequentemente verdade quando o argumento contém espaços, vírgulas ou outros carateres especiais. Por exemplo:

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

    As flags com valores booleanos podem ser especificadas sem um argumento. Se especificar true ou false, tem de usar o formato FLAG=ARGUMENT.

    Por exemplo, este comando especifica falso 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'

    Em alternativa, para especificar false como o argumento da flag, pode introduzir o seguinte:

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

    Executar consultas a partir da ferramenta de linhas de comando bq

    Para executar uma consulta que desenvolveu na Google Cloud consola a partir da ferramenta de linhas de comando bq, faça o seguinte:

    1. Inclua a consulta num comando bq query da seguinte forma: bq query --use_legacy_sql=false 'QUERY'. Substitua QUERY pela consulta.

    2. Formate a string de consulta.

      Se precisar de usar literais de string adicionais na consulta, tem de seguir as regras de colocação entre aspas da shell que está a usar, como o Bash ou o PowerShell.

      O exemplo seguinte mostra uma abordagem típica no Bash, que consiste em usar aspas duplas para indicar os literais de string na consulta e, em seguida, incluir a própria consulta entre aspas simples:

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

      Se estiver a copiar a consulta de outra localização, também tem de remover todos os comentários na consulta.

      Por exemplo, transforme a seguinte Google Cloud consulta da consola:

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

      numa consulta da ferramenta de linhas de comando bq da seguinte forma:

      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 o artigo Executar tarefas de consulta interativas e em lote.

    Obter ajuda

    Para obter ajuda para a ferramenta de linhas de comando bq, pode introduzir os seguintes comandos:

    • Para a versão instalada da ferramenta de linhas de comando bq, introduza bq version.
    • Para ver uma lista completa de comandos, introduza bq help.
    • Para ver uma lista de flags globais, introduza bq --help.
    • Para obter ajuda com um comando específico, introduza bq help COMMAND.
    • Para obter ajuda com um comando específico, além de uma lista de flags globais, introduza bq COMMAND --help.

    Substitua COMMAND pelo comando com o qual precisa de ajuda.

    Definir valores predefinidos para sinalizadores da linha de comandos

    Pode definir valores predefinidos para sinalizadores da linha de comandos, incluindo-os no ficheiro de configuração da ferramenta de linha de comandos bq, .bigqueryrc. Antes de configurar as opções predefinidas, tem de criar primeiro um ficheiro .bigqueryrc. Pode usar o seu editor de texto preferido para criar o ficheiro. Depois de criar o ficheiro .bigqueryrc, pode especificar o caminho para o ficheiro através da flag global --bigqueryrc.

    Se a flag --bigqueryrc não for especificada, é usada a variável de ambiente BIGQUERYRC. Se não for especificado, é usado o caminho ~/.bigqueryrc. O caminho predefinido é $HOME/.bigqueryrc.

    Adicionar sinalizações a .bigqueryrc

    Para adicionar valores predefinidos para flags de linha de comandos a .bigqueryrc:

    • Coloque indicadores globais na parte superior do ficheiro sem um cabeçalho.
    • Para sinalizadores específicos de comandos, introduza o nome do comando (entre parênteses) e adicione os sinalizadores específicos de comandos (um por linha) após o nome do comando.

    Por 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 valores predefinidos para as seguintes flags:

    • A flag global --apilog está definida como stdout para imprimir a saída de depuração na consolaGoogle Cloud .
    • O sinalizador global --format está definido como prettyjson para apresentar a saída do comando num formato JSON legível.
    • A flag global --location está definida para a localização de várias regiões US.

    • O sinalizador específico do comando query está definido como --use_legacy_sql para tornar o GoogleSQL a sintaxe de consulta predefinida.false

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

    • O comando específico da flag query está definido para 10 000 000 bytes (10 MB) para falhar as consultas que leiam mais de 10 MB de dados.--maximum_bytes_billed

    • O sinalizador específico do comando load--destination_kms_key está definido como projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey.

    Executar a ferramenta de linhas de comando bq num shell interativo

    Pode executar a ferramenta de linhas de comando bq numa shell interativa onde não precisa de prefixar os comandos com bq. Para iniciar o modo interativo, introduza bq shell. Depois de iniciar a shell, o comando muda para o ID do seu projeto predefinido. Para sair do modo interativo, introduza exit.

    Executar a ferramenta de linhas de comando bq num script

    Pode executar a ferramenta de linhas de comando bq num script, tal como executaria um comando da CLI do Google Cloud. Segue-se um exemplo de comandos gcloud e bq num 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'

    Executar bq comandos a partir de uma conta de serviço

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

    Para começar a executar comandos do bq através da representação de contas de serviço, execute o seguinte comando:

    gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_NAME

    Substitua SERVICE_ACCOUNT_NAME pelo nome da sua conta de serviço.

    Os comandos bq que executar agora usam as credenciais da conta de serviço.

    Para parar de executar comandos bq a partir de uma conta de serviço, execute o seguinte comando:

    gcloud config unset auth/impersonate_service_account

    Exemplos

    Pode encontrar exemplos de linhas de comandos na secção Guias de instruções da documentação do BigQuery. Esta secção apresenta links para tarefas comuns de linha de comandos, como criar, obter, listar, eliminar e modificar recursos do BigQuery.

    Criar recursos

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

    Para ver exemplos de como criar uma tabela com um ficheiro de dados, consulte o artigo Carregar dados.

    Obter informações sobre recursos

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

    Recursos da ficha

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

    Anunciar empregos

    Para ver informações sobre como usar a ferramenta de linhas de comando bq para listar tarefas, consulte o seguinte:

    A atualizar recursos

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

    Carregar dados

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

    Consultar dados

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

    Usar origens de dados externas

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

    Exportar dados

    Para obter informações sobre a utilização da ferramenta de linhas de comando bq para exportar dados, consulte o seguinte:

    Usar o Serviço de transferência de dados do BigQuery

    Para obter informações sobre a utilização da ferramenta de linha de comandos bq com o Serviço de transferência de dados do BigQuery, consulte o seguinte:

    Resolução de problemas da ferramenta de linhas de comando bq

    Esta secção mostra-lhe como resolver problemas com a ferramenta de linhas de comando bq.

    Mantenha a CLI gcloud atualizada

    Se estiver a usar a ferramenta de linha de comandos bq da CLI gcloud do Google Cloud, certifique-se de que tem a funcionalidade e as correções mais recentes para a ferramenta de linha de comandos bq, mantendo a instalação da CLI gcloud atualizada. Para ver se está a executar a versão mais recente da CLI gcloud, introduza o seguinte comando no Cloud Shell:

    gcloud components list

    As duas primeiras linhas do resultado apresentam o número da versão da instalação atual da CLI gcloud e o número da versão da CLI gcloud mais recente. Se descobrir que a sua versão está desatualizada, pode atualizar a instalação da CLI gcloud para a versão mais recente introduzindo o seguinte comando no Cloud Shell:

    gcloud components update

    Depuração

    Pode introduzir os seguintes comandos para depurar a ferramenta de linhas de comando bq:

    • Veja os pedidos enviados e recebidos. Adicione a flag --apilog=PATH_TO_FILE para guardar um registo de operações num ficheiro local. Substitua PATH_TO_FILE pelo caminho onde quer guardar o registo. A ferramenta de linhas de comando bq funciona fazendo chamadas de API baseadas em REST padrão, que podem ser úteis para ver. Também é útil anexar este registo quando comunica problemas. A utilização de - ou stdout em vez de um caminho imprime o registo na consola Google Cloud . A definição de --apilog como stderr envia a saída para o ficheiro de erro padrão. Para registar mais pedidos, use a flag --httplib2_debuglevel=LOG_LEVEL. Um nível LOG_LEVEL regista mais informações sobre os pedidos http.

    • Resolva problemas de erros. Introduza a flag --format=prettyjson quando obtiver o estado de uma tarefa ou quando vir informações detalhadas sobre recursos, como tabelas e conjuntos de dados. A utilização desta flag gera a resposta no formato JSON, incluindo a propriedade reason. Pode usar a propriedade reason para procurar os passos de resolução de problemas. Para mais informações sobre erros durante a execução, use a flag --debug_mode.