Escolher uma biblioteca Python

É possível escolher entre três bibliotecas Python no BigQuery, de acordo com o caso de uso.

	Caso de uso	Mantido por	Descrição
BigQuery DataFrames	Processamento de dados baseado em Python e operações de ML com processamento do lado do servidor (por exemplo, uso de slots)	Google	APIs do Pandas e do scikit-learn implementadas com o pushdown do lado do servidor. Para mais informações, consulte Introdução ao BigQuery DataFrames.
pandas-gbq	Processamento de dados baseado em Python usando uma cópia de dados do lado do cliente	Biblioteca de código aberto mantida pelo PyData e por colaboradores voluntários	Permite mover dados de/para DataFrames do Python no lado do cliente. Para mais informações, consulte a documentação e o código-fonte.
google-cloud-bigquery	Implantação, administração e consultas baseadas em SQL do BigQuery	Biblioteca de código aberto mantida pelo Google	Pacote Python que une todas as APIs do BigQuery. Para mais informações, consulte a documentação e o código-fonte.

Como usar pandas-gbq e google-cloud-bigquery

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 bibliotecas é ajudar você a realizar análises de dados usando SQL.

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.

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

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

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	Enviada como dicionário no formato de uma solicitação de consulta.	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 de uma solicitação de consulta. 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	Também é possível especificar um esquema de tabela.	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:

 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 de DataFrames do pandas ou de DataFrames do pandas com colunas JSON
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

Como solucionar erros do pool de conexão

String de erro: Connection pool is full, discarding connection: bigquery.googleapis.com. Connection pool size: 10

Se você usar o objeto do cliente padrão do BigQuery em Python, o limite será de 10 linhas de execução, já que o tamanho padrão do pool do Python HTTPAdapter é 10. Para usar mais de 10 conexões, crie um objeto requests.adapters.HTTPAdapter personalizado. Exemplo:

client = bigquery.Client()
adapter = requests.adapters.HTTPAdapter(pool_connections=128,
pool_maxsize=128,max_retries=3)
client._http.mount("https://",adapter)
client._http._auth_request.session.mount("https://",adapter)
query_job = client.query(QUERY)