Elige una biblioteca de Python

Puedes elegir entre tres bibliotecas de Python en BigQuery según tu caso práctico.

	Caso de uso	Mantenido por	Descripción
BigQuery DataFrames	Operaciones de AA y procesamiento de datos basadas en Python con procesamiento del servidor (por ejemplo, mediante ranuras)	Google	APIs de Pandas y scikit-learn implementadas con pushdown del servidor. Para obtener más información, consulta Introducción a BigQuery DataFrames.
pandas-gbq	Procesamiento de datos basado en Python mediante una copia de datos del cliente	Biblioteca de código abierto mantenida por PyData y contribuyentes voluntarios	Te permite mover datos hacia y desde DataFrames de Python en el cliente. Para obtener más información, consulta la documentación y el código fuente.
google-cloud-bigquery	Implementación, administración y consultas basadas en SQL de BigQuery	Biblioteca de código abierto mantenida por Google	Paquete de Python que une todas las APIs de BigQuery. Para obtener más información, consulta la documentación y el código fuente.

Usa pandas-gbq y google-cloud-bigquery

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. Ambas bibliotecas se enfocan en ayudarte a realizar análisis de datos con SQL.

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

Consultas en ejecución

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 de una solicitud de consulta.	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 de una solicitud de consulta. 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	De manera opcional, puedes especificar un esquema de tabla.	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

 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:

La administración de conjuntos de datos, que incluye la creación de conjuntos de datos nuevos, la actualización de las propiedades de los conjuntos de datos y la eliminación de conjuntos de datos
Carga datos en BigQuery en formatos que no sean DataFrames de pandas o de DataFrames de pandas con columnas JSON
La administración de tablas, que incluye la enumeración de las tablas de un conjunto de datos, la copia de datos de tablas y la eliminación de tablas
La exportación de datos de BigQuery directamente a Cloud Storage

Soluciona problemas de errores del grupo de conexiones

Cadena del error: Connection pool is full, discarding connection: bigquery.googleapis.com. Connection pool size: 10

Si usas el objeto de cliente de BigQuery predeterminado en Python, tienes un límite de 10 subprocesos porque el tamaño del grupo predeterminado para el HTTPAdapter de Python es 10. Para usar más de 10 conexiones, crea un objeto requests.adapters.HTTPAdapter personalizado. Por ejemplo:

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)