Usa BigQuery DataFrames

BigQuery DataFrames proporciona un DataFrame de Python y una API de aprendizaje automático (AA) con la tecnología del motor de BigQuery. BigQuery DataFrames es un paquete de código abierto. Puedes ejecutar pip install --upgrade bigframes para instalar la versión más reciente.

BigQuery DataFrames proporciona tres bibliotecas:

  • bigframes.pandas proporciona una API de Pandas que puedes usar para analizar y manipular datos en BigQuery. Muchas cargas de trabajo se pueden migrar de pandas a bigframes con solo cambiar algunas importaciones. La API de bigframes.pandas es escalable para admitir el procesamiento de terabytes de datos de BigQuery y usa el motor de consulta de BigQuery para realizar cálculos.
  • bigframes.bigquery proporciona muchas funciones de SQL de BigQuery que podrían no tener un equivalente de pandas.
  • bigframes.ml proporciona una API similar a la API de scikit-learn para el AA. Las funciones del AA en BigQuery DataFrames te permiten procesar previamente los datos y, luego, entrenar modelos en esos datos. También puedes encadenar estas acciones para crear canalizaciones de datos.

Roles obligatorios

Para obtener los permisos que necesitas para completar las tareas de este documento, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Además, cuando usas funciones remotas de BigQuery DataFrames o modelos remotos de BigQuery DataFrames para AA, necesitas el rol de administrador de IAM del proyecto (roles/resourcemanager.projectIamAdmin) si usas una conexión predeterminada de BigQuery o el rol de navegador (roles/browser) si usas una conexión preconfigurada. Este requisito se puede evitar si se configura la opción bigframes.pandas.options.bigquery.skip_bq_connection_check en True, en cuyo caso la conexión (predeterminada o preconfigurada) se usa tal como está sin ninguna existencia o permiso. Si usas la conexión preconfigurada y omites la verificación de conexión, verifica lo siguiente:

  • La conexión se crea en la ubicación correcta.
  • Si usas funciones remotas de BigQuery DataFrames, la cuenta de servicio tiene el rol de invocador de Cloud Run (roles/run.invoker) en el proyecto.
  • Si usas modelos remotos de BigQuery DataFrames ML, la cuenta de servicio tiene el rol de usuario de Vertex AI (roles/aiplatform.user) en el proyecto.

Cuando realizas la autenticación de usuario final en un entorno interactivo como un notebook, el REPL de Python o la línea de comandos, BigQuery DataFrames solicita la autenticación si es necesario. De lo contrario, consulta cómo configurar las credenciales predeterminadas de la aplicación para varios entornos.

Configura las opciones de instalación

Después de instalar BigQuery DataFrames, puedes especificar las siguientes opciones.

Ubicación y proyecto

Debes especificar la ubicación y proyecto en la que deseas usar BigQuery DataFrames.

Puedes definir la ubicación y el proyecto en tu notebook de la siguiente manera:

import bigframes.pandas as bpd

PROJECT_ID = "bigframes-dev"  # @param {type:"string"}
REGION = "US"  # @param {type:"string"}

# Set BigQuery DataFrames options
# Note: The project option is not required in all environments.
# On BigQuery Studio, the project ID is automatically detected.
bpd.options.bigquery.project = PROJECT_ID

# Note: The location option is not required.
# It defaults to the location of the first table or query
# passed to read_gbq(). For APIs where a location can't be
# auto-detected, the location defaults to the "US" location.
bpd.options.bigquery.location = REGION

Ubicación del procesamiento de datos

BigQuery DataFrames está diseñado para el escalamiento, lo que lo logra a través de la conservación de los datos y el procesamiento en el servicio de BigQuery. Sin embargo, puedes incorporar datos a la memoria de tu máquina cliente si llamas a .to_pandas() en un objeto de DataFrame o de serie. Si eliges hacerlo, se aplica la limitación de memoria de la máquina cliente.

Ubicación de la sesión

BigQuery DataFrames usa un objeto de sesión local para administrar metadatos de forma interna. Esta sesión está vinculada a una ubicación. BigQuery DataFrames usa la multirregional US como la ubicación predeterminada, pero puedes usar session_options.location para establecer una ubicación diferente. Cada consulta en una sesión se ejecuta en la ubicación en la que se creó la sesión. BigQuery DataFrames propaga automáticamente bf.options.bigquery.location con la ubicación de la tabla si el usuario comienza con read_gbq/read_gbq_table/read_gbq_query() y especifica una tabla, ya sea directamente o en una instrucción de SQL.

Si deseas restablecer la ubicación de los objetos DataFrame o de serie creados, puedes cerrar la sesión mediante la ejecución de bigframes.pandas.close_session(). Después de eso, puedes volver a usar bigframes.pandas.options.bigquery.location para especificar otra ubicación.

read_gbq() requiere que especifiques una ubicación si el conjunto de datos que consultas no está en la multirregión US. Si intentas leer una tabla desde otra ubicación, obtendrás una excepción NotFound.

Cómo migrar a BigQuery DataFrames versión 2.0

La versión 2.0 de BigQuery DataFrames realiza mejoras de seguridad y rendimiento en la API de BigQuery DataFrames, agrega funciones nuevas y presenta cambios rotundos. En este documento, se describen los cambios y se proporciona orientación para la migración. Puedes aplicar estas recomendaciones antes de instalar la versión 2.0 con la versión 1.x más reciente de BigQuery DataFrames.

BigQuery DataFrames versión 2.0 tiene los siguientes beneficios:

  • Se crean consultas más rápidas y menos tablas cuando ejecutas consultas que muestran resultados al cliente, ya que allow_large_results se establece de forma predeterminada en False. Esto puede reducir los costos de almacenamiento, en especial si usas la facturación de bytes físicos.
  • Seguridad mejorada de forma predeterminada en las funciones remotas que implementa BigQuery DataFrames

Instala la versión 2.0 de BigQuery DataFrames

Para evitar cambios drásticos, fija una versión específica de BigQuery DataFrames en tu archivo requirements.txt (por ejemplo, bigframes==1.42.0) o en tu archivo pyproject.toml (por ejemplo, dependencies = ["bigframes = 1.42.0"]). Cuando tengas todo listo para probar la versión más reciente, puedes ejecutar pip install --upgrade bigframes para instalar la versión más reciente de BigQuery DataFrames.

Usa la opción allow_large_results

BigQuery tiene un límite de tamaño máximo de respuesta para los trabajos de consulta. A partir de la versión 2.0 de BigQuery DataFrames, BigQuery DataFrames aplica este límite de forma predeterminada en los métodos que muestran resultados al cliente, como peek(), to_pandas() y to_pandas_batches(). Si tu trabajo muestra resultados grandes, puedes establecer allow_large_results en True en tu objeto BigQueryOptions para evitar cambios drásticos. Esta opción se establece en False de forma predeterminada en BigQuery DataFrames versión 2.0.

import bigframes.pandas as bpd

bpd.options.bigquery.allow_large_results = True

Puedes anular la opción allow_large_results con el parámetro allow_large_results en to_pandas() y otros métodos. Por ejemplo:

bf_df = bpd.read_gbq(query)
# ... other operations on bf_df ...
pandas_df = bf_df.to_pandas(allow_large_results=True)

Usa el decorador @remote_function

La versión 2.0 de BigQuery DataFrames realiza algunos cambios en el comportamiento predeterminado del decorador @remote_function.

Los argumentos de palabras clave se aplican de manera forzosa para los parámetros ambiguos

Para evitar pasar valores a un parámetro no deseado, BigQuery DataFrames versión 2.0 y versiones posteriores aplican el uso de argumentos de palabras clave para los siguientes parámetros:

  • bigquery_connection
  • reuse
  • name
  • packages
  • cloud_function_service_account
  • cloud_function_kms_key_name
  • cloud_function_docker_repository
  • max_batching_rows
  • cloud_function_timeout
  • cloud_function_max_instances
  • cloud_function_vpc_connector
  • cloud_function_memory_mib
  • cloud_function_ingress_settings

Cuando uses estos parámetros, proporciona el nombre del parámetro. Por ejemplo:

@remote_function(
  name="my_remote_function",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Cómo configurar una cuenta de servicio

A partir de la versión 2.0, BigQuery DataFrames ya no usa la cuenta de servicio de Compute Engine de forma predeterminada para las funciones de Cloud Run que implementa. Para limitar los permisos de la función que implementes, haz lo siguiente:

  1. Crea una cuenta de servicio con permisos mínimos.
  2. Proporciona el correo electrónico de la cuenta de servicio al parámetro cloud_function_service_account del decorador @remote_function.

Por ejemplo:

@remote_function(
  cloud_function_service_account="my-service-account@my-project.iam.gserviceaccount.com",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Si deseas usar la cuenta de servicio de Compute Engine, puedes establecer el parámetro cloud_function_service_account del decorador @remote_function en "default". Por ejemplo:

# This usage is discouraged. Use only if you have a specific reason to use the
# default Compute Engine service account.
@remote_function(cloud_function_service_account="default", ...)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Configura la configuración de entrada

A partir de la versión 2.0, BigQuery DataFrames establece la configuración de entrada de las funciones de Cloud Run que implementa en "internal-only". Anteriormente, la configuración de entrada se establecía en "all" de forma predeterminada. Puedes cambiar la configuración de entrada si estableces el parámetro cloud_function_ingress_settings del decorador @remote_function. Por ejemplo:

@remote_function(cloud_function_ingress_settings="internal-and-gclb", ...)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Usa extremos personalizados

En las versiones anteriores a la 2.0 de BigQuery DataFrames, si una región no era compatible con los endpoints de servicio regionales ni con bigframes.pandas.options.bigquery.use_regional_endpoints = True, BigQuery DataFrames recurría a los endpoints de ubicación. La versión 2.0 de BigQuery DataFrames quita este comportamiento de resguardo. Para conectarte a extremos de ubicación en la versión 2.0, configura la opción bigframes.pandas.options.bigquery.client_endpoints_override. Por ejemplo:

import bigframes.pandas as bpd

bpd.options.bigquery.client_endpoints_override = {
  "bqclient": "https://LOCATION-bigquery.googleapis.com",
  "bqconnectionclient": "LOCATION-bigqueryconnection.googleapis.com",
  "bqstoragereadclient": "LOCATION-bigquerystorage.googleapis.com",
}

Reemplaza LOCATION por el nombre de la ubicación de BigQuery a la que deseas conectarte.

Usa el módulo bigframes.ml.llm

En la versión 2.0 de BigQuery DataFrames, el model_name predeterminado para GeminiTextGenerator se actualizó a "gemini-2.0-flash-001". Te recomendamos que proporciones un model_name directamente para evitar fallas si el modelo predeterminado cambia en el futuro.

import bigframes.ml.llm

model = bigframes.ml.llm.GeminiTextGenerator(model_name="gemini-2.0-flash-001")

INPUT y OUTPUT

Con la biblioteca bigframes.pandas, puedes acceder a datos de varias fuentes, incluidos los archivos CSV locales, los archivos de Cloud Storage, los DataFrames pandas, los modelos de BigQuery y las funciones de BigQuery. Luego, puedes cargar esos datos en un DataFrame de BigQuery DataFrames. También puedes crear tablas de BigQuery DataFrames de BigQuery.

Carga datos desde una tabla o consulta de BigQuery

Puedes crear un DataFrame a partir de una consulta o tabla de BigQuery de la siguiente manera:

# Create a DataFrame from a BigQuery table:
import bigframes.pandas as bpd

query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

Carga datos desde un archivo CSV

Puedes crear un DataFrame desde un archivo CSV local o de Cloud Storage de la siguiente manera:

import bigframes.pandas as bpd

filepath_or_buffer = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
df_from_gcs = bpd.read_csv(filepath_or_buffer)
# Display the first few rows of the DataFrame:
df_from_gcs.head()

Tipos de datos

BigQuery DataFrames es compatible con los siguientes dtypes de NumPy y Pandas:

BigQuery BigQuery DataFrames y Pandas
ARRAY pandas.ArrowDtype(pa.list_())
BOOL pandas.BooleanDtype()
DATE pandas.ArrowDtype(pa.date32())
DATETIME pandas.ArrowDtype(pa.timestamp("us"))
FLOAT64 pandas.Float64Dtype()
GEOGRAPHY

geopandas.array.GeometryDtype()

Solo es compatible con to_pandas()
INT64 pandas.Int64Dtype()
JSON pandas.ArrowDtype(pa.json_(pa.string()) en pandas versión 3.0 o posterior y pyarrow versión 19.0 o posterior; de lo contrario, las columnas JSON se exponen como pandas.ArrowDtype(db_dtypes.JSONArrowType()).
STRING pandas.StringDtype(storage="pyarrow")
STRUCT pandas.ArrowDtype(pa.struct())
TIME pandas.ArrowDtype(pa.time64("us"))
TIMESTAMP pandas.ArrowDtype(pa.timestamp("us", tz="UTC"))

BigQuery DataFrames no es compatible con los siguientes tipos de datos de BigQuery:

  • NUMERIC

  • BIGNUMERIC

  • INTERVAL

  • RANGE

Todos los demás tipos de datos de BigQuery se muestran como el tipo de objeto.

Manipulación de datos

En las siguientes secciones, se describen las capacidades de manipulación de datos para los DataFrames de BigQuery. Puedes encontrar las funciones que se describen en la biblioteca bigframes.bigquery.

API de pandas

Una característica notable de BigQuery DataFrames es que la API de bigframes.pandas está diseñada para ser similar a las APIs de la biblioteca de Pandas. Este diseño te permite emplear patrones de sintaxis familiares para tareas de manipulación de datos. Las operaciones definidas a través de la API de BigQuery DataFrames se ejecutan del servidor, operan directamente en los datos almacenados en BigQuery y eliminan la necesidad de transferir conjuntos de datos fuera de BigQuery.

Para verificar qué APIs de pandas son compatibles con BigQuery DataFrames, consulta APIs de pandas compatibles.

Inspecciona y manipula datos

Puedes usar la API de bigframes.pandas para realizar operaciones de inspección y cálculo de datos. En la siguiente muestra de código, se usa la biblioteca bigframes.pandas para inspeccionar la columna body_mass_g, calcular la media body_mass y calcular la media body_mass por species:

import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Inspect one of the columns (or series) of the DataFrame:
bq_df["body_mass_g"]

# Compute the mean of this series:
average_body_mass = bq_df["body_mass_g"].mean()
print(f"average_body_mass: {average_body_mass}")

# Find the heaviest species using the groupby operation to calculate the
# mean body_mass_g:
(
    bq_df["body_mass_g"]
    .groupby(by=bq_df["species"])
    .mean()
    .sort_values(ascending=False)
    .head(10)
)

Biblioteca de BigQuery

La biblioteca de BigQuery proporciona funciones de SQL de BigQuery que podrían no tener un equivalente de pandas. En las siguientes secciones, se presentan algunos ejemplos.

Procesa valores de arrays

Puedes usar la función bigframes.bigquery.array_agg() en la biblioteca bigframes.bigquery para agregar valores después de una operación groupby:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

s = bpd.Series([0, 1, 2, 3, 4, 5])

# Group values by whether they are divisble by 2 and aggregate them into arrays
bbq.array_agg(s.groupby(s % 2 == 0))
# False    [1 3 5]
# True     [0 2 4]
# dtype: list<item: int64>[pyarrow]

También puedes usar las funciones de array array_length() y array_to_string().

Crea una serie de struct

Puedes usar la función bigframes.bigquery.struct() en la biblioteca bigframes.bigquery para crear una nueva serie de struct con subcampos para cada columna en un DataFrame:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create a new STRUCT Series with subfields for each column in a DataFrames.
lengths = bbq.struct(
    bq_df[["culmen_length_mm", "culmen_depth_mm", "flipper_length_mm"]]
)

lengths.peek()
# 146	{'culmen_length_mm': 51.1, 'culmen_depth_mm': ...
# 278	{'culmen_length_mm': 48.2, 'culmen_depth_mm': ...
# 337	{'culmen_length_mm': 36.4, 'culmen_depth_mm': ...
# 154	{'culmen_length_mm': 46.5, 'culmen_depth_mm': ...
# 185	{'culmen_length_mm': 50.1, 'culmen_depth_mm': ...
# dtype: struct[pyarrow]

Convierte marcas de tiempo en épocas de Unix

Puedes usar la función bigframes.bigquery.unix_micros() en la biblioteca bigframes.bigquery para convertir marcas de tiempo en microsegundos de Unix:

import pandas as pd

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Create a series that consists of three timestamps: [1970-01-01, 1970-01-02, 1970-01-03]
s = bpd.Series(pd.date_range("1970-01-01", periods=3, freq="d", tz="UTC"))

bbq.unix_micros(s)
# 0               0
# 1     86400000000
# 2    172800000000
# dtype: Int64

También puedes usar las funciones de hora unix_seconds() y unix_millis().

Usa la función escalar de SQL

Puedes usar la función bigframes.bigquery.sql_scalar() en la biblioteca bigframes.bigquery para acceder a una sintaxis de SQL arbitraria que represente una expresión de una sola columna:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"

# The sql_scalar function can be used to inject SQL syntax that is not supported
# or difficult to express with the bigframes.pandas APIs.
bq_df = bpd.read_gbq(query_or_table)
shortest = bbq.sql_scalar(
    "LEAST({0}, {1}, {2})",
    columns=[
        bq_df["culmen_depth_mm"],
        bq_df["culmen_length_mm"],
        bq_df["flipper_length_mm"],
    ],
)

shortest.peek()
#         0
# 149	18.9
# 33	16.3
# 296	17.2
# 287	17.0
# 307	15.0
# dtype: Float64

Funciones personalizadas de Python

BigQuery DataFrames te permite convertir tus funciones personalizadas de Python en artefactos de BigQuery que puedes ejecutar en objetos de BigQuery DataFrames a gran escala. Esta compatibilidad con la extensibilidad te permite realizar operaciones más allá de lo que es posible con BigQuery DataFrames y las APIs de SQL, de modo que puedas aprovechar las bibliotecas de código abierto. Las dos variantes de este mecanismo de extensibilidad se describen en las siguientes secciones.

Funciones definidas por el usuario (UDF)

Con las UDF (versión preliminar), puedes convertir tu función personalizada de Python en una UDF de Python. Para ver un ejemplo de uso, consulta Cómo crear una UDF persistente de Python.

Cuando creas una UDF en BigQuery DataFrames, se crea una rutina de BigQuery como la UDF de Python en el conjunto de datos especificado. Para obtener un conjunto completo de parámetros admitidos, consulta udf.

Limpia

Además de limpiar los artefactos de nube directamente en la consola de Google Cloud o con otras herramientas, puedes limpiar las UDF de BigQuery DataFrames que se crearon con un argumento de nombre explícito mediante el comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Requisitos

Para usar una UDF de BigQuery DataFrames, habilita la API de BigQuery en tu proyecto. Si proporcionas el parámetro bigquery_connection en tu proyecto, también debes habilitar la API de conexión de BigQuery.

Limitaciones

  • El código de la UDF debe ser independiente, es decir, no debe contener ninguna referencia a una importación o variable definida fuera del cuerpo de la función.
  • El código de la UDF debe ser compatible con Python 3.11, ya que ese es el entorno en el que se ejecuta el código en la nube.
  • Si vuelves a ejecutar el código de definición de la UDF después de realizar cambios simples en el código de la función, por ejemplo, cambiar el nombre de una variable o insertar una línea nueva, se volverá a crear la UDF, incluso si estos cambios no son importantes para el comportamiento de la función.
  • Los usuarios con acceso de lectura a las rutinas de BigQuery pueden ver el código del usuario, por lo que debes incluir contenido sensible solo con precaución.
  • Un proyecto puede tener hasta 1,000 funciones de Cloud Run a la vez en una ubicación de BigQuery.

La UDF de BigQuery DataFrames implementa una función de Python de BigQuery definida por el usuario, y se aplican las limitaciones relacionadas.

Funciones remotas

BigQuery DataFrames te permite convertir tus funciones escalares personalizadas en funciones remotas de BigQuery. Para ver un ejemplo de uso, consulta Crea una función remota. Para obtener un conjunto completo de parámetros admitidos, consulta remote_function.

Cuando se crea una función remota en BigQuery DataFrames, se crea lo siguiente:

  • Una función de Cloud Run
  • Una conexión de BigQuery. De forma predeterminada, se usa una conexión llamada bigframes-default-connection. Si lo prefieres, puedes usar una conexión de BigQuery preconfigurada, en cuyo caso se omite la creación de la conexión. A la cuenta de servicio para la conexión predeterminada se le otorga el rol de Cloud Run (roles/run.invoker).
  • Una función remota de BigQuery que usa la función de Cloud Run que se creó con la conexión de BigQuery.

Las conexiones de BigQuery se crean en la misma ubicación que la sesión de BigQuery DataFrames, con el nombre que proporcionas en la definición de la función personalizada. Para ver y administrar conexiones, haz lo siguiente:

  1. En la consola de Google Cloud , ve a la página BigQuery.

    Ir a BigQuery

  2. Selecciona el proyecto en el que creaste la función remota.

  3. En el panel Explorador, expande el proyecto y, luego, expande Conexiones externas.

Las funciones remotas de BigQuery se crean en el conjunto de datos que especificas o en un conjunto de datos anónimo, que es un tipo de conjunto de datos oculto. Si no estableces un nombre para una función remota durante su creación, BigQuery DataFrames aplica un nombre predeterminado que comienza con el prefijo bigframes. Para ver y administrar funciones remotas creadas en un conjunto de datos especificado por el usuario, haz lo siguiente:

  1. En la consola de Google Cloud , ve a la página BigQuery.

    Ir a BigQuery

  2. Selecciona el proyecto en el que creaste la función remota.

  3. En el panel Explorador, expande el proyecto, expande el conjunto de datos en el que creaste la función remota y, luego, expande Rutinas.

Para ver y administrar las funciones de Cloud Run, haz lo siguiente:

  1. Ir a la página Cloud Run.

    Ir a Cloud Run

  2. Selecciona el proyecto en el que creaste la función.

  3. Filtra por Tipo de implementación de funciones en la lista de servicios disponibles.

  4. Para identificar las funciones creadas por BigQuery DataFrames, busca nombres de funciones con el prefijo bigframes.

Limpia

Además de limpiar los artefactos de la nube directamente en la consola de Google Cloud o con otras herramientas, puedes limpiar las funciones remotas de BigQuery que se crearon sin un argumento de nombre explícito y sus funciones asociadas de Cloud Run de las siguientes maneras:

  • Para una sesión de BigQuery DataFrames, usa el comando session.close().
  • Para la sesión predeterminada de BigQuery DataFrames, usa el comando bigframes.pandas.close_session().
  • Para una sesión anterior con session_id, usa el comando bigframes.pandas.clean_up_by_session_id(session_id).

También puedes limpiar las funciones remotas de BigQuery que se crearon con un argumento de nombre explícito y sus funciones asociadas de Cloud Run con el comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Requisitos

Para usar las funciones remotas de BigQuery DataFrames, debes habilitar las siguientes APIs:

Limitaciones

  • Las funciones remotas tardan unos 90 segundos en estar disponibles cuando las creas por primera vez. Las dependencias de paquetes adicionales pueden aumentar la latencia.
  • Si vuelves a ejecutar el código de definición de la función remota después de realizar cambios simples en el código de la función, por ejemplo, cambiar el nombre de una variable, insertar una línea nueva o insertar una celda nueva en el notebook, es posible que se vuelva a crear la función remota, incluso si estos cambios no son importantes para el comportamiento de la función.
  • Los usuarios con acceso de lectura a las funciones de Cloud Run pueden ver el código del usuario, por lo que debes incluir contenido sensible solo con precaución.
  • Un proyecto puede tener hasta 1,000 funciones de Cloud Run a la vez en una región. Para obtener más información, consulta Cuotas.

IA y AA

En las siguientes secciones, se describen las capacidades de IA y de procesamiento de datos de BigQuery. Estas funciones usan la biblioteca bigframes.ml.

Ubicaciones de AA

La biblioteca de bigframes.ml admite las mismas ubicaciones que BigQuery ML. La predicción de modelos de BigQuery ML y otras funciones del AA son compatibles con todas las regiones de BigQuery. La compatibilidad de la entrenamiento de modelos varía según la región. Para obtener más información, consulta Ubicaciones de BigQuery ML.

Preprocesar datos

Crear transformadores para preparar datos para usar en estimadores (modelos) mediante el módulo bigframes.ml.preprocessing y el módulo bigframes.ml.compose BigQuery DataFrames ofrece las siguientes transformaciones:

  • Usa la clase KBinsDiscretizer en el módulo bigframes.ml.preprocessing para agrupar datos continuos en intervalos.

  • Usa la clase LabelEncoder en el módulo bigframes.ml.preprocessing para normalizar las etiquetas de destino como valores de números enteros.

  • Usa la clase MaxAbsScaler en el módulo bigframes.ml.preprocessing para escalar cada atributo al rango [-1, 1] según su valor absoluto máximo.

  • Usa la clase MinMaxScaler en el módulo bigframes.ml.preprocessing para estandarizar atributos mediante el escalamiento de cada atributo al rango [0, 1].

  • Usa la clase StandardScaler en el módulo bigframes.ml.preprocessing para estandarizar atributos mediante la eliminación de la media y la escala a la varianza de unidades.

  • Usa la clase OneHotEncoder en el módulo bigframes.ml.preprocessing para transformar los valores categóricos en formato numérico.

  • Usa la clase ColumnTransformer en el módulo bigframes.ml.compose para aplicar transformadores a las columnas de DataFrames.

Entrenar modelos

Puedes crear estimadores para entrenar modelos en BigQuery DataFrames.

Agrupa modelos en clústeres

Puedes crear estimadores para los modelos de agrupamiento en clústeres mediante el módulo bigframes.ml.cluster.

  • Usa la clase KMeans para crear modelos de agrupamiento en clústeres de K-means. Usa estos modelos para la segmentación de datos. Por ejemplo, identificar segmentos de clientes. K-means es una técnica de aprendizaje no supervisado, por lo que el entrenamiento de modelos no requiere etiquetas ni datos divididos para el entrenamiento o la evaluación.

Puedes usar el módulo bigframes.ml.cluster para crear estimadores para los modelos de agrupamiento en clústeres.

En la siguiente muestra de código, se usa la clase bigframes.ml.cluster KMeans para crear un modelo de agrupamiento en clústeres de k-means para la segmentación de datos:

from bigframes.ml.cluster import KMeans
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create the KMeans model
cluster_model = KMeans(n_clusters=10)
cluster_model.fit(bq_df["culmen_length_mm"], bq_df["sex"])

# Predict using the model
result = cluster_model.predict(bq_df)
# Score the model
score = cluster_model.score(bq_df)

Modelos de descomposición

Puedes crear estimadores para los modelos de descomposición mediante el módulo bigframes.ml.decomposition.

  • Usa la clase PCA para crear modelos de análisis de componentes principales (PCA). Usa estos modelos para calcular los componentes principales y usarlos a fin de realizar un cambio de base en los datos. Esto proporciona una reducción de la dimensionalidad mediante la proyección de cada dato a los primeros componentes principales para obtener datos de menor dimensión y, al mismo tiempo, conservar la mayor variación posible de los datos.

Ensamblar modelos

Puedes crear estimadores para modelos de ensamble con el módulo bigframes.ml.ensemble.

  • Usa la clase RandomForestClassifier para crear modelos clasificadores de bosque aleatorios. Usa estos modelos para construir varios árboles de decisión de métodos de aprendizaje para la clasificación.

  • Usa la clase RandomForestRegressor para crear modelos de regresión de bosque aleatorio. Usa estos modelos para construir varios árboles de decisión de métodos de aprendizaje para la regresión.

  • Usa la clase XGBClassifier para crear modelos clasificadores de árbol mejorado con gradiente. Usa estos modelos para construir de forma aditiva varios árboles de decisión de métodos de aprendizaje para la clasificación.

  • Usa la clase XGBRegressor para crear modelos de regresión de árbol mejorado con gradiente. Usa estos modelos para construir de forma aditiva varios árboles de decisión de métodos de aprendizaje para la regresión.

Modelos de previsión

Puedes crear estimadores para los modelos de previsión mediante el módulo bigframes.ml.forecasting.

  • Usa la clase ARIMAPlus para crear modelos de previsión de series temporales.

Modelos importados

Puedes crear estimadores para modelos importados con el módulo bigframes.ml.imported.

Modelos lineales

Crea estimadores para modelos lineales con el módulo bigframes.ml.linear_model.

  • Usa la clase LinearRegression para crear modelos de regresión lineal. Usa estos modelos para la previsión. Por ejemplo, la previsión de las ventas de un artículo en un día determinado.

  • Usa la clase LogisticRegression para crear modelos de regresión logística. Usa estos modelos para la clasificación de dos o más valores posibles, por ejemplo, si una entrada es low-value, medium-value o high-value.

En la siguiente muestra de código, se usa bigframes.ml para hacer lo siguiente:

from bigframes.ml.linear_model import LinearRegression
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Filter down to the data to the Adelie Penguin species
adelie_data = bq_df[bq_df.species == "Adelie Penguin (Pygoscelis adeliae)"]

# Drop the species column
adelie_data = adelie_data.drop(columns=["species"])

# Drop rows with nulls to get training data
training_data = adelie_data.dropna()

# Specify your feature (or input) columns and the label (or output) column:
feature_columns = training_data[
    ["island", "culmen_length_mm", "culmen_depth_mm", "flipper_length_mm", "sex"]
]
label_columns = training_data[["body_mass_g"]]

test_data = adelie_data[adelie_data.body_mass_g.isnull()]

# Create the linear model
model = LinearRegression()
model.fit(feature_columns, label_columns)

# Score the model
score = model.score(feature_columns, label_columns)

# Predict using the model
result = model.predict(test_data)

Modelos de lenguaje grandes

Puedes crear estimadores para LLM con el módulo bigframes.ml.llm.

Usa la clase GeminiTextGenerator para crear modelos de generador de texto de Gemini. Usa estos modelos para tareas de generación de texto.

Usa el módulo bigframes.ml.llm para crear estimadores para modelos remotos grandes de lenguaje (LLM).
En la siguiente muestra de código, se usa la clase bigframes.ml.llm GeminiTextGenerator para crear un modelo de Gemini para la generación de código:

from bigframes.ml.llm import GeminiTextGenerator
import bigframes.pandas as bpd

# Create the Gemini LLM model
session = bpd.get_global_session()
connection = f"{PROJECT_ID}.{REGION}.{CONN_NAME}"
model = GeminiTextGenerator(
    session=session, connection_name=connection, model_name="gemini-2.0-flash-001"
)

df_api = bpd.read_csv("gs://cloud-samples-data/vertex-ai/bigframe/df.csv")

# Prepare the prompts and send them to the LLM model for prediction
df_prompt_prefix = "Generate Pandas sample code for DataFrame."
df_prompt = df_prompt_prefix + df_api["API"]

# Predict using the model
df_pred = model.predict(df_prompt.to_frame(), max_output_tokens=1024)

Modelos remotos

Para usar los modelos remotos de BigQuery DataFrames (bigframes.ml.remote o bigframes.ml.llm), debes habilitar las siguientes APIs:

Cuando se crea un modelo remoto en BigQuery DataFrames, se crea una conexión de BigQuery. De forma predeterminada, se usa una conexión con el nombre bigframes-default-connection. Si lo prefieres, puedes usar una conexión de BigQuery preconfigurada, en cuyo caso se omite la creación de la conexión. A la cuenta de servicio para la conexión predeterminada se le otorga el rol de usuario de Vertex AI (roles/aiplatform.user) en el proyecto.

Crear canalizaciones

Puedes crear canalizaciones de AA con el módulo bigframes.ml.pipeline. Las canalizaciones te permiten ensamblar varios pasos del AA para realizar una validación cruzada mientras se configuran diferentes parámetros. Esto simplifica tu código y te permite implementar pasos de procesamiento previo de datos y un estimador juntos.

Usa la clase de canalización para crear una canalización de transformaciones con un estimador final.

Modelos seleccionados

Usa el módulo bigframes.ml.model_selection para dividir tus conjuntos de datos de entrenamiento y prueba, y seleccionar los mejores modelos:

  • Usa la función train_test_split para dividir los datos en conjuntos de entrenamiento y de prueba (evaluación), como se muestra en el siguiente muestra de código:

    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

  • Usa la clase KFold y el método KFold.split para crear conjuntos de entrenamiento y pruebas múltiples para entrenar y evaluar modelos, como se muestra en la siguiente muestra de código. Esta función es valiosa para conjuntos de datos pequeños.

    kf = KFold(n_splits=5)
for i, (X_train, X_test, y_train, y_test) in enumerate(kf.split(X, y)):
# Train and evaluate models with training and testing sets

  • Usa la función cross_validate para crear automáticamente conjuntos de entrenamiento y pruebas de varios pasos, entrenar y evaluar el modelo, y obtener el resultado de cada paso, como se muestra en la siguiente muestra de código:

    scores = cross_validate(model, X, y, cv=5)

Optimización del rendimiento

En esta sección, se presentan formas de optimizar el rendimiento de los DataFrames de BigQuery.

Modo de pedido parcial

BigQuery DataFrames proporciona una función de modo de ordenamiento. Establece la propiedad ordering_mode en partial para generar consultas más eficientes.

El modo de ordenamiento partial contrasta con el modo strict predeterminado, que crea un ordenamiento total en todas las filas. Un ordenamiento total hace que los DataFrames de BigQuery sean más compatibles con pandas, ya que proporciona acceso basado en el orden a las filas con la propiedad DataFrame.iloc. Sin embargo, el ordenamiento total y el índice secuencial predeterminado sobre ese ordenamiento significan que ni los filtros de columna ni los de fila reducen la cantidad de bytes analizados, a menos que esos filtros se apliquen como parámetros a las funciones read_gbq y read_gbq_table. Para proporcionar un ordenamiento total sobre todas las filas del DataFrame, BigQuery DataFrames crea un hash de todas las filas. Esto puede generar un análisis de datos completo que omita los filtros de filas y columnas.

Si estableces la propiedad ordering_mode en partial, se impide que los DataFrames de BigQuery generen un orden total en todas las filas. El modo de ordenamiento parcial también desactiva las funciones que requieren un ordenamiento total en todas las filas, como la propiedad DataFrame.iloc. El modo de ordenamiento parcial establece la clase DefaultIndexKind en un índice nulo, en lugar de un índice secuencial sobre el ordenamiento.

Cuando se filtra un DataFrame con la propiedad ordering_mode establecida en partial, BigQuery DataFrames ya no tiene que calcular qué filas faltan en el índice secuencial, por lo que genera consultas más rápidas y eficientes. La API de BigQuery DataFrames sigue siendo la API de pandas familiar, al igual que la experiencia predeterminada con el modo de ordenamiento estricto. Sin embargo, el modo de ordenamiento parcial diferirá del comportamiento común de pandas. Por ejemplo, el modo de ordenamiento parcial no realiza uniones implícitas por índice.

Con los modos de ordenamiento parcial y estricto, pagas por los recursos de BigQuery que usas. Sin embargo, usar el modo de ordenamiento parcial puede reducir los costos cuando se trabaja con tablas agrupadas y particionadas grandes, ya que los filtros de filas en las columnas de clúster y partición reducen la cantidad de bytes procesados.

Uso

Para usar el ordenamiento parcial, establece la propiedad ordering_mode en partial antes de realizar cualquier otra operación con BigQuery DataFrames, como se muestra en el siguiente muestra de código:

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

Debido a que no hay un índice secuencial con el modo de ordenamiento parcial, los DataFrames de BigQuery no relacionados no se unen de forma implícita. En su lugar, debes llamar de forma explícita al método DataFrame.merge para unir dos DataFrames de BigQuery que se derivan de diferentes expresiones de tabla.

Las funciones Series.unique() y Series.drop_duplicates() no son compatibles con el modo de ordenamiento parcial. En su lugar, usa el método groupby para encontrar valores únicos de esta manera:

# Avoid order dependency by using groupby instead of drop_duplicates.
unique_col = df.groupby(["column"], as_index=False).size().drop(columns="size")

Con el modo de ordenamiento parcial, el resultado de las funciones DataFrame.head(n) y Series.head(n) no es idempotente en todas las invocaciones. Para descargar una muestra pequeña y arbitraria de los datos, usa los métodos DataFrame.peek() o Series.peek().

Si deseas obtener un instructivo detallado en el que se usa la propiedad ordering_mode = "partial", consulta este notebook de BigQuery DataFrames en el que se muestra el uso del modo de ordenamiento parcial.

Soluciona problemas

Debido a que los DataFrames en el modo de ordenamiento parcial no siempre tienen un ordenamiento o un índice, es posible que encuentres los siguientes problemas cuando uses algunos métodos compatibles con pandas.

Error de pedido obligatorio

Algunas funciones requieren un orden, como las funciones DataFrame.head() y DataFrame.iloc. Para obtener una lista de las funciones que requieren orden, consulta la columna Requiere orden en APIs de pandas compatibles.

Cuando no hay orden en el objeto, la operación falla con un mensaje OrderRequiredError como el siguiente:

OrderRequiredError: Op iloc requires an ordering. Use .sort_values or .sort_index to provide an ordering.

Como se describe en el mensaje de error, puedes proporcionar un orden con el método DataFrame.sort_values() para ordenar por una o varias columnas. Otras operaciones, como la operación DataFrame.groupby(), proporcionan de forma implícita un orden total sobre el grupo por claves.

Si no se puede determinar que el orden es un orden total completamente estable en todas las filas, las operaciones posteriores podrían advertirte con un mensaje AmbiguousWindowWarning como el siguiente:

AmbiguousWindowWarning: Window ordering may be ambiguous, this can cause unstable results.

Si tu carga de trabajo puede admitir resultados no deterministas o puedes verificar manualmente que el orden que proporcionas es un orden total, puedes filtrar el mensaje AmbiguousWindowWarning de esta manera:

import warnings

import bigframes.exceptions

warnings.simplefilter(
    "ignore", category=bigframes.exceptions.AmbiguousWindowWarning
)
Error de índice nulo

Algunas funciones requieren un índice, como las propiedades DataFrame.unstack() y Series.interpolate(). Para obtener una lista de las funciones que requieren un índice, consulta la columna Requiere índice en APIs de pandas compatibles.

Cuando usas una operación que requiere un índice con el modo de ordenamiento parcial, la operación genera un mensaje NullIndexError como el siguiente:

NullIndexError: DataFrame cannot perform interpolate as it has no index. Set an index using set_index.

Como se describe en el mensaje de error, puedes proporcionar un índice con el método DataFrame.set_index() para ordenar por una o varias columnas. Otras operaciones, como la operación DataFrame.groupby(), proporcionan de forma implícita un índice sobre el grupo por claves, a menos que se configure el parámetro as_index=False.

Visualizaciones

La API de bigframes.pandas es una puerta de enlace al ecosistema completo de herramientas de Python. La API es compatible con operaciones estadísticas avanzadas, y puedes visualizar las agregaciones generadas a partir de BigQuery DataFrames. También puedes cambiar de un DataFrame de BigQuery DataFrames a un DataFrame pandas con operaciones de muestreo integradas.

¿Qué sigue?