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 datos Descripción
bigquery-dataframes Operaciones de AA y procesamiento de datos basadas en Python con procesamiento del servidor Se puede escalar a conjuntos de datos de varios terabytes (transferencia de procesamiento al 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.

Uso de 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 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.

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 Se puede configurar con los parámetros bpd.options.bigquery o read_gbq Se envía como diccionario en el formato de una solicitud de búsqueda. 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 no se especifica un proyecto, este se determinará a partir de 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 las 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 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 bigquery-dataframes (read_gbq) y pandas-gbq, la configuración se debe enviar como un diccionario en el formato de una solicitud de búsqueda. 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

Las tres bibliotecas admiten la carga de datos de un DataFrame de Pandas a una tabla nueva en BigQuery. Las diferencias clave incluyen lo siguiente:

bigquery-dataframes pandas-gbq google-cloud-bigquery
Asistencia de tipo Convierte el DataFrame de Pandas local en un bigframes.pandas.DataFrame con read_pandas (con Parquet o CSV de forma interna), que admite valores de arreglo y anidados. Luego, lo guardas en una tabla con to_gbq. 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 Usa el parámetro if_exists ('fail', 'replace' o 'append') cuando guardes con to_gbq. 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.

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 upload_from_dataframe(
    table_id: str = "your-project.your_dataset.your_table_name",
) -> bpd.DataFrame:
    # Create a local pandas DataFrame.
    df = pd.DataFrame(
        {
            "my_string": ["a", "b", "c"],
            "my_int64": [1, 2, 3],
            "my_float64": [4.0, 5.0, 6.0],
        }
    )

    # Convert the local pandas DataFrame to a BigQuery DataFrame.
    bq_df = bpd.read_pandas(df)

    # Write the DataFrame to a BigQuery table.
    bq_df.to_gbq(table_id, if_exists="replace")
    return bq_df

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

Si bien las bibliotecas pandas-gbq y bigquery-dataframes proporcionan interfaces útiles para consultar datos y escribirlos en tablas, no abarcan muchas de las funciones de la API de BigQuery, incluidas, entre otras, 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)