Como usar o BigQuery com Node.js

1. Visão geral

O BigQuery é o data warehouse de análise de baixo custo, totalmente gerenciado e com escala em petabyte, desenvolvido pelo Google. O BigQuery é NoOps. Não há infraestrutura para gerenciar, e você não precisa de um administrador de banco de dados. Assim, é possível se concentrar na análise de dados para encontrar insights significativos, usar um SQL conhecido e aproveitar nosso modelo de pagamento por uso.

Neste codelab, você vai usar a biblioteca de cliente do Google Cloud BigQuery para consultar conjuntos de dados públicos do BigQuery com Node.js.

O que você vai aprender

• Como usar o Cloud Shell
• Como ativar a API BigQuery
• Como autenticar solicitações de API
• Como instalar a biblioteca de cliente do BigQuery para Node.js
• Como consultar as obras de Shakespeare
• Como consultar o conjunto de dados do GitHub
• Como ajustar o armazenamento em cache e mostrar estatísticas

O que é necessário

• Um projeto do Google Cloud Platform
• Um navegador, como o Chrome ou o Firefox
• Familiaridade com o uso do Node.js

Pesquisa

Como você vai usar este tutorial?

Apenas leitura Leitura e exercícios

Como você classificaria sua experiência com o Node.js?

Iniciante Intermediário Proficiente

Como você classificaria sua experiência com o uso dos serviços do Google Cloud Platform?

Iniciante Intermediário Proficiente

2. Configuração e requisitos

Configuração de ambiente autoguiada

1. Faça login no Console do Cloud e crie um novo projeto ou reutilize um existente. Crie uma se você ainda não tiver uma conta do Gmail ou do G Suite.

Observação: para acessar facilmente o console do Cloud, basta memorizar o URL, que é console.cloud.google.com.

Lembre-se do código do projeto, um nome exclusivo em todos os projetos do Google Cloud. O nome acima já foi escolhido e não servirá para você. Faremos referência a ele mais adiante neste codelab como PROJECT_ID.

Observação: se você estiver usando uma conta do Gmail, deixe o local padrão definido como Sem organização. Se você estiver usando uma conta do G Suite, escolha um local adequado à sua organização.

2. Em seguida, será necessário ativar o faturamento no Console do Cloud para usar os recursos do Google Cloud.

A execução deste codelab não será muito cara, se for o caso. Siga todas as instruções na seção "Limpeza", que orienta você sobre como encerrar recursos para não incorrer em cobranças além deste tutorial. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.

Inicie o Cloud Shell

Embora a ferramenta de linha de comando do SDK Cloud possa ser operada remotamente do seu laptop, neste codelab você vai usar o Google Cloud Shell, um ambiente de linha de comando executado na nuvem.

Ativar o Cloud Shell

1. No Console do Cloud, clique em Ativar o Cloud Shell.

Se você nunca iniciou o Cloud Shell, vai ver uma tela intermediária abaixo da dobra com a descrição dele. Se esse for o caso, clique em Continuar e você não a verá novamente. Esta é a aparência dessa tela única:

Leva apenas alguns instantes para provisionar e se conectar ao Cloud Shell.

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Praticamente todo o seu trabalho neste codelab pode ser feito em um navegador ou no seu Chromebook.

Depois de se conectar ao Cloud Shell, você já estará autenticado e o projeto já estará configurado com seu ID do projeto.

2. Execute o seguinte comando no Cloud Shell para confirmar que você está autenticado:

gcloud auth list

Resposta ao comando

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Observação: a ferramenta de linha de comando gcloud é a poderosa e unificada do Google Cloud. Ela vem pré-instalado no Cloud Shell. Essa ferramenta aceita preenchimento com tabulação. Para mais informações, consulte a visão geral da ferramenta de linha de comando gcloud.

gcloud config list project

Resposta ao comando

[core]
project = <PROJECT_ID>

Se o projeto não estiver configurado, configure-o usando este comando:

gcloud config set project <PROJECT_ID>

Resposta ao comando

Updated property [core/project].

3. Ative a API BigQuery

A API BigQuery deve estar ativada por padrão em todos os projetos do Google Cloud. Para verificar se isso é verdade, execute o seguinte comando no Cloud Shell:

gcloud services list

O BigQuery vai aparecer na lista:

NAME                              TITLE
bigquery-json.googleapis.com      BigQuery API
...

Se a API BigQuery não estiver ativada, use o seguinte comando no Cloud Shell para ativá-la:

gcloud services enable bigquery-json.googleapis.com

Observação: se esse comando for exibido como erro, verifique se o ID do projeto atual corresponde ao ID do projeto do codelab.

Use o seguinte comando para encontrar o ID do projeto atual que está sendo usado pelo Cloud Shell:

gcloud info | grep "project"

Se o ID do projeto não estiver correto, use o seguinte comando para usá-lo:

gcloud config set project <PROJECT_ID>

Substitua <PROJECT_ID> pelo ID do projeto correto.

4. Autenticar as solicitações de API

Para fazer solicitações à API BigQuery, você precisa usar uma conta de serviço. Uma conta de serviço pertence ao seu projeto. Ela é usada pela biblioteca de cliente Node.js do Google BigQuery para fazer solicitações da API BigQuery. Como qualquer outra conta de usuário, uma conta de serviço é representada por um endereço de e-mail. Nesta seção, você vai usar o SDK Cloud para criar uma conta de serviço e, em seguida, criar as credenciais necessárias para realizar a autenticação.

Primeiro, defina uma variável de ambiente com seu PROJECT_ID para usar neste codelab:

export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value core/project)

Em seguida, crie uma conta de serviço para acessar a API BigQuery usando:

gcloud iam service-accounts create my-bigquery-sa --display-name "my bigquery codelab service account"

Em seguida, crie credenciais que o código Node.js vai usar para fazer login como a nova conta de serviço. Crie e salve essas credenciais como um arquivo JSON "~/key.json" usando o seguinte comando:

gcloud iam service-accounts keys create ~/key.json --iam-account  my-bigquery-sa@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com

Por fim, defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS, que é usada pela biblioteca C# da API BigQuery, abordada na próxima etapa, para encontrar suas credenciais. A variável de ambiente deve ser definida para o caminho completo do arquivo JSON de credenciais que você criou. Defina a variável de ambiente usando o seguinte comando:

export GOOGLE_APPLICATION_CREDENTIALS="/home/${USER}/key.json"

Saiba mais sobre autenticar a API BigQuery.

5. Configurar o controle de acesso

O BigQuery usa o Identity and Access Management (IAM) para gerenciar o acesso aos recursos. O BigQuery tem vários papéis predefinidos (usuário, dataOwner, dataViewer etc.) que podem ser atribuídos à conta de serviço criada na etapa anterior. Saiba mais sobre o controle de acesso na documentação do BigQuery.

Antes de consultar os conjuntos de dados públicos, verifique se a conta de serviço tem pelo menos o papel bigquery.user. No Cloud Shell, execute o comando a seguir para atribuir o papel bigquery.user à conta de serviço:

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} --member "serviceAccount:my-bigquery-sa@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" --role "roles/bigquery.user"

Execute o comando a seguir para verificar se a conta de serviço tem a função de usuário atribuída:

gcloud projects get-iam-policy $GOOGLE_CLOUD_PROJECT

6. Instale a biblioteca de cliente do BigQuery para Node.js

Primeiro, crie uma pasta BigQueryDemo e navegue até ela:

mkdir BigQueryDemo
cd BigQueryDemo

Em seguida, crie um projeto Node.js que será usado para executar exemplos da biblioteca de cliente do BigQuery:

npm init -y

O projeto Node.js criado vai aparecer:

{
  "name": "BigQueryDemo",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Instale a biblioteca de cliente do BigQuery:

 npm install --save @google-cloud/bigquery

npm notice created a lockfile as package-lock.json. You should commit this file.
npm WARN BigQueryDemo@1.0.0 No description
npm WARN BigQueryDemo@1.0.0 No repository field.
+ @google-cloud/bigquery@2.1.0
added 69 packages from 105 contributors and audited 147 packages in 4.679s
found 0 vulnerabilities

Agora você pode usar a biblioteca de cliente Node.js do BigQuery.

7. Consultar as obras de Shakespeare

Um conjunto de dados público é qualquer conjunto de dados armazenado no BigQuery e disponibilizado para o público em geral. Há muitos outros conjuntos de dados públicos disponíveis para consulta, alguns deles também hospedados pelo Google, mas muitos outros hospedados por terceiros. Leia mais na página Conjuntos de dados públicos.

Além dos conjuntos de dados públicos, o BigQuery oferece um número limitado de tabelas de amostra que podem ser consultadas. Essas tabelas ficam no bigquery-public-data:samples dataset. Uma dessas tabelas se chama shakespeare. e contém um índice de palavras das obras de Shakespeare com o número de vezes que cada palavra aparece em cada acervo.

Nesta etapa, você vai consultar a tabela "shakespeare".

Observação:confira os detalhes da tabela "shakespeare" no console do BigQuery aqui.

Primeiro, abra o editor de código no canto superior direito do Cloud Shell:

Crie um arquivo queryShakespeare.js na pasta BigQueryDemo :

 touch queryShakespeare.js

Navegue até o arquivo queryShakespeare.js e insira o seguinte código:

'use strict';

function main() {

    // Import the Google Cloud client library
    const {BigQuery} = require('@google-cloud/bigquery');

    async function queryShakespeare() {
    // Queries a public Shakespeare dataset.

        // Create a client
        const bigqueryClient = new BigQuery();

        // The SQL query to run
        const sqlQuery = `SELECT word, word_count
            FROM \`bigquery-public-data.samples.shakespeare\`
            WHERE corpus = @corpus
            AND word_count >= @min_word_count
            ORDER BY word_count DESC`;

        const options = {
        query: sqlQuery,
        // Location must match that of the dataset(s) referenced in the query.
        location: 'US',
        params: {corpus: 'romeoandjuliet', min_word_count: 250},
        };

        // Run the query
        const [rows] = await bigqueryClient.query(options);

        console.log('Rows:');
        rows.forEach(row => console.log(row));
    }

    queryShakespeare();
  }

main();

Reserve um ou dois minutos para estudar o código e ver como a tabela é consultada.

No Cloud Shell, execute o app:

node queryShakespeare.js

Uma lista de palavras e suas ocorrências vai aparecer:

Rows:
{ word: 'the', word_count: 614 }
{ word: 'I', word_count: 577 }
{ word: 'and', word_count: 490 }
{ word: 'to', word_count: 486 }
{ word: 'a', word_count: 407 }
{ word: 'of', word_count: 367 }
{ word: 'my', word_count: 314 }
{ word: 'is', word_count: 307 }
...

Observação:se esse código Node.js não funcionar para você, verifique as instruções realizadas na etapa Autenticar solicitações de API.

Use o comando a seguir para verificar o valor da variável de ambiente GOOGLE_APPLICATION_CREDENTIALS:

echo GOOGLE_APPLICATION_CREDENTIALS

Ele precisa gerar o valor "~/key.json".

Se sim, verifique se uma conta de serviço foi criada e está localizada em "~/key.json" usando:

cat "~/key.json"

Você verá algo como o seguinte:

{

"type": "service_account",

"project_id": "PROJECT_ID",

"private_key_id": "ff31939192529e07f42e4535fb20bb029def1276",

"Private_key":...

Caso contrário, volte à etapa Autenticar solicitações de API.

8. Consultar o conjunto de dados do GitHub

Para se familiarizar mais com o BigQuery, agora você vai executar uma consulta no conjunto de dados público do GitHub. Você encontra as mensagens de commit mais comuns no GitHub. Você também vai usar a interface da Web do BigQuery para visualizar e executar consultas ad hoc.

Para ver os dados, abra o conjunto de dados do GitHub na interface da Web do BigQuery:

https://console.cloud.google.com/bigquery?p=bigquery-public-data&d=github_repos&t=commits&page=table

Para conferir uma prévia rápida da aparência dos dados, clique na guia "Prévia":

Crie o arquivo queryGitHub.js na pasta BigQueryDemo:

 touch queryGitHub.js

Navegue até o arquivo queryGitHub.js e insira o seguinte código:

'use strict';

function main() {

    // Import the Google Cloud client library
    const {BigQuery} = require('@google-cloud/bigquery');


    async function queryGitHub() {
        // Queries a public GitHub dataset.

        // Create a client
        const bigqueryClient = new BigQuery();

        // The SQL query to run
        const sqlQuery = `SELECT subject AS subject, COUNT(*) AS num_duplicates
        FROM \`bigquery-public-data.github_repos.commits\`
        GROUP BY subject 
        ORDER BY num_duplicates 
        DESC LIMIT 10`;

        const options = {
        query: sqlQuery,
        // Location must match that of the dataset(s) referenced in the query.
        location: 'US',
        };

        // Run the query
        const [rows] = await bigqueryClient.query(options);

        console.log('Rows:');
        rows.forEach(row => console.log(`${row.subject}: ${row.num_duplicates}`));
    }
    
    queryGitHub();
}

main();

Reserve um ou dois minutos para estudar o código e ver como a tabela é consultada para as mensagens de commit mais comuns.

No Cloud Shell, execute o app:

node queryGitHub.js

Você vai ver uma lista de mensagens de commit e suas ocorrências:

Rows:
Update README.md: 2572220
: 1985733
Initial commit: 1940228
Mirroring from Micro.blog.: 646772
update: 592520
Update data.json: 548730
Update data.js: 548354
...

9. Armazenamento em cache e estatísticas

Quando você executa uma consulta, o BigQuery armazena os resultados em cache. Como resultado, as consultas idênticas subsequentes levam muito menos tempo. É possível desativar o armazenamento em cache usando as opções de consulta. O BigQuery também acompanha algumas estatísticas sobre as consultas, como hora de criação, hora de término e total de bytes processados.

Nesta etapa, você vai desativar o armazenamento em cache e mostrar algumas estatísticas sobre as consultas.

Navegue até o arquivo queryShakespeare.js dentro da pasta BigQueryDemo e substitua o código pelo seguinte:

'use strict';

function main() {

    // Import the Google Cloud client library
    const {BigQuery} = require('@google-cloud/bigquery');

    async function queryShakespeareDisableCache() {
        // Queries the Shakespeare dataset with the cache disabled.

        // Create a client
        const bigqueryClient = new BigQuery();

        const sqlQuery = `SELECT word, word_count
            FROM \`bigquery-public-data.samples.shakespeare\`
            WHERE corpus = @corpus
            AND word_count >= @min_word_count
            ORDER BY word_count DESC`;

        const options = {
            query: sqlQuery,
            // Location must match that of the dataset(s) referenced in the query.
            location: 'US',
            params: {corpus: 'romeoandjuliet', min_word_count: 250},
            useQueryCache: false,
        };

        // Run the query as a job
        const [job] = await bigqueryClient.createQueryJob(options);
        console.log(`Job ${job.id} started.`);

        // Wait for the query to finish
        const [rows] = await job.getQueryResults();

        // Print the results
        console.log('Rows:');
        rows.forEach(row => console.log(row));

        // Print job statistics
        console.log('JOB STATISTICS:')
        console.log(`Status: ${job.metadata.status.state}`);
        console.log(`Creation time: ${job.metadata.statistics.creationTime}`);
        console.log(`Start time: ${job.metadata.statistics.startTime}`);
        console.log(`Statement type: ${job.metadata.statistics.query.statementType}`);
    }
    queryShakespeareDisableCache();
}

main();

Alguns pontos importantes sobre o código: Primeiro, o armazenamento em cache é desativado definindo UseQueryCache como false dentro do objeto options. Em segundo lugar, você acessou as estatísticas sobre a consulta no objeto de job.

No Cloud Shell, execute o app:

node queryShakespeare.js

Você vai ver uma lista de mensagens de commit e as ocorrências delas. Além disso, você também vai encontrar algumas estatísticas sobre a consulta:

Rows:
{ word: 'the', word_count: 614 }
{ word: 'I', word_count: 577 }
{ word: 'and', word_count: 490 }
{ word: 'to', word_count: 486 }
{ word: 'a', word_count: 407 }
{ word: 'of', word_count: 367 }
{ word: 'my', word_count: 314 }
{ word: 'is', word_count: 307 }
{ word: 'in', word_count: 291 }
{ word: 'you', word_count: 271 }
{ word: 'that', word_count: 270 }
{ word: 'me', word_count: 263 }
JOB STATISTICS:
Status: RUNNING
Creation time: 1554309220660
Start time: 1554309220793
Statement type: SELECT

10. Como carregar dados no BigQuery

Se quiser consultar seus próprios dados, primeiro carregue-os no BigQuery. O BigQuery é compatível com o carregamento de dados de várias fontes, como o Google Cloud Storage, outros serviços do Google ou uma fonte local legível. Você pode até transmitir seus dados. Leia mais na página Como carregar dados no BigQuery.

Nesta etapa, você vai carregar um arquivo JSON armazenado no Google Cloud Storage em uma tabela do BigQuery. O arquivo JSON está localizado em: gs://cloud-samples-data/bigquery/us-states/us-states.json

Se você quiser saber o conteúdo do arquivo JSON, use a ferramenta de linha de comando gsutil para fazer o download dele no Cloud Shell:

gsutil cp gs://cloud-samples-data/bigquery/us-states/us-states.json .

Copying gs://cloud-samples-data/bigquery/us-states/us-states.json...
/ [1 files][  2.0 KiB/  2.0 KiB]                                                
Operation completed over 1 objects/2.0 KiB.

Ele contém a lista de estados dos EUA, e cada estado é um objeto JSON em uma linha separada:

less us-states.json

{"name": "Alabama", "post_abbr": "AL"}
{"name": "Alaska", "post_abbr":  "AK"}
...

Para carregar esse arquivo JSON no BigQuery, crie um arquivo createDataset.js e um arquivo loadBigQueryJSON.js na pasta BigQueryDemo:

touch createDataset.js 
touch loadBigQueryJSON.js

Instale a biblioteca de cliente do Node.js do Google Cloud Storage:

 npm install --save @google-cloud/storage

Navegue até o arquivo createDataset.js e insira o seguinte código:

'use strict';

function main() {
    // Import the Google Cloud client libraries
    const {BigQuery} = require('@google-cloud/bigquery');

    async function createDataset() {
        const datasetId = "my_states_dataset3";

        const bigqueryClient = new BigQuery();

        // Specify the geographic location where the dataset should reside
        const options = {
        location: 'US',
        };

        // Create a new dataset
        const [dataset] = await bigqueryClient.createDataset(datasetId, options);
        console.log(`Dataset ${dataset.id} created.`);
    }

    createDataset();
}

main();

Em seguida, navegue até o arquivo loadBigQueryJSON.js e insira o seguinte código:

'use strict';

function main() {
    // Import the Google Cloud client libraries
    const {BigQuery} = require('@google-cloud/bigquery');
    const {Storage} = require('@google-cloud/storage');

    const datasetId = "my_states_dataset3";
    const tableId = "my_states_table";


    async function createTable(datasetId, tableId) {
        // Creates a new table

        // Create a client
        const bigqueryClient = new BigQuery();

        const options = {
            location: 'US',
            };

        // Create a new table in the dataset
        const [table] = await bigqueryClient
        .dataset(datasetId)
        .createTable(tableId, options);

        console.log(`Table ${table.id} created.`);
    }

    async function loadJSONFromGCS(datasetId, tableId) {
        // Import a GCS file into a table with manually defined schema.

        // Instantiate clients
        const bigqueryClient = new BigQuery();
        const storageClient = new Storage();

        const bucketName = 'cloud-samples-data';
        const filename = 'bigquery/us-states/us-states.json';

        // Configure the load job.
        const metadata = {
        sourceFormat: 'NEWLINE_DELIMITED_JSON',
        schema: {
            fields: [
            {name: 'name', type: 'STRING'},
            {name: 'post_abbr', type: 'STRING'},
            ],
        },
        location: 'US',
        };

        // Load data from a Google Cloud Storage file into the table
        const [job] = await bigqueryClient
        .dataset(datasetId)
        .table(tableId)
        .load(storageClient.bucket(bucketName).file(filename), metadata);

        // load() waits for the job to finish
        console.log(`Job ${job.id} completed.`);

        // Check the job's status for errors
        const errors = job.status.errors;
        if (errors && errors.length > 0) {
        throw errors;
        }
    }

    // createDataset(datasetId);
    createTable(datasetId, tableId);
    loadJSONFromGCS(datasetId, tableId);
}

main();

Estude por um ou dois minutos como o código carrega o arquivo JSON e cria uma tabela (com um esquema) em um conjunto de dados.

No Cloud Shell, execute o app:

node createDataset.js
node loadBigQueryJSON.js

Um conjunto de dados e uma tabela são criados no BigQuery:

Table my_states_table created.
Job [JOB ID] completed.

Para verificar se o conjunto de dados foi criado, acesse a IU da Web do BigQuery. Um novo conjunto de dados e uma tabela vão aparecer. Se você mudar para a guia "Visualização" da tabela, poderá conferir os dados reais:

11. Parabéns!

Você aprendeu a usar o BigQuery com Node.js.

Limpar

Para evitar a cobrança na sua conta do Google Cloud Platform pelo uso de recursos neste guia de início rápido, siga estas etapas:

• Acesse o Console do Cloud Platform.
• Selecione o projeto que você quer encerrar e clique em "Excluir" na parte de cima. Isso programa a exclusão do projeto.

Saiba mais

• Google BigQuery: https://cloud.google.com/bigquery/docs/
• Node.js no Google Cloud Platform: https://cloud.google.com/nodejs/
• Biblioteca de cliente do Node.js do Google BigQuery: https://github.com/googleapis/nodejs-bigquery

Licença

Este conteúdo está sob a licença Atribuição 2.0 Genérica da Creative Commons.