Como migrar do pandas-gbq

A biblioteca pandas-gbq é um projeto conduzido pela comunidade pandas. A biblioteca de cliente do BigQuery, google-cloud-bigquery, é a biblioteca oficial do Python para interagir com o BigQuery. Se você estiver usando a biblioteca pandas-gbq, já está usando a biblioteca google-cloud-bigquery. A biblioteca pandas-gbq usa o google-cloud-bigquery para fazer chamadas de API para o BigQuery. Ela fornece uma interface fácil do pandas para o BigQuery, mas não tem muitos dos recursos fornecidos pela biblioteca google-cloud-bigquery.

Este tópico inclui detalhes sobre as alterações necessárias para atualizar seu código Python para usar google-cloud-bigquery em vez de pandas-gbq. Os exemplos de código neste tópico usam as seguintes versões das duas bibliotecas:

google-cloud-bigquery[pandas,pyarrow]==1.7.0
pandas-gbq==0.7.0

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 e por colaboradores voluntários
Funcionalidade da API do BigQuery coberta Limitado a executar consultas e salvar dados de DataFrames do 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
Frequência de novos recursos Novos recursos só são adicionados à biblioteca se forem implementados por colaboradores voluntários Novos recursos são implementados à medida que são lançados na API do BigQuery
documentos/origem documentos/origem

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 SQL legado SQL padrão
Configurações de consulta Enviado como dicionário no formato especificado na referência REST do BigQuery. Usa a classe QueryJobConfig, que contém propriedades para as várias opções de configuração da API.

Como consultar dados com a sintaxe SQL padrão

A amostra a seguir mostra como executar uma consulta SQL padrão tanto especificando explicitamente um projeto quanto sem especificá-lo. 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. Veja o Guia de migração ao SQL padrão para orientação sobre como atualizar suas consultas para SQL padrão.

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 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 formato DataFrame para Parquet antes de enviar para a API, que é compatível com valores aninhados e de matriz. Observe que o pyarrow, que é o mecanismo parquet usado para enviar os dados do DataFrame para a API do BigQuery, precisa ser 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],
    }
)
full_table_id = 'my_dataset.new_table'
project_id = 'my-project-id'

df.to_gbq(full_table_id, project_id=project_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:

 pip install pyarrow

ou

 conda install -c conda-forge 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],
    }
)
client = bigquery.Client()
dataset_ref = client.dataset('my_dataset')
table_ref = dataset_ref.table('new_table')

client.load_table_from_dataframe(df, table_ref).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:

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Esta página
Comentários sobre a documentação
BigQuery
Comentários sobre o produto
Precisa de ajuda? Acesse nossa página de suporte.