Comparación con pandas-gbq

La biblioteca pandas-gbq ofrece una interfaz simple para ejecutar búsquedas y subir DataFrames de Pandas a BigQuery. Es un wrapper liviano que rodea la biblioteca cliente de BigQuery, google-cloud-bigquery. En este tema, se ofrecen ejemplos de códigos que comparan google-cloud-bigquery y pandas-gbq.

Las diferencias clave en el nivel de funcionalidad y compatibilidad entre las dos bibliotecas incluyen lo siguiente:

pandas-gbq google-cloud-bigquery
Asistencia Biblioteca de código abierto mantenida por PyData y contribuyentes voluntarios Biblioteca de código abierto mantenida por Google
Funcionalidad de la API de BigQuery cubierta Ejecutar consultas y guardar datos de DataFrames de Pandas en tablas Funcionalidad de la API de BigQuery completa con compatibilidad agregada para escritura y lectura de DataFrames de pandas y un Jupyter automático a fin de ejecutar consultas
documentos/fuente documentos/fuente

Instala las bibliotecas

Para usar las muestras de código de esta guía, instala el paquete pandas-gbq y las bibliotecas cliente de Python de BigQuery.

PIP

Instala los paquetes pandas-gbq y google-cloud-bigquery.

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

Conda

Instala los paquetes Conda pandas-gbq y google-cloud-bigquery del canal conda-forge administrado por la comunidad.

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

Ejecuta consultas

Ambas bibliotecas son compatibles con los datos de consultas almacenados en BigQuery. Las diferencias clave entre las bibliotecas incluyen lo siguiente:

pandas-gbq google-cloud-bigquery
Sintaxis de SQL predeterminada GoogleSQL (configurable con pandas_gbq.context.dialect) GoogleSQL
Configuraciones de consulta Enviado como diccionario en el formato especificado en la referencia de REST de BigQuery. Usa la clase QueryJobConfig, que contiene propiedades para las distintas opciones de configuración de la API.

Consulta datos con la sintaxis de GoogleSQL

En el siguiente ejemplo, se muestra cómo ejecutar una consulta de GoogleSQL con un proyecto o sin él. Para ambas bibliotecas, si un proyecto no está especificado, se determinará desde las credenciales predeterminadas.

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

Consulta datos con la sintaxis de SQL heredado

En el siguiente ejemplo, se muestra cómo ejecutar una consulta con la sintaxis de SQL heredado. Consulta la Guía de migración de GoogleSQL para obtener orientación sobre cómo actualizar las consultas a 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()

Usa la API de BigQuery Storage para descargar resultados grandes

Usa la API de BigQuery Storage para acelerar descargas de resultados grandes entre 15 y 31 veces.

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

Ejecuta una consulta con una configuración

Se requiere enviar una configuración con una consulta de la API de BigQuery a fin de realizar ciertas operaciones complejas, como ejecutar una consulta parametrizada o especificar una tabla de destino para almacenar los resultados de la consulta. En pandas-gbq, la configuración se debe enviar como un diccionario en el formato que se especifica en la referencia de REST de BigQuery. En google-cloud-bigquery, se proporcionan las clases de configuración de trabajos, como QueryJobConfig, que contiene las propiedades necesarias para configurar trabajos complejos.

En el siguiente ejemplo, se muestra cómo ejecutar una consulta mediante parámetros asignados.

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

Carga un DataFrame de pandas a una tabla de BigQuery

Ambas bibliotecas son compatibles con la carga de datos desde DataFrame de pandas a una tabla nueva en BigQuery. Las diferencias clave incluyen lo siguiente:

pandas-gbq google-cloud-bigquery
Asistencia de tipo Convierte el formato DataFrame en el formato CSV antes de enviarlo a la API, lo cual no es compatible con valores de arreglo o anidados. Convierte el formato DataFrame en el formato Parquet o CSV antes de enviarlo a la API, que es compatible con los valores de arreglo y anidados. Elige Parquet para los valores de struct y de array, y CSV para la flexibilidad de serialización de fecha y hora. Parquet es la opción predeterminada. Ten en cuenta que, para cargar el DataFrame en una tabla, debes tener instalado pyarrow, que es el motor de Parquet que se usa para enviar los datos de DataFrame a la API de BigQuery.
Configuraciones de carga Enviado como diccionario en el formato especificado en la referencia de REST de BigQuery. Usa la clase LoadJobConfig, que contiene propiedades para las distintas opciones de configuración de la 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:

El paquete google-cloud-bigquery requiere que la biblioteca pyarrow serialize un DataFrame de Pandas en un archivo Parquet.

Instala el paquete pyarrow:

 conda install -c conda-forge pyarrow

o

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

Funciones no compatibles con pandas-gbq

La biblioteca pandas-gbq proporciona una interfaz útil para consultar datos y escribirlos en tablas, pero no abarca varias de las características de la API de BigQuery, como las siguientes: