Comparação com pandas-gbq

A biblioteca pandas-gbq fornece uma interface simples para executar consultas e fazer upload dos DataFrames do Pandas para o BigQuery. É um wrapper fino da biblioteca de cliente do BigQuery, google-cloud-bigquery. O foco dessas duas bibliotecas é ajudar você a realizar análises de dados usando SQL. Veja neste tópico amostras de código comparando google-cloud-bigquery e pandas-gbq.

As principais diferenças no nível de funcionalidade e de suporte entre as duas bibliotecas incluem:

	pandas-gbq	google-cloud-bigquery
Suporte	Biblioteca de código aberto mantida pelo PyData e por colaboradores voluntários	Biblioteca de código aberto mantida pelo Google
Funcionalidade da API do BigQuery coberta	Execute consultas e salve dados de DataFrames pandas em tabelas	Funcionalidade completa da API do BigQuery, com suporte extra para ler/gravar DataFrames do pandas e um comando mágico do Jupyter para executar consultas
	documentos/fonte	documentos/fonte

Instalar as bibliotecas

Para usar os exemplos de código deste guia, instale o pacote pandas-gbq e as bibliotecas de cliente Python do BigQuery.

PIP

Instale os pacotes pandas-gbq e google-cloud-bigquery.

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

Conda

Instale os pacotes Conda do pandas-gbq e do google-cloud-bigquery usando o canal conda-forge gerenciado pela comunidade.

conda install -c conda-forge pandas-gbq google-cloud-bigquery

Executar consultas

Ambas as bibliotecas são compatíveis com a consulta de dados armazenados no BigQuery. As principais diferenças entre as bibliotecas incluem:

	pandas-gbq	google-cloud-bigquery
Sintaxe SQL padrão	GoogleSQL (configurável com `pandas_gbq.context.dialect`)	GoogleSQL
Configurações de consulta	Enviado como dicionário no formato especificado na referência REST do BigQuery.	Use a classe `QueryJobConfig`, que contém propriedades para as várias opções de configuração da API.

Consultar dados com a sintaxe GoogleSQL

Na amostra a seguir, mostramos como executar uma consulta do GoogleSQL com e sem a especificação explícita de um projeto. Em ambas as bibliotecas, se um projeto não for especificado, ele será determinado a partir das credenciais padrão.

pandas-gbq:

import pandas

sql = """
    SELECT name
    FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = 'TX'
    LIMIT 100
"""

# Run a Standard SQL query using the environment's default project
df = pandas.read_gbq(sql, dialect="standard")

# Run a Standard SQL query with the project set explicitly
project_id = "your-project-id"
df = pandas.read_gbq(sql, project_id=project_id, dialect="standard")

google-cloud-bigquery:

from google.cloud import bigquery

client = bigquery.Client()
sql = """
    SELECT name
    FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = 'TX'
    LIMIT 100
"""

# Run a Standard SQL query using the environment's default project
df = client.query(sql).to_dataframe()

# Run a Standard SQL query with the project set explicitly
project_id = "your-project-id"
df = client.query(sql, project=project_id).to_dataframe()

Como consultar dados com a sintaxe SQL legada

No exemplo a seguir, mostramos como executar uma consulta usando a sintaxe SQL legada. Consulte o guia de migração do GoogleSQL para ver orientações sobre como atualizar suas consultas para o GoogleSQL.

pandas-gbq:

import pandas

sql = """
    SELECT name
    FROM [bigquery-public-data:usa_names.usa_1910_current]
    WHERE state = 'TX'
    LIMIT 100
"""

df = pandas.read_gbq(sql, dialect="legacy")

google-cloud-bigquery:

from google.cloud import bigquery

client = bigquery.Client()
sql = """
    SELECT name
    FROM [bigquery-public-data:usa_names.usa_1910_current]
    WHERE state = 'TX'
    LIMIT 100
"""
query_config = bigquery.QueryJobConfig(use_legacy_sql=True)

df = client.query(sql, job_config=query_config).to_dataframe()

Como usar a API BigQuery Storage para fazer o download de resultados grandes

Use a API BigQuery Storage para acelerar downloads de resultados pesados de 15 a 31 vezes.

pandas-gbq:

import pandas

sql = "SELECT * FROM `bigquery-public-data.irs_990.irs_990_2012`"

# Use the BigQuery Storage API to download results more quickly.
df = pandas.read_gbq(sql, dialect="standard", use_bqstorage_api=True)

google-cloud-bigquery:

from google.cloud import bigquery

client = bigquery.Client()
sql = "SELECT * FROM `bigquery-public-data.irs_990.irs_990_2012`"

# The client library uses the BigQuery Storage API to download results to a
# pandas dataframe if the API is enabled on the project, the
# `google-cloud-bigquery-storage` package is installed, and the `pyarrow`
# package is installed.
df = client.query(sql).to_dataframe()

Como executar uma consulta com uma configuração

O envio de uma configuração com uma solicitação da API do BigQuery é necessário para executar determinadas operações complexas, como executar uma consulta parametrizada ou especificar uma tabela de destino para armazenar os resultados da consulta. No pandas-gbq, a configuração precisa ser enviada como um dicionário no formato especificado na referência REST do BigQuery. No google-cloud-bigquery, são fornecidas classes de configuração de jobs, como QueryJobConfig, que contêm as propriedades necessárias para configurar jobs complexos.

A amostra a seguir mostra como executar uma consulta com parâmetros nomeados.

pandas-gbq:

import pandas

sql = """
    SELECT name
    FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = @state
    LIMIT @limit
"""
query_config = {
    "query": {
        "parameterMode": "NAMED",
        "queryParameters": [
            {
                "name": "state",
                "parameterType": {"type": "STRING"},
                "parameterValue": {"value": "TX"},
            },
            {
                "name": "limit",
                "parameterType": {"type": "INTEGER"},
                "parameterValue": {"value": 100},
            },
        ],
    }
}

df = pandas.read_gbq(sql, configuration=query_config)

google-cloud-bigquery:

from google.cloud import bigquery

client = bigquery.Client()
sql = """
    SELECT name
    FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = @state
    LIMIT @limit
"""
query_config = bigquery.QueryJobConfig(
    query_parameters=[
        bigquery.ScalarQueryParameter("state", "STRING", "TX"),
        bigquery.ScalarQueryParameter("limit", "INTEGER", 100),
    ]
)

df = client.query(sql, job_config=query_config).to_dataframe()

Como carregar um DataFrame do pandas para uma tabela do BigQuery

Ambas as bibliotecas são compatíveis com o upload de dados de um DataFrame do pandas para uma nova tabela no BigQuery. As principais diferenças incluem:

	pandas-gbq	google-cloud-bigquery
Tipo de suporte	Converte o formato DataFrame para CSV antes de enviar para a API, que não é compatível com valores aninhados ou de matriz.	Converte o DataFrame em formato Parquet ou CSV antes de enviar para a API, que é compatível com valores aninhados e de matriz. Escolha Parquet para valores de estrutura e matriz e CSV para flexibilidade de serialização de data e hora. O Parquet é a escolha padrão. Observe que `pyarrow`, que é o mecanismo de parquet usado para enviar os dados do DataFrame para a API do BigQuery, deve estar instalado para carregar o DataFrame em uma tabela.
Carregar configurações	Enviado como dicionário no formato especificado na referência REST do BigQuery.	Use a classe `LoadJobConfig`, que contém propriedades para as várias opções de configuração da API.

pandas-gbq:

import pandas

df = pandas.DataFrame(
    {
        "my_string": ["a", "b", "c"],
        "my_int64": [1, 2, 3],
        "my_float64": [4.0, 5.0, 6.0],
        "my_timestamp": [
            pandas.Timestamp("1998-09-04T16:03:14"),
            pandas.Timestamp("2010-09-13T12:03:45"),
            pandas.Timestamp("2015-10-02T16:00:00"),
        ],
    }
)
table_id = "my_dataset.new_table"

df.to_gbq(table_id)

google-cloud-bigquery:

O pacote google-cloud-bigquery requer que a biblioteca pyarrow serialize um DataFrame pandas em um arquivo Parquet.

Instale o pacote pyarrow:

 conda install -c conda-forge pyarrow

 pip install pyarrow

from google.cloud import bigquery
import pandas

df = pandas.DataFrame(
    {
        "my_string": ["a", "b", "c"],
        "my_int64": [1, 2, 3],
        "my_float64": [4.0, 5.0, 6.0],
        "my_timestamp": [
            pandas.Timestamp("1998-09-04T16:03:14"),
            pandas.Timestamp("2010-09-13T12:03:45"),
            pandas.Timestamp("2015-10-02T16:00:00"),
        ],
    }
)
client = bigquery.Client()
table_id = "my_dataset.new_table"
# Since string columns use the "object" dtype, pass in a (partial) schema
# to ensure the correct BigQuery data type.
job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("my_string", "STRING"),
    ]
)

job = client.load_table_from_dataframe(df, table_id, job_config=job_config)

# Wait for the load job to complete.
job.result()

Recursos não compatíveis com o pandas-gbq

Embora a biblioteca pandas-gbq forneça uma interface útil para consultar dados e gravar dados em tabelas, ela não abrange muitos recursos da API BigQuery, incluindo, entre outros:

Como gerenciar conjuntos de dados, incluindo a criação de novos conjuntos de dados, a atualização de propriedades do conjunto de dados e a exclusão de conjuntos de dados
Carregar dados no BigQuery de formatos diferentes do DataFrames do pandas
Como gerenciar tabelas, incluindo listar tabelas em um conjunto de dados, copiar dados de tabelas e excluir tabelas
Como exportar dados do BigQuery diretamente para o Cloud Storage