Escolha uma biblioteca Python

Pode escolher entre três bibliotecas Python no BigQuery, com base no seu exemplo de utilização.

Exemplo de utilização Mantido por Descrição
DataFrames do BigQuery Processamento de dados e operações de ML baseados em Python com processamento do lado do servidor (por exemplo, através de espaços) Google APIs Pandas e Scikit learn implementadas com pushdown do lado do servidor. Para mais informações, consulte o artigo Introdução aos DataFrames do BigQuery.
pandas-gbq Tratamento de dados baseado em Python com a cópia de dados do lado do cliente Biblioteca de código aberto mantida pela PyData e colaboradores voluntários Permite-lhe mover dados para e a partir de DataFrames do Python do lado do cliente. Para mais informações, consulte a documentação e o código fonte.
google-cloud-bigquery Implementação, administração e consultas baseadas em SQL do BigQuery Biblioteca de código aberto mantida pela Google Pacote Python que envolve todas as APIs BigQuery. Para mais informações, consulte a documentação e o código fonte.

Usar o pandas-gbq e o google-cloud-bigquery

A biblioteca pandas-gbq oferece uma interface simples para executar consultas e carregar frames de dados do pandas para o BigQuery. É um wrapper simples em torno da biblioteca de cliente do BigQuery, google-cloud-bigquery. Ambas as bibliotecas focam-se em ajudar a realizar a análise de dados através de SQL.

Instale as bibliotecas

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

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

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

A executar consultas

Ambas as bibliotecas suportam a consulta de dados armazenados no BigQuery. As principais diferenças entre as bibliotecas incluem:

pandas-gbq google-cloud-bigquery
Sintaxe de SQL predefinida GoogleSQL (configurável com pandas_gbq.context.dialect) GoogleSQL
Configurações de consultas Enviado como dicionário no formato de um pedido 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 do GoogleSQL

O exemplo seguinte mostra como executar uma consulta GoogleSQL com e sem especificar explicitamente um projeto. Para ambas as bibliotecas, se não for especificado um projeto, o projeto é determinado a partir das credenciais predefinidas.

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()

Consultar dados com a sintaxe do SQL antigo

O exemplo seguinte mostra como executar uma consulta com a sintaxe SQL antiga. Consulte o guia de migração do GoogleSQL para ver orientações sobre como atualizar as 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()

Usar a API BigQuery Storage para transferir resultados grandes

Use a API BigQuery Storage para acelerar os downloads de grandes resultados 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()

Executar uma consulta com uma configuração

É necessário enviar uma configuração com um pedido API do BigQuery para realizar determinadas operações complexas, como executar uma consulta parametrizada ou especificar uma tabela de destino para armazenar os resultados da consulta. Em pandas-gbq, a configuração tem de ser enviada como um dicionário no formato de um pedido de consulta. No google-cloud-bigquery, são fornecidas classes de configuração de tarefas, como QueryJobConfig, que contêm as propriedades necessárias para configurar tarefas complexas.

O exemplo seguinte mostra como executar uma consulta com parâmetros com nomes.

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()

Carregar um DataFrame do pandas para uma tabela do BigQuery

Ambas as bibliotecas suportam o carregamento de dados de um pandas DataFrame para uma nova tabela no BigQuery. As principais diferenças incluem:

pandas-gbq google-cloud-bigquery
Suporte de tipos Converte o DataFrame para o formato CSV antes de o enviar para a API, que não suporta valores aninhados ou de matriz. Converte o DataFrame no formato Parquet ou CSV antes de o enviar para a API, que suporta 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 predefinida. Tenha em atenção que o pyarrow, que é o motor parquet usado para enviar os dados do DataFrame para a API BigQuery, tem de estar instalado para carregar o DataFrame para uma tabela.
Carregue configurações Opcionalmente, pode 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 a biblioteca pyarrow para serializar um pandas DataFrame num ficheiro 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()

Funcionalidades não suportadas pelo pandas-gbq

Embora a biblioteca pandas-gbq forneça uma interface útil para consultar dados e escrever dados em tabelas, não abrange muitas das funcionalidades da API BigQuery, incluindo, entre outras:

Resolução de problemas relacionados com erros do conjunto de ligações

Error string: Connection pool is full, discarding connection: bigquery.googleapis.com. Connection pool size: 10

Se usar o objeto cliente do BigQuery predefinido em Python, está limitado a um máximo de 10 threads, porque o tamanho do conjunto predefinido para o HTTPAdapter do Python é 10. Para usar mais de 10 associações, crie um objeto personalizado.requests.adapters.HTTPAdapter Por 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)