Como fazer 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 para criar ou selecionar um projeto e ativar o faturamento.

1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

2. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

3. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

4. O BigQuery é ativado automaticamente em novos projetos. Para ativar o BigQuery em um projeto preexistente, Ative as APIs BigQuery, BigQuery Storage API.

   Ative 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

Antes de terminar este tutorial, também é necessário se familiarizar com os comandos mágicos do IPython para BigQuery (em inglês), a biblioteca de cliente do BigQuery e como usar a biblioteca de cliente com pandas (em inglês).

Instalar as bibliotecas de cliente

Instale a biblioteca de cliente Python para BigQuery versão 1.9.0 (em inglês) ou superior e a biblioteca de cliente Python da API BigQuery Storage.

PIP

Instale os pacotes google-cloud-bigquery e google-cloud-bigquery-storage.

pip install --upgrade 'google-cloud-bigquery[bqstorage,pandas]'

Conda

Instale os pacotes Conda do BigQuery e da API BigQuery Storage (páginas em inglês) usando o canal conda-forge gerenciado pela comunidade.

conda install -c conda-forge google-cloud-bigquery \
  google-cloud-bigquery-storage \
  pandas \
  pyarrow

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

Inicie o servidor do Jupyter Notebook 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 de resultados de consulta extensos com a API BigQuery Storage adicionando o argumento --use_bq_storage_api aos comandos mágicos %%bigquery.

%%bigquery tax_forms --use_bqstorage_api
SELECT * FROM `bigquery-public-data.irs_990.irs_990_2012`

Quando esse argumento é usado com pequenos resultados de consulta, os comandos mágicos utilizam a API BigQuery para fazer o 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 outros argumentos para usar a API BigQuery Storage para fazer o download de grandes resultados.

%%bigquery tax_forms
SELECT * FROM `bigquery-public-data.irs_990.irs_990_2012`

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

# 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.BigQueryReadClient(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 não precisar fazer a autenticação 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 fazer o download dos resultados usando a API BigQuery Storage.

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()
    .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 em uma tabela usando o método list_rows, que retorna um objeto RowIterator. Faça o download das 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 filtrar linhas. Crie uma sessão de leitura usando o método create_read_session.

Se houver algum stream na sessão, comece a ler as linhas a partir dele usando o método read_rows. 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

project_id = "bigquery-public-data"
dataset_id = "new_york_trees"
table_id = "tree_species"
table = f"projects/{project_id}/datasets/{dataset_id}/tables/{table_id}"

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

parent = "projects/{}".format(your_project_id)

requested_session = types.ReadSession(
    table=table,
    # This API can also deliver data serialized in Apache Avro format.
    # This example leverages Apache Arrow.
    data_format=types.DataFormat.ARROW,
    read_options=read_options,
)
read_session = bqstorageclient.create_read_session(
    parent=parent, read_session=requested_session, max_stream_count=1,
)

# 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 = read_session.streams[0]
reader = bqstorageclient.read_rows(stream.name)

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

Código-fonte para todos os exemplos

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

Ver no GitHub Feedback

import google.auth
from google.cloud import bigquery
from google.cloud import bigquery_storage

# 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.BigQueryReadClient(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()
    .to_dataframe(bqstorage_client=bqstorageclient)
)
print(dataframe.head())
project_id = "bigquery-public-data"
dataset_id = "new_york_trees"
table_id = "tree_species"
table = f"projects/{project_id}/datasets/{dataset_id}/tables/{table_id}"

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

parent = "projects/{}".format(your_project_id)

requested_session = types.ReadSession(
    table=table,
    # This API can also deliver data serialized in Apache Avro format.
    # This example leverages Apache Arrow.
    data_format=types.DataFormat.ARROW,
    read_options=read_options,
)
read_session = bqstorageclient.create_read_session(
    parent=parent, read_session=requested_session, max_stream_count=1,
)

# 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 = read_session.streams[0]
reader = bqstorageclient.read_rows(stream.name)

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

Limpeza

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

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 IDs 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 ID 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 Cloud, acesse a página Gerenciar recursos:

   Acessar "Gerenciar recursos"

2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
3. Na caixa de diálogo, digite o ID 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 (em inglês)