Guia de início rápido: como usar bibliotecas de cliente

Veja nesta página como começar com a API BigQuery na sua linguagem de programação favorita.

Antes de começar

  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. Ative a BigQuery API.

    Ative a API

  4. Configurar a autenticação:

    1. No Console do Cloud, acesse a página Criar chave da conta de serviço.

      Acessar página "Criar chave da conta de serviço"
    2. Na lista Conta de serviço, selecione Nova conta de serviço.
    3. No campo Nome da conta de serviço, insira um nome.

    4. Na lista Papel, selecione Projeto > Proprietário.

      Observação: o campo Papel autoriza sua conta de serviço a acessar recursos. É possível visualizar e alterar esse campo mais tarde usando o Console do Cloud. Se você estiver desenvolvendo um aplicativo de produção, especifique permissões mais granulares do que Projeto > Proprietário. Para mais informações, consulte Como atribuir papéis a contas de serviço.
    5. Clique em Criar. O download de um arquivo JSON que contém a chave é feito no computador.

  5. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço. Essa variável só se aplica à sessão de shell atual. Dessa maneira, se você abrir uma nova sessão, defina a variável novamente.

Instalar a biblioteca de cliente

C#

Para mais informações sobre a configuração do ambiente de desenvolvimento do C#, consulte o guia de configuração do ambiente de desenvolvimento do C#. 

Install-Package Google.Cloud.BigQuery.V2 -Pre

Go

go get -u cloud.google.com/go/bigquery

Java

Para mais informações sobre a configuração do ambiente de desenvolvimento do Java, consulte o Guia de configuração do ambiente de desenvolvimento Java.

Se você estiver usando o Maven, adicione o código abaixo ao arquivo pom.xml. Para mais informações sobre BOMs, consulte BOM das bibliotecas do Google Cloud Platform.

<!--  Using libraries-bom to manage versions.
See https://github.com/GoogleCloudPlatform/cloud-opensource-java/wiki/The-Google-Cloud-Platform-Libraries-BOM -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>10.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery</artifactId>
  </dependency>

Se você estiver usando o Gradle, adicione isto às dependências:

compile 'com.google.cloud:google-cloud-bigquery:1.117.1'

Se você estiver usando o sbt, adicione o seguinte às suas dependências:

libraryDependencies += "com.google.cloud" % "google-cloud-bigquery" % "1.117.1"

Caso você esteja usando o IntelliJ ou o Eclipse, poderá adicionar bibliotecas de cliente ao seu projeto usando estes plug-ins de ambiente de desenvolvimento integrado:

Os plug-ins também oferecem outras funcionalidades, como gerenciamento de chaves de contas de serviço. Consulte a documentação de cada plug-in para mais detalhes.

Node.js

Para mais informações sobre a configuração do ambiente de desenvolvimento do Node.js, consulte este guia. 

npm install --save @google-cloud/bigquery

PHP

composer require google/cloud-bigquery

Python

Para mais informações sobre a configuração do ambiente de desenvolvimento do Python, consulte este guia. 

pip install --upgrade google-cloud-bigquery

Ruby

Para mais informações sobre a configuração do ambiente de desenvolvimento do Ruby, consulte o Guia de configuração do ambiente de desenvolvimento Ruby.

gem install google-cloud-bigquery

Importar as bibliotecas

C#

Para mais informações, consulte a documentação de referência da API BigQuery C#.

bigquery/api/SimpleApp/Program.cs 

using System;
using Google.Cloud.BigQuery.V2;

Go

Para mais informações, consulte a documentação de referência da API BigQuery em Go (em inglês).

import (
	"context"
	"fmt"
	"io"
	"log"
	"os"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

Java

Para mais informações, consulte a documentação de referência da API BigQuery em Java (em inglês).

Ver no GitHub (em inglês) Feedback 

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FieldValueList;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobId;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableResult;
import java.util.UUID;

Node.js

Para mais informações, consulte a documentação de referência da API BigQuery Node.js (em inglês).

Ver no GitHub (em inglês) Feedback 
// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');

PHP

Para mais informações, consulte a documentação de referência da API BigQuery PHP.

Ver no GitHub (em inglês) Feedback 
use Google\Cloud\BigQuery\BigQueryClient;

Python

Para mais informações, consulte a documentação de referência da API Python para BigQuery (em inglês).

Ver no GitHub (em inglês) Feedback 
from google.cloud import bigquery

Ruby

Para mais informações, consulte a documentação de referência da API BigQuery em Ruby.

require "google/cloud/bigquery"

Inicializar um cliente do BigQuery

C#

Use a função BigQueryClient.Create() para criar o cliente do BigQuery.

string projectId = "YOUR-PROJECT-ID";
var client = BigQueryClient.Create(projectId);

Go

Use a função bigquery.NewClient() para criar o cliente do BigQuery.

ctx := context.Background()

client, err := bigquery.NewClient(ctx, projectID)
if err != nil {
	log.Fatalf("bigquery.NewClient: %v", err)
}
defer client.Close()

Java

Use a função BigQueryOptions.getDefaultInstance() para usar as opções de autenticação padrão. Use a função BigQueryOptions.getService() para criar o cliente do BigQuery.

Ver no GitHub (em inglês) Feedback 
BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

Node.js

Instancie a classe BigQuery para criar o cliente do BigQuery.

Ver no GitHub (em inglês) Feedback 
// Create a client
const bigqueryClient = new BigQuery();

PHP

Instancie a classe BigQueryClient para criar o cliente do BigQuery.

Ver no GitHub (em inglês) Feedback 
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);

Python

Instancie a classe bigquery.Client para criar o cliente do BigQuery.

Ver no GitHub (em inglês) Feedback 
client = bigquery.Client()

Ruby

Use a função Google::Cloud::Bigquery.new para criar o cliente do BigQuery.

# This uses Application Default Credentials to authenticate.
# @see https://cloud.google.com/bigquery/docs/authentication/getting-started
bigquery = Google::Cloud::Bigquery.new

Execução de consultas

Consulte o Conjunto de dados públicos do Stack Overflow para encontrar as perguntas mais visualizadas marcadas com google-bigquery.

SELECT
  CONCAT(
    'https://stackoverflow.com/questions/',
    CAST(id as STRING)) as url,
  view_count
FROM `bigquery-public-data.stackoverflow.posts_questions`
WHERE tags like '%google-bigquery%'
ORDER BY view_count DESC
LIMIT 10

Essa consulta usa a sintaxe SQL padrão, que está descrita no guia de referência da consulta. As bibliotecas de cliente são pré-determinadas para a sintaxe SQL padrão. Consulte Como trocar dialetos SQL para alterar os dialetos SQL.

Execução da consulta

Faça a consulta usando o cliente autenticado do BigQuery.

C#

Defina uma string de consulta e use a função client.ExecuteQuery() para enviar a consulta e receber os resultados.

string query = @"SELECT
    CONCAT(
        'https://stackoverflow.com/questions/',
        CAST(id as STRING)) as url, view_count
    FROM `bigquery-public-data.stackoverflow.posts_questions`
    WHERE tags like '%google-bigquery%'
    ORDER BY view_count DESC
    LIMIT 10";
var result = client.ExecuteQuery(query, parameters: null);

Go

Use a função bigquery.Query() para definir uma consulta e a função Query.Read() para enviar a consulta e receber os resultados.

query := client.Query(
	`SELECT
		CONCAT(
			'https://stackoverflow.com/questions/',
			CAST(id as STRING)) as url,
		view_count
	FROM ` + "`bigquery-public-data.stackoverflow.posts_questions`" + `
	WHERE tags like '%google-bigquery%'
	ORDER BY view_count DESC
	LIMIT 10;`)
return query.Read(ctx)

Java

Defina a consulta com uma instância do QueryJobConfiguration. Inicie o job de consulta com o método BigQuery.create().

Ver no GitHub (em inglês) Feedback 
QueryJobConfiguration queryConfig =
    QueryJobConfiguration.newBuilder(
            "SELECT "
                + "CONCAT('https://stackoverflow.com/questions/', CAST(id as STRING)) as url, "
                + "view_count "
                + "FROM `bigquery-public-data.stackoverflow.posts_questions` "
                + "WHERE tags like '%google-bigquery%' "
                + "ORDER BY favorite_count DESC LIMIT 10")
        // Use standard SQL syntax for queries.
        // See: https://cloud.google.com/bigquery/sql-reference/
        .setUseLegacySql(false)
        .build();

// Create a job ID so that we can safely retry.
JobId jobId = JobId.of(UUID.randomUUID().toString());
Job queryJob = bigquery.create(JobInfo.newBuilder(queryConfig).setJobId(jobId).build());

// Wait for the query to complete.
queryJob = queryJob.waitFor();

// Check for errors
if (queryJob == null) {
  throw new RuntimeException("Job no longer exists");
} else if (queryJob.getStatus().getError() != null) {
  // You can also look at queryJob.getStatus().getExecutionErrors() for all
  // errors, not just the latest one.
  throw new RuntimeException(queryJob.getStatus().getError().toString());
}

Node.js

Use o método BigQuery.query() para iniciar a consulta.

Ver no GitHub (em inglês) Feedback 
// The SQL query to run
const sqlQuery = `SELECT
  CONCAT(
    'https://stackoverflow.com/questions/',
    CAST(id as STRING)) as url,
  view_count
  FROM \`bigquery-public-data.stackoverflow.posts_questions\`
  WHERE tags like '%google-bigquery%'
  ORDER BY view_count 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);

PHP

Crie uma configuração de consulta e use o método BigQueryClient.startQuery() para iniciar a consulta.

Ver no GitHub (em inglês) Feedback 
$query = <<<ENDSQL
SELECT
  CONCAT(
    'https://stackoverflow.com/questions/',
    CAST(id as STRING)) as url,
  view_count
FROM `bigquery-public-data.stackoverflow.posts_questions`
WHERE tags like '%google-bigquery%'
ORDER BY view_count DESC
LIMIT 10;
ENDSQL;
$queryJobConfig = $bigQuery->query($query);
$queryResults = $bigQuery->runQuery($queryJobConfig);

Python

Use o método Client.query() para iniciar a consulta.

Ver no GitHub (em inglês) Feedback 
query_job = client.query(
    """
    SELECT
      CONCAT(
        'https://stackoverflow.com/questions/',
        CAST(id as STRING)) as url,
      view_count
    FROM `bigquery-public-data.stackoverflow.posts_questions`
    WHERE tags like '%google-bigquery%'
    ORDER BY view_count DESC
    LIMIT 10"""
)

results = query_job.result()  # Waits for job to complete.

Ruby

Use a função Google::Cloud::BigQuery::Project.query para iniciar uma consulta e aguarde os resultados.

sql     = "SELECT " +
          "CONCAT('https://stackoverflow.com/questions/', " +
          "       CAST(id as STRING)) as url, view_count " +
          "FROM `bigquery-public-data.stackoverflow.posts_questions` " +
          "WHERE tags like '%google-bigquery%' " +
          "ORDER BY view_count DESC LIMIT 10"
results = bigquery.query sql

Para ver mais exemplos de como executar consultas do BigQuery, acesse:

Exibição do resultado da consulta

Exiba os resultados da consulta.

C#

Console.Write("\nQuery Results:\n------------\n");
foreach (var row in result)
{
    Console.WriteLine($"{row["url"]}: {row["view_count"]} views");
}

Go

Use a função RowIterator.Next() para carregar cada linha em um ponteiro de struct.

type StackOverflowRow struct {
	URL       string `bigquery:"url"`
	ViewCount int64  `bigquery:"view_count"`
}

// printResults prints results from a query to the Stack Overflow public dataset.
func printResults(w io.Writer, iter *bigquery.RowIterator) error {
	for {
		var row StackOverflowRow
		err := iter.Next(&row)
		if err == iterator.Done {
			return nil
		}
		if err != nil {
			return fmt.Errorf("error iterating through results: %v", err)
		}

		fmt.Fprintf(w, "url: %s views: %d\n", row.URL, row.ViewCount)
	}
}

Java

Itere o QueryResponse para receber todas as linhas nos resultados. O iterador administra automaticamente a paginação. Cada FieldList expõe as colunas por índices numéricos ou nome de coluna.

Ver no GitHub (em inglês) Feedback 
// Get the results.
TableResult result = queryJob.getQueryResults();

// Print all pages of the results.
for (FieldValueList row : result.iterateAll()) {
  String url = row.get("url").getStringValue();
  long viewCount = row.get("view_count").getLongValue();
  System.out.printf("url: %s views: %d%n", url, viewCount);
}

Node.js

Os resultados da consulta são retornados como uma lista de linhas, em que cada uma é um dicionário.

Ver no GitHub (em inglês) Feedback 
console.log('Query Results:');
rows.forEach(row => {
  const url = row['url'];
  const viewCount = row['view_count'];
  console.log(`url: ${url}, ${viewCount} views`);
});

PHP

Chame o método Job.queryResults() para aguardar o encerramento da consulta. Cada linha nos resultados da consulta é uma matriz associativa.

Ver no GitHub (em inglês) Feedback 
if ($queryResults->isComplete()) {
    $i = 0;
    $rows = $queryResults->rows();
    foreach ($rows as $row) {
        printf('--- Row %s ---' . PHP_EOL, ++$i);
        printf('url: %s, %s views' . PHP_EOL, $row['url'], $row['view_count']);
    }
    printf('Found %s row(s)' . PHP_EOL, $i);
} else {
    throw new Exception('The query failed to complete');
}

Python

Itere o RowIterator para receber todas as linhas nos resultados. O iterador administra automaticamente a paginação. Cada linha expõe as colunas por índice numérico, nome da coluna ou como atributos do Python.

Ver no GitHub (em inglês) Feedback 
for row in results:
    print("{} : {} views".format(row.url, row.view_count))

Ruby

A classe Google::Cloud::BigQuery::Data expõe cada linha como um hash.

results.each do |row|
  puts "#{row[:url]}: #{row[:view_count]} views"
end

Saiba mais como trabalhar com linhas de dados no BigQuery:

Código-fonte completo

Veja o código-fonte completo para a amostra.

C#


using System;
using Google.Cloud.BigQuery.V2;

namespace GoogleCloudSamples
{
    public class Program
    {
        public static void Main(string[] args)
        {
            string projectId = "YOUR-PROJECT-ID";
            var client = BigQueryClient.Create(projectId);
            string query = @"SELECT
                CONCAT(
                    'https://stackoverflow.com/questions/',
                    CAST(id as STRING)) as url, view_count
                FROM `bigquery-public-data.stackoverflow.posts_questions`
                WHERE tags like '%google-bigquery%'
                ORDER BY view_count DESC
                LIMIT 10";
            var result = client.ExecuteQuery(query, parameters: null);
            Console.Write("\nQuery Results:\n------------\n");
            foreach (var row in result)
            {
                Console.WriteLine($"{row["url"]}: {row["view_count"]} views");
            }
        }
    }
}

Go

import (
	"context"
	"fmt"
	"io"
	"log"
	"os"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

func main() {
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	if projectID == "" {
		fmt.Println("GOOGLE_CLOUD_PROJECT environment variable must be set.")
		os.Exit(1)
	}

	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		log.Fatalf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	rows, err := query(ctx, client)
	if err != nil {
		log.Fatal(err)
	}
	if err := printResults(os.Stdout, rows); err != nil {
		log.Fatal(err)
	}
}

// query returns a row iterator suitable for reading query results.
func query(ctx context.Context, client *bigquery.Client) (*bigquery.RowIterator, error) {

	query := client.Query(
		`SELECT
			CONCAT(
				'https://stackoverflow.com/questions/',
				CAST(id as STRING)) as url,
			view_count
		FROM ` + "`bigquery-public-data.stackoverflow.posts_questions`" + `
		WHERE tags like '%google-bigquery%'
		ORDER BY view_count DESC
		LIMIT 10;`)
	return query.Read(ctx)
}

type StackOverflowRow struct {
	URL       string `bigquery:"url"`
	ViewCount int64  `bigquery:"view_count"`
}

// printResults prints results from a query to the Stack Overflow public dataset.
func printResults(w io.Writer, iter *bigquery.RowIterator) error {
	for {
		var row StackOverflowRow
		err := iter.Next(&row)
		if err == iterator.Done {
			return nil
		}
		if err != nil {
			return fmt.Errorf("error iterating through results: %v", err)
		}

		fmt.Fprintf(w, "url: %s views: %d\n", row.URL, row.ViewCount)
	}
}

Java

Ver no GitHub (em inglês) Feedback 

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FieldValueList;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobId;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableResult;
import java.util.UUID;

public class SimpleApp {
  public static void main(String... args) throws Exception {
    BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
    QueryJobConfiguration queryConfig =
        QueryJobConfiguration.newBuilder(
                "SELECT "
                    + "CONCAT('https://stackoverflow.com/questions/', CAST(id as STRING)) as url, "
                    + "view_count "
                    + "FROM `bigquery-public-data.stackoverflow.posts_questions` "
                    + "WHERE tags like '%google-bigquery%' "
                    + "ORDER BY favorite_count DESC LIMIT 10")
            // Use standard SQL syntax for queries.
            // See: https://cloud.google.com/bigquery/sql-reference/
            .setUseLegacySql(false)
            .build();

    // Create a job ID so that we can safely retry.
    JobId jobId = JobId.of(UUID.randomUUID().toString());
    Job queryJob = bigquery.create(JobInfo.newBuilder(queryConfig).setJobId(jobId).build());

    // Wait for the query to complete.
    queryJob = queryJob.waitFor();

    // Check for errors
    if (queryJob == null) {
      throw new RuntimeException("Job no longer exists");
    } else if (queryJob.getStatus().getError() != null) {
      // You can also look at queryJob.getStatus().getExecutionErrors() for all
      // errors, not just the latest one.
      throw new RuntimeException(queryJob.getStatus().getError().toString());
    }

    // Get the results.
    TableResult result = queryJob.getQueryResults();

    // Print all pages of the results.
    for (FieldValueList row : result.iterateAll()) {
      String url = row.get("url").getStringValue();
      long viewCount = row.get("view_count").getLongValue();
      System.out.printf("url: %s views: %d%n", url, viewCount);
    }
  }
}

Node.js

Ver no GitHub (em inglês) Feedback 
// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');

async function queryStackOverflow() {
  // Queries a public Stack Overflow dataset.

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

  // The SQL query to run
  const sqlQuery = `SELECT
    CONCAT(
      'https://stackoverflow.com/questions/',
      CAST(id as STRING)) as url,
    view_count
    FROM \`bigquery-public-data.stackoverflow.posts_questions\`
    WHERE tags like '%google-bigquery%'
    ORDER BY view_count 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('Query Results:');
  rows.forEach(row => {
    const url = row['url'];
    const viewCount = row['view_count'];
    console.log(`url: ${url}, ${viewCount} views`);
  });
}
queryStackOverflow();

PHP

Ver no GitHub (em inglês) Feedback 
require __DIR__ . '/vendor/autoload.php';

use Google\Cloud\BigQuery\BigQueryClient;

// get the project ID as the first argument
if (2 != count($argv)) {
    die("Usage: php stackoverflow.php YOUR_PROJECT_ID\n");
}

$projectId = $argv[1];

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$query = <<<ENDSQL
SELECT
  CONCAT(
    'https://stackoverflow.com/questions/',
    CAST(id as STRING)) as url,
  view_count
FROM `bigquery-public-data.stackoverflow.posts_questions`
WHERE tags like '%google-bigquery%'
ORDER BY view_count DESC
LIMIT 10;
ENDSQL;
$queryJobConfig = $bigQuery->query($query);
$queryResults = $bigQuery->runQuery($queryJobConfig);

if ($queryResults->isComplete()) {
    $i = 0;
    $rows = $queryResults->rows();
    foreach ($rows as $row) {
        printf('--- Row %s ---' . PHP_EOL, ++$i);
        printf('url: %s, %s views' . PHP_EOL, $row['url'], $row['view_count']);
    }
    printf('Found %s row(s)' . PHP_EOL, $i);
} else {
    throw new Exception('The query failed to complete');
}

Python

Ver no GitHub (em inglês) Feedback 
from google.cloud import bigquery

def query_stackoverflow():
    client = bigquery.Client()
    query_job = client.query(
        """
        SELECT
          CONCAT(
            'https://stackoverflow.com/questions/',
            CAST(id as STRING)) as url,
          view_count
        FROM `bigquery-public-data.stackoverflow.posts_questions`
        WHERE tags like '%google-bigquery%'
        ORDER BY view_count DESC
        LIMIT 10"""
    )

    results = query_job.result()  # Waits for job to complete.

    for row in results:
        print("{} : {} views".format(row.url, row.view_count))

if __name__ == "__main__":
    query_stackoverflow()

Ruby

require "google/cloud/bigquery"

# This uses Application Default Credentials to authenticate.
# @see https://cloud.google.com/bigquery/docs/authentication/getting-started
bigquery = Google::Cloud::Bigquery.new

sql     = "SELECT " +
          "CONCAT('https://stackoverflow.com/questions/', " +
          "       CAST(id as STRING)) as url, view_count " +
          "FROM `bigquery-public-data.stackoverflow.posts_questions` " +
          "WHERE tags like '%google-bigquery%' " +
          "ORDER BY view_count DESC LIMIT 10"
results = bigquery.query sql

results.each do |row|
  puts "#{row[:url]}: #{row[:view_count]} views"
end

Parabéns! Você enviou sua primeira solicitação ao BigQuery.

Como foi?

A seguir

Saiba mais sobre as bibliotecas de cliente da API BigQuery.