Migra desde pandas-gbq

La biblioteca pandas-gbq es un proyecto liderado por la comunidad Pandas. La biblioteca cliente de BigQuery, google-cloud-bigquery, es la biblioteca oficial de Python para interactuar con BigQuery. Si usas la biblioteca pandas-gbq, también usas la biblioteca google-cloud-bigquery. pandas-gbq usa google-cloud-bigquery para realizar llamadas a la API a BigQuery.

En este tema, se ofrecen ejemplos de códigos que comparan google-cloud-bigquery y pandas-gbq. Los ejemplos de códigos incluidos en este tema usan las bibliotecas siguientes:

google-cloud-bigquery==1.20.0
google-cloud-bigquery-storage==0.7.0
pandas==0.25.1
pandas-gbq==0.11.0
pyarrow==0.14.1

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 Limitado a 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
Cadencia de característica nuevas Características nuevas agregadas a la biblioteca solo si se implementan por los contribuyentes voluntarios Se implementan funciones nuevas a medida que se las lanza en la API de BigQuery
documentos/fuente documentos/fuente

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 SQL estándar (configurable con pandas_gbq.context.dialect) SQL estándar
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 de las opciones de configuración de la API.

Consulta datos con la sintaxis SQL estándar

En el siguiente ejemplo, se muestra cómo ejecutar una consulta de SQL estándar con especificación explícita un proyecto o sin ella. 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 SQL estándar para obtener información sobre cómo actualizar tus consultas en SQL estándar.

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:

import google.auth
from google.cloud import bigquery
from google.cloud import bigquery_storage_v1beta1

# Create a BigQuery client and a BigQuery Storage API client with the same
# credentials to avoid authenticating twice.
credentials, project_id = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
client = bigquery.Client(credentials=credentials, project=project_id)
bqstorage_client = bigquery_storage_v1beta1.BigQueryStorageClient(
    credentials=credentials
)
sql = "SELECT * FROM `bigquery-public-data.irs_990.irs_990_2012`"

# Use a BigQuery Storage API client to download results more quickly.
df = client.query(sql).to_dataframe(bqstorage_client=bqstorage_client)

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 antes de enviarlo a la API, que es compatible con los valores de arreglo y anidados. 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()

Características 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: