Usa bibliotecas de Python de código abierto

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

Caso de uso Tamaño máximo de los datos Descripción
bigquery-dataframes Procesamiento de datos y operaciones de AA basados en Python con procesamiento del servidor Escalable a conjuntos de datos de varios terabytes (pushdown del servidor) 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 con copia de datos del cliente Limitado por la memoria del cliente 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 Limitado por la memoria del cliente 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 BigQuery DataFrames, pandas-gbq y google-cloud-bigquery

La biblioteca de BigQuery DataFrames (bigframes) proporciona un DataFrame de Python y una API de AA con procesamiento de consultas del servidor. La biblioteca pandas-gbq proporciona 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.

Instala las bibliotecas

Para usar las muestras de código de esta guía, instala los paquetes bigframes, pandas-gbq y google-cloud-bigquery:

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

Consultas en ejecución

Las tres bibliotecas admiten la consulta de datos almacenados en BigQuery. Las diferencias clave entre las bibliotecas incluyen lo siguiente:

bigquery-dataframes pandas-gbq google-cloud-bigquery
Sintaxis de SQL predeterminada GoogleSQL GoogleSQL (configurable con pandas_gbq.context.dialect) GoogleSQL
Configuraciones de consulta Configurable con los parámetros bpd.options.bigquery o read_gbq Se envía como un 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 las tres bibliotecas, si un proyecto no está especificado, se determinará desde las credenciales predeterminadas.

bigquery-dataframes 

import bigframes.pandas as bpd

# Set partial ordering mode as the default configuration for BigQuery
# DataFrames.
bpd.options.bigquery.ordering_mode = "partial"


def query_standard_sql(project_id: str = "your-project-id") -> bpd.DataFrame:
    sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = 'TX'
    LIMIT 100
    """

    # Run a query alongside existing SQL. The project will be determined from
    # default credentials.
    df = bpd.read_gbq(sql)

    # Run a query after explicitly specifying a project.
    bpd.close_session()
    bpd.options.bigquery.project = project_id
    df = bpd.read_gbq(sql)
    return df

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.

bigquery-dataframes

BigQuery DataFrames no admite la sintaxis de SQL heredado. En su lugar, usa la sintaxis de 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.

bigquery-dataframes 

import bigframes.pandas as bpd

import pandas as pd

# Set partial ordering mode as the default configuration for BigQuery
# DataFrames.
bpd.options.bigquery.ordering_mode = "partial"


def query_bqstorage() -> pd.DataFrame:
    sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = 'TX'
    LIMIT 100
    """

    # Read query results into a server-side DataFrame without downloading data.
    df = bpd.read_gbq(sql)

    # When downloading results to an in-memory pandas DataFrame,
    # bigquery-dataframes automatically uses the BigQuery Storage API if
    # installed.
    pandas_df = df.to_pandas()
    return pandas_df

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 solicitud a 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 bigquery-dataframes (read_gbq) y 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.

bigquery-dataframes 

import bigframes.pandas as bpd

# Set partial ordering mode as the default configuration for BigQuery
# DataFrames.
bpd.options.bigquery.ordering_mode = "partial"


def query_parameters() -> bpd.DataFrame:
    sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = @state
    LIMIT 100
    """

    query_config = {
        "query": {
            "parameterMode": "NAMED",
            "queryParameters": [
                {
                    "name": "state",
                    "parameterType": {"type": "STRING"},
                    "parameterValue": {"value": "TX"},
                }
            ],
        }
    }

    df = bpd.read_gbq(sql, configuration=query_config)
    return df

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

pandas-gbq y google-cloud-bigquery admiten la carga de datos de un 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 LoadJobConfig class, 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 serialice un DataFrame de Pandas en un archivo Parquet.

Instala el paquete 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 y bigquery-dataframes

Las bibliotecas pandas-gbq y bigquery-dataframes proporcionan interfaces útiles para consultar datos y escribirlos en tablas, pero no abarcan varias de las características de la API de BigQuery, como las siguientes:

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)