Como fazer o download de dados do BigQuery para o pandas usando a API BigQuery Storage

A API BigQuery Storage fornece acesso rápido aos dados armazenados no BigQuery. Use essa API para fazer o download de dados armazenados no BigQuery para utilização em ferramentas de análise, como a biblioteca pandas para Python.

Objetivos

Neste tutorial, você:

• fará o download dos resultados das consultas para um DataFrame do pandas usando a API BigQuery Storage a partir dos comandos mágicos do IPython para BigQuery em um notebook Jupyter;
• fará o download dos resultados da consulta para um DataFrame do pandas usando a biblioteca de cliente do BigQuery para Python;
• fará o download dos dados da tabela do BigQuery para um DataFrame do pandas usando a biblioteca de cliente do BigQuery para Python;
• fará o download dos dados da tabela do BigQuery para um DataFrame do pandas usando a biblioteca de cliente da API BigQuery Storage para Python.

Custos

O BigQuery é um produto pago. Você paga pelas consultas que executa nele. O primeiro 1 TB de dados de consulta processados por mês é gratuito. Para mais informações, consulte a página Preços do BigQuery.

A API BigQuery Storage é um produto pago. Você paga pelos dados da tabela que verifica durante o download de um DataFrame. Para mais informações, consulte a página Preços do BigQuery.

Antes de começar

Antes de começar este tutorial, use o Console do Google Cloud Platform para criar ou selecionar um projeto e ativar o faturamento.

1. Faça login na sua Conta do Google.

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

2. Selecione ou crie um projeto do GCP.

   Observação: se você não pretende manter os recursos criados neste tutorial, crie um novo projeto em vez de selecionar um existente. Depois de terminar, é possível excluir o projeto, removendo todos os recursos associados ao projeto e ao tutorial.

   Acessar a página Gerenciar recursos

3. Verifique se o faturamento foi ativado para o projeto.

   Saiba como ativar o faturamento

4. O BigQuery é ativado automaticamente em novos projetos. Para ativar o BigQuery em um projeto pré-existente, Ativar BigQuery, BigQuery Storage API APIs.

   Ativar as APIs

5. Configure um ambiente de desenvolvimento para Python
   Configurar Python
6. Configure a autenticação para seu ambiente de desenvolvimento.
   Configurar a autenticação

Também é necessário ter familiaridade com os comandos mágicos do IPython para BigQuery, a biblioteca de cliente do BigQuery e o uso da biblioteca de cliente com pandas antes de terminar este tutorial.

Instalar as bibliotecas de cliente

Instale a versão 1.9.0 ou superior da biblioteca de cliente para Python do BigQuery para usar a integração da API BigQuery Storage com a biblioteca do pandas.

pip install --upgrade google-cloud-bigquery[pandas]

Instale a biblioteca de cliente para Python da API BigQuery Storage com suporte para as bibliotecas do pandas e fastavro.

pip install --upgrade google-cloud-bigquery-storage[fastavro,pandas]

Fazer o download dos resultados da consulta usando os comandos mágicos do IPython para BigQuery

Inicie o servidor de notebook do Jupyter e crie um notebook. Carregue os comandos mágicos do IPython para BigQuery usando o comando mágico %load_ext.

%load_ext google.cloud.bigquery

Faça o download dos resultados pesados de consulta com a API BigQuery Storage adicionando o argumento --use_bq_storage_api aos comandos mágicos %%bigquery.

Cuidado: para demonstrar a API BigQuery Storage, a consulta abaixo processa cerca de 7 GB de dados e retorna mais de 125 MB de resultados.

%%bigquery nodejs_deps --use_bqstorage_api
SELECT
    dependency_name,
    dependency_platform,
    project_name,
    project_id,
    version_number,
    version_id,
    dependency_kind,
    optional_dependency,
    dependency_requirements,
    dependency_project_id
FROM
    `bigquery-public-data.libraries_io.dependencies`
WHERE
    LOWER(dependency_platform) = 'npm'
LIMIT 2500000

Quando esse argumento é usado com resultados leves de consulta, os comandos mágicos usam a API BigQuery para fazer download dos resultados.

%%bigquery stackoverflow --use_bqstorage_api
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

Defina a propriedade context.use_bqstorage_api como True para usar a API BigQuery Storage por padrão.

import google.cloud.bigquery.magics

google.cloud.bigquery.magics.context.use_bqstorage_api = True

Depois de definir a propriedade context.use_bqstorage_api, execute o comando mágico %%bigquery sem argumentos adicionais para usar a API BigQuery Storage para fazer o download de resultados pesados.

%%bigquery java_deps
SELECT
    dependency_name,
    dependency_platform,
    project_name,
    project_id,
    version_number,
    version_id,
    dependency_kind,
    optional_dependency,
    dependency_requirements,
    dependency_project_id
FROM
    `bigquery-public-data.libraries_io.dependencies`
WHERE
    LOWER(dependency_platform) = 'maven'
LIMIT 2500000

Usar as bibliotecas de cliente do Python

Criar clientes do Python

Use o código a seguir para construir um objeto BigQuery Client e um BigQueryStorageClient.

Ver no GitHub Feedback

import google.auth
from google.cloud import bigquery
from google.cloud import bigquery_storage_v1beta1

# Explicitly create a credentials object. This allows you to use the same
# credentials for both the BigQuery and BigQuery Storage clients, avoiding
# unnecessary API calls to fetch duplicate authentication tokens.
credentials, your_project_id = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)

# Make clients.
bqclient = bigquery.Client(
    credentials=credentials,
    project=your_project_id
)
bqstorageclient = bigquery_storage_v1beta1.BigQueryStorageClient(
    credentials=credentials
)

Use a biblioteca para Python google-auth para criar credenciais com escopo suficiente para as duas APIs. Transmita um objeto de credenciais para cada construtor para evitar autenticar duas vezes.

Fazer download dos resultados da consulta usando a biblioteca de cliente do BigQuery

Execute uma consulta usando o método query. Chame o método to_dataframe para aguardar a conclusão da consulta e faça o download dos resultados usando a API BigQuery Storage.

Observação: o download dos resultados da consulta usando a API BigQuery Storage aumenta o custo geral. A execução da consulta e o download dos resultados usando a API BigQuery Storage são ações passíveis de cobrança.

Ver no GitHub Feedback

# Download query results.
query_string = """
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
"""

dataframe = (
    bqclient.query(query_string)
    .result()

    # Note: The BigQuery Storage API cannot be used to download small query
    # results, but as of google-cloud-bigquery version 1.11.1, the
    # to_dataframe method will fallback to the tabledata.list API when the
    # BigQuery Storage API fails to read the query results.
    .to_dataframe(bqstorage_client=bqstorageclient)
)
print(dataframe.head())

Fazer o download dos dados da tabela usando a biblioteca de cliente do BigQuery

Faça o download de todas as linhas de uma tabela usando o método list_rows, que retorna um objeto RowIterator. Faça o download de linhas usando a API BigQuery Storage chamando o método to_dataframe com o argumento bqstorage_client.

Ver no GitHub Feedback

# Download a table.
table = bigquery.TableReference.from_string(
    "bigquery-public-data.utility_us.country_code_iso"
)
rows = bqclient.list_rows(
    table,
    selected_fields=[
        bigquery.SchemaField("country_name", "STRING"),
        bigquery.SchemaField("fips_code", "STRING"),
    ],
)
dataframe = rows.to_dataframe(bqstorage_client=bqstorageclient)
print(dataframe.head())

Fazer o download dos dados da tabela usando a biblioteca de cliente da API BigQuery Storage

Use a biblioteca de cliente da API BigQuery Storage diretamente para ter um controle refinado sobre filtros e paralelismo. Quando apenas filtros de linha simples são necessários, uma sessão de leitura da API BigQuery Storage pode ser usada no lugar de uma consulta.

Crie um objeto TableReference com a tabela que quiser ler. Crie um objeto TableReadOptions para selecionar colunas ou linhas de filtro. Crie uma sessão de leitura usando o método create_read_session.

Se houver algum stream na sessão, use o método read_rows para ler as linhas dele. Chame o método to_dataframe no leitor para gravar todo o stream em um DataFrame do pandas. Para um melhor desempenho, leia a partir de vários streams em paralelo. Para simplificar, este exemplo de código lê apenas a partir de um único stream.

Ver no GitHub Feedback

table = bigquery_storage_v1beta1.types.TableReference()
table.project_id = "bigquery-public-data"
table.dataset_id = "new_york_trees"
table.table_id = "tree_species"

# Select columns to read with read options. If no read options are
# specified, the whole table is read.
read_options = bigquery_storage_v1beta1.types.TableReadOptions()
read_options.selected_fields.append("species_common_name")
read_options.selected_fields.append("fall_color")

parent = "projects/{}".format(your_project_id)
session = bqstorageclient.create_read_session(
    table, parent, read_options=read_options
)

# This example reads from only a single stream. Read from multiple streams
# to fetch data faster. Note that the session may not contain any streams
# if there are no rows to read.
stream = session.streams[0]
position = bigquery_storage_v1beta1.types.StreamPosition(stream=stream)
reader = bqstorageclient.read_rows(position)

# Parse all Avro blocks and create a dataframe. This call requires a
# session, because the session contains the schema for the row blocks.
dataframe = reader.to_dataframe(session)
print(dataframe.head())

Código-fonte para todos os exemplos

Veja o código fonte completo para todos os exemplos de biblioteca do cliente.

Ver no GitHub Feedback

import google.auth
from google.cloud import bigquery
from google.cloud import bigquery_storage_v1beta1

# Explicitly create a credentials object. This allows you to use the same
# credentials for both the BigQuery and BigQuery Storage clients, avoiding
# unnecessary API calls to fetch duplicate authentication tokens.
credentials, your_project_id = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)

# Make clients.
bqclient = bigquery.Client(
    credentials=credentials,
    project=your_project_id
)
bqstorageclient = bigquery_storage_v1beta1.BigQueryStorageClient(
    credentials=credentials
)
# Download a table.
table = bigquery.TableReference.from_string(
    "bigquery-public-data.utility_us.country_code_iso"
)
rows = bqclient.list_rows(
    table,
    selected_fields=[
        bigquery.SchemaField("country_name", "STRING"),
        bigquery.SchemaField("fips_code", "STRING"),
    ],
)
dataframe = rows.to_dataframe(bqstorage_client=bqstorageclient)
print(dataframe.head())
# Download query results.
query_string = """
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
"""

dataframe = (
    bqclient.query(query_string)
    .result()

    # Note: The BigQuery Storage API cannot be used to download small query
    # results, but as of google-cloud-bigquery version 1.11.1, the
    # to_dataframe method will fallback to the tabledata.list API when the
    # BigQuery Storage API fails to read the query results.
    .to_dataframe(bqstorage_client=bqstorageclient)
)
print(dataframe.head())
table = bigquery_storage_v1beta1.types.TableReference()
table.project_id = "bigquery-public-data"
table.dataset_id = "new_york_trees"
table.table_id = "tree_species"

# Select columns to read with read options. If no read options are
# specified, the whole table is read.
read_options = bigquery_storage_v1beta1.types.TableReadOptions()
read_options.selected_fields.append("species_common_name")
read_options.selected_fields.append("fall_color")

parent = "projects/{}".format(your_project_id)
session = bqstorageclient.create_read_session(
    table, parent, read_options=read_options
)

# This example reads from only a single stream. Read from multiple streams
# to fetch data faster. Note that the session may not contain any streams
# if there are no rows to read.
stream = session.streams[0]
position = bigquery_storage_v1beta1.types.StreamPosition(stream=stream)
reader = bqstorageclient.read_rows(position)

# Parse all Avro blocks and create a dataframe. This call requires a
# session, because the session contains the schema for the row blocks.
dataframe = reader.to_dataframe(session)
print(dataframe.head())

Limpeza

Para evitar que os recursos usados neste tutorial sejam cobrados na conta do Google Cloud Platform, faça o seguinte:

Exclua o projeto. Você não criou nenhum recurso do BigQuery neste tutorial, mas a exclusão do projeto removerá todos os outros recursos que você criou.

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para seguir este tutorial, a exclusão dele incluirá quaisquer outras ações feitas no projeto.
• Os códigos do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o código do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar vários tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

1. No Console do GCP, acesse a página "Projetos".

   Acessar a página Projetos

2. Na lista de projetos, selecione um e clique em Excluir projeto.
3. Na caixa de diálogo, digite o código do projeto e clique em Encerrar para excluí-lo.

A seguir

• Conheça a referência das bibliotecas de cliente para Python:
  • Referência da biblioteca de cliente do BigQuery para Python
  • Referência da biblioteca de cliente da API BigQuery Storage para Python