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 download de dados armazenados no BigQuery para utilização em ferramentas de análise, como a biblioteca pandas para Python (em inglês).

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 Google Cloud Platform.

   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 no projeto do Google Cloud Platform.

   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

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 (páginas em inglês).

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 de notebook do Jupyter e crie um notebook. Carregue os comandos mágicos do IPython para BigQuery usando o comando mágico %load_ext (em inglês).

%load_ext google.cloud.bigquery

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

Atenção: 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 utilizam a API do 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 (em inglês) 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 os comandos mágicos %%bigquery sem argumentos extras para usar a API BigQuery Storage e 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 criar um objeto BigQuery Client e um BigQueryStorageClient (páginas em inglês).

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 (em inglês). Chame o método to_dataframe (em inglês) 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 faturáveis.

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 de uma tabela usando o método list_rows, que retorna um objeto RowIterator (páginas em inglês). Faça o download de linhas usando a API BigQuery Storage. Para isso, chame o método to_dataframe (em inglês) 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 (em inglês).

Se houver algum stream na sessão, use o método read_rows (em inglês) para ler as linhas do stream. Chame o método to_dataframe (em inglês) 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 API can also deliver data serialized in Apache Avro format.
    # This example leverages Apache Arrow.
    format_=bigquery_storage_v1beta1.enums.DataFormat.ARROW,
    # We use a LIQUID strategy in this example because we only read from a
    # single stream. Consider BALANCED if you're consuming multiple streams
    # concurrently and want more consistent stream sizes.
    sharding_strategy=(
        bigquery_storage_v1beta1.enums.ShardingStrategy.LIQUID
    ),
)

# 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()
    .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 API can also deliver data serialized in Apache Avro format.
    # This example leverages Apache Arrow.
    format_=bigquery_storage_v1beta1.enums.DataFormat.ARROW,
    # We use a LIQUID strategy in this example because we only read from a
    # single stream. Consider BALANCED if you're consuming multiple streams
    # concurrently and want more consistent stream sizes.
    sharding_strategy=(
        bigquery_storage_v1beta1.enums.ShardingStrategy.LIQUID
    ),
)

# 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 (em inglês)