Guia de início rápido para usar a ferramenta de linha de comando bq

Nesta página, explicamos como usar a ferramenta de linha de comando bq para executar consultas e carregar dados.

Antes de começar

Antes de começar este guia de início rápido, use 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 Cloud, na página do seletor de projetos, selecione ou crie um projeto do Cloud.

    Acessar 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 preexistente, clique no botão abaixo. Ative a API BigQuery.

    Ative a API

  5. Se 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 deste tópico mesmo que seu projeto não tenha o faturamento ativado. Se quiser ativá-lo, consulte Saiba como ativar o faturamento.

Examinar uma tabela

O BigQuery oferece várias tabelas de exemplo para consulta. Neste guia de início rápido, você executa algumas consultas na tabela shakespeare, que contém uma entrada para cada palavra em cada reprodução de Shakespeare.

Para examinar o esquema de uma tabela específica, execute o comando a seguir. Se os IDs do projeto e do conjunto de dados forem os valores padrão da ferramenta bq, será possível omitir os IDs do projeto e do conjunto de dados.

bq show PROJECT_ID:DATASET_ID.TABLE_ID

Neste exemplo, a tabela shakespeare é examinada no conjunto de dados samples:

bq show bigquery-public-data:samples.shakespeare

Saída:

Table bigquery-public-data:samples.shakespeare

   Last modified                  Schema                 Total Rows   Total Bytes   Expiration
 ----------------- ------------------------------------ ------------ ------------- ------------
  26 Aug 14:43:49   |- word: string (required)           164656       6432064
                    |- word_count: integer (required)
                    |- corpus: string (required)
                    |- corpus_date: integer (required)

Executar o comando de ajuda

Use bq help para ver informações detalhadas sobre a ferramenta de linha de comando bq.

bq help

Inclua um nome de comando para receber informações sobre ele. Por exemplo, veja informações sobre o comando query com a seguinte chamada ao comando bq help:

bq help query

Execute uma consulta

Execute uma consulta para saber quantas vezes a substring raisin aparece nas obras de Shakespeare.

Para realizar uma consulta, execute o comando bq query "SQL_STATEMENT".

  • Dentro do SQL_STATEMENT, evite o uso das aspas simples utilizando \.

  • Uma outra opção é usar um tipo diferente de aspas: ", em vez de '.

A consulta SQL padrão a seguir faz uma contagem de palavras pelo número de vezes em que a substring raisin aparece em todas as obras de Shakespeare.

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'

Saída:

Waiting on job_dcda37c0bbed4c669b04dfd567859b90 ... (0s) Current status:
DONE
+---------------+-------+
|     word      | count |
+---------------+-------+
| Praising      |   4   |
| raising       |   5   |
| raisins       |   1   |
| praising      |   8   |
| dispraising   |   2   |
| dispraisingly |   1   |
+---------------+-------+

Quando você procura uma palavra que não aparece nas obras de Shakespeare, nenhum resultado é retornado. Por exemplo, a pesquisa a seguir para huzzah não retorna correspondências.

bq query --use_legacy_sql=false \
'SELECT
  word
FROM
  `bigquery-public-data`.samples.shakespeare
WHERE
  word = "huzzah"'

Saída:

Waiting on job_e19 ... (4s) Current status: DONE
$

Criar uma tabela

Agora, crie sua tabela. Toda tabela fica armazenada dentro de um conjunto de dados, que é um grupo de recursos como tabelas e visualizações.

Etapa 1: fazer o download dos dados de exemplo

Os dados personalizados contêm aproximadamente 7 MB de dados sobre nomes conhecidos de bebês e são fornecidos pela Administração do Seguro Social dos EUA.

  1. Fazer o download do arquivo ZIP com nomes de bebês

  2. Extraia o arquivo:

    O arquivo ZIP contém um arquivo readme que descreve o esquema do conjunto de dados. Saiba mais sobre o conjunto de dados (em inglês).

  3. Abra o arquivo yob2010.txt para ver como ele é. Trata-se de um arquivo CSV com três colunas: nome, sexo (M ou F) e número de crianças com esse nome. O arquivo não tem linha de cabeçalho.

  4. Para executar os comandos com a ferramenta de linha de comando bq, copie ou mova o arquivo yob2010.txt para o diretório que você está usando.

Etapa 2: criar um conjunto de dados

  1. Use o comando bq ls para ver se há algum conjunto de dados no seu projeto padrão.

    bq ls

    Exemplo de saída:

      datasetId
     -------------
      olddataset
  2. Execute bq ls novamente para listar os conjuntos de dados em um projeto específico. Basta incluir o ID do projeto seguido por dois-pontos (:). No exemplo a seguir, são listados os conjuntos de dados do projeto publicdata.
    bq ls publicdata:

    Saída:

      datasetId
     -----------
      samples
  3. Use o comando bq mk para criar um novo conjunto de dados chamado babynames no seu projeto padrão. Para o nome desse conjunto, há um limite de 1.024 caracteres. Use letras de A a Z (maiúsculas ou minúsculas), números de 0 a 9 e sublinhados, mas o nome não pode começar com número ou sublinhado nem incluir espaços.
    bq mk babynames

    Exemplo de saída:

    Dataset 'myprojectid:babynames' successfully created.
  4. Execute bq ls para confirmar que agora o conjunto de dados aparece como parte do projeto padrão:
    bq ls

    Exemplo de saída:

      datasetId
     -------------
      olddataset
      babynames

Etapa 3: carregar a tabela

Com o comando bq load, você cria ou atualiza uma tabela e carrega os dados dela em uma só etapa.

  1. Execute o comando bq load para carregar o arquivo de origem em uma nova tabela chamada names2010 no conjunto de dados babynames que você criou. Por padrão, esse comando é executado de forma síncrona e leva alguns segundos para ser concluído.

    bq load babynames.names2010 yob2010.txt name:string,gender:string,count:integer

    Argumentos do comando bq load:

    • datasetID: babynames.
    • tableID: names2010.
    • source: yob2010.txt: se necessário, inclua o caminho completo para o arquivo.
    • schema: name:string,gender:string,count:integer.

    Exemplo de saída:

    Waiting on job_4f0c0878f6184119abfdae05f5194e65 ... (35s) Current status: DONE
  2. Execute bq ls para confirmar que a tabela agora aparece no conjunto de dados:

    bq ls babynames

    Saída:

       tableId    Type
     ----------- -------
      names2010   TABLE
    
  3. Execute bq show para ver o esquema:

    bq show babynames.names2010

    Saída:

    Table myprojectid:babynames.names2010
    
       Last modified         Schema         Total Rows   Total Bytes   Expiration
     ----------------- ------------------- ------------ ------------- ------------
      13 Mar 15:31:00   |- name: string     34041        653855
                        |- gender: string
                        |- count: integer
    

Por padrão, quando você carrega dados no BigQuery, espera-se que eles estejam no formato UTF-8. Caso você tenha dados na codificação ISO-8859-1 (ou Latin-1) e você esteja tendo problemas com ele, diga ao BigQuery para tratar seus dados como Latin-1 usando a sinalização-E. Para ver mais informações, consulte Codificação.

Etapa 4: executar consultas

  1. Execute o seguinte comando para retornar os nomes mais populares de meninas:

    bq query "SELECT name,count FROM babynames.names2010 WHERE gender = 'F' ORDER BY count DESC LIMIT 5"

    Saída:

    Waiting on job_58c0f5ca52764ef1902eba611b71c651 ... (0s) Current status: DONE
    +----------+-------+
    |   name   | COUNT |
    +----------+-------+
    | Isabella | 22731 |
    | Sophia   | 20477 |
    | Emma     | 17179 |
    | Olivia   | 16860 |
    | Ava      | 15300 |
    +----------+-------+
    
  2. Execute o comando a seguir para ver os nomes mais incomuns de meninos. A contagem mínima é 5, porque os nomes com menos de 5 ocorrências não são exibidos nos dados de origem.
    bq query "SELECT name,count FROM babynames.names2010 WHERE gender = 'M' ORDER BY count ASC LIMIT 5"

    Saída:

    Waiting on job_556ba2e5aad340a7b2818c3e3280b7a3 ... (1s) Current status: DONE
    +----------+-------+
    |   name   | COUNT |
    +----------+-------+
    | Aarian   |     5 |
    | Aaidan   |     5 |
    | Aamarion |     5 |
    | Aadhavan |     5 |
    | Aaqib    |     5 |
    +----------+-------+
    

Limpar

Para evitar cobranças na conta do Google Cloud pelos recursos usados neste guia de início rápido, siga estas etapas.

  1. Execute o comando bq rm para remover o conjunto de dados babynames. Em seguida, use a sinalização -r para excluir todas as tabelas do conjunto de dados, inclusive a names2010.

    bq rm -r babynames
    
  2. Digite y para confirmar o comando de exclusão.

A seguir