Trabaja con funciones definidas por el usuario en Python

Una función definida por el usuario (UDF) de Python te permite implementar una función escalar en Python y usarla en una consulta en SQL. Las UDF de Python son similares a las UDF de SQL y JavaScript, pero con capacidades adicionales. Las UDF de Python te permiten instalar bibliotecas de terceros desde el índice de paquetes de Python (PyPI) y acceder a servicios externos con una conexión de recursos de Cloud.

Las UDF de Python se compilan y ejecutan en recursos administrados de BigQuery.

Limitaciones

python-3.11 es el único tiempo de ejecución compatible.
No puedes crear una UDF de Python temporal.
No puedes usar una UDF de Python con una vista materializada.
Los resultados de una consulta que llama a una UDF de Python no se almacenan en caché porque siempre se supone que el valor de retorno de una UDF de Python no es determinista.
No se admiten las redes de VPC.
No se admiten las cargas de trabajo aseguradas.
No se admiten los siguientes tipos de datos: JSON, RANGE, INTERVAL y GEOGRAPHY.
Los contenedores que ejecutan UDF de Python solo se pueden configurar con hasta 4 vCPU y 16 GiB.
No se admiten las claves de encriptación administradas por el cliente (CMEK).

Roles obligatorios

Los roles de IAM requeridos dependen de si eres propietario o usuario de una UDF de Python.

Propietarios de UDF

Por lo general, el propietario de una UDF de Python crea o actualiza una UDF. También se requieren roles adicionales si creas una UDF de Python que hace referencia a una conexión de recursos de Cloud. Esta conexión solo es necesaria si tu UDF usa la cláusula WITH CONNECTION para acceder a un servicio externo.

Para obtener los permisos que necesitas para crear o actualizar una UDF de Python, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Editor de datos de BigQuery (roles/bigquery.dataEditor) en el conjunto de datos
Usuario de trabajo de BigQuery (roles/bigquery.jobUser) en el proyecto
Administrador de conexión de BigQuery (roles/bigquery.connectionAdmin) en el proyecto

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

Estos roles predefinidos contienen los permisos necesarios para crear o actualizar una UDF de Python. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear o actualizar una UDF de Python:

Crea una UDF de Python con la instrucción CREATE FUNCTION: bigquery.routines.create en el conjunto de datos
Actualiza una UDF de Python con la instrucción CREATE FUNCTION: bigquery.routines.update en el conjunto de datos
Ejecuta un trabajo de consulta de la instrucción CREATE FUNCTION: bigquery.jobs.create en el proyecto
Crea una nueva conexión de recurso de Cloud: bigquery.connections.create en el proyecto.
Usa una conexión en la instrucción CREATE FUNCTION: bigquery.connections.delegate en la conexión

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Para obtener más información sobre los roles en BigQuery, consulta Roles de IAM predefinidos.

Usuarios de UDF

Un usuario de una UDF de Python invoca una UDF creada por otra persona. También se requieren roles adicionales si invocas una UDF de Python que hace referencia a una conexión de recursos de Cloud.

Para obtener los permisos que necesitas para invocar una UDF de Python creada por otra persona, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Usuario de BigQuery (roles/bigquery.user) en el proyecto
Visualizador de datos de BigQuery (roles/bigquery.dataViewer) en el conjunto de datos
Usuario de conexión de BigQuery (roles/bigquery.connectionUser) en la conexión

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

Estos roles predefinidos contienen los permisos necesarios para invocar una UDF de Python creada por otra persona. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para invocar una UDF de Python creada por otra persona:

Para ejecutar un trabajo de consulta que haga referencia a una UDF de Python, haz lo siguiente: bigquery.jobs.create en el proyecto
Para invocar una UDF de Python creada por otra persona, sigue estos pasos: bigquery.routines.get en el conjunto de datos
Para ejecutar una UDF de Python que haga referencia a una conexión de recursos de Cloud, haz lo siguiente: bigquery.connections.use en la conexión

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Para obtener más información sobre los roles en BigQuery, consulta Roles de IAM predefinidos.

Llama a una UDF de Python

Si tienes permiso para invocar una UDF de Python, puedes llamarla como cualquier otra función. Para usar una función definida en un proyecto diferente, usa el nombre completamente calificado para la función. Por ejemplo, para llamar a la UDF de Python cw_xml_extract definida como una UDF de la comunidad de bigquery-utils, sigue estos pasos:

Console

Ve a la página de BigQuery.

Ir a BigQuery

En el editor de consultas, ingresa el siguiente ejemplo:

SELECT
  `bqutil`.`fn`.`cw_xml_extract`(xml, '//title/text()') AS `title`
FROM UNNEST([
  STRUCT('''<book id="1">
    <title>The Great Gatsby</title>
    <author>F. Scott Fitzgerald</author>
  </book>''' AS xml),
  STRUCT('''<book id="2">
    <title>1984</title>
    <author>George Orwell</author>
  </book>''' AS xml),
  STRUCT('''<book id="3">
    <title>Brave New World</title>
    <author>Aldous Huxley</author>
  </book>''' AS xml)
])

Haz clic en Ejecutar.

En este ejemplo, se produce el siguiente resultado:

+--------------------------+
| title                    |
+--------------------------+
| The Great Gatsby         |
| 1984                     |
| Brave New World          |
+--------------------------+

Permite trabajar con BigQuery DataFrames.

En el siguiente ejemplo, se usan los métodos BigQuery DataFrames sql_scalar, read_gbq_function y apply para llamar a una UDF de Python:

import textwrap
from typing import Tuple

import bigframes.pandas as bpd
import pandas as pd
import pyarrow as pa


# Using partial ordering mode enables more efficient query optimizations.
bpd.options.bigquery.ordering_mode = "partial"


def call_python_udf(
    project_id: str, location: str,
) -> Tuple[pd.Series, bpd.Series]:
    # Set the billing project to use for queries. This step is optional, as the
    # project can be inferred from your environment in many cases.
    bpd.options.bigquery.project = project_id  # "your-project-id"

    # Since this example works with local data, set a processing location.
    bpd.options.bigquery.location = location  # "US"

    # Create a sample series.
    xml_series = pd.Series(
        [
            textwrap.dedent(
                """
                <book id="1">
                    <title>The Great Gatsby</title>
                    <author>F. Scott Fitzgerald</author>
                </book>
                """
            ),
            textwrap.dedent(
                """
                <book id="2">
                    <title>1984</title>
                    <author>George Orwell</author>
                </book>
                """
            ),
            textwrap.dedent(
                """
                <book id="3">
                    <title>Brave New World</title>
                    <author>Aldous Huxley</author>
                </book>
                """
            ),
        ],
        dtype=pd.ArrowDtype(pa.string()),
    )
    df = pd.DataFrame({"xml": xml_series})

    # Use the BigQuery Accessor, which is automatically registered on pandas
    # DataFrames when you import bigframes.  This example uses a function that
    # has been deployed to bigquery-utils for demonstration purposes. To use in
    # production, deploy the function at
    # https://github.com/GoogleCloudPlatform/bigquery-utils/blob/master/udfs/community/cw_xml_extract.sqlx
    # to your own project.
    titles_pandas = df.bigquery.sql_scalar(
        "`bqutil`.`fn`.cw_xml_extract({xml}, '//title/text()')",
    )

    # Alternatively, call read_gbq_function to get a pointer to the function
    # that can be applied on BigQuery DataFrames objects.
    cw_xml_extract = bpd.read_gbq_function("bqutil.fn.cw_xml_extract")
    xml_bigframes = bpd.read_pandas(xml_series)

    xpath_query = "//title/text()"
    titles_bigframes = xml_bigframes.apply(cw_xml_extract, args=(xpath_query,))
    return titles_pandas, titles_bigframes

Crea una UDF de Python persistente

Sigue estas reglas cuando crees una UDF de Python:

El cuerpo de la UDF de Python debe ser un literal de cadena entre comillas que represente el código de Python. Para obtener más información sobre los literales de cadena entre comillas, consulta Formatos para literales entrecomillados.
El cuerpo de la UDF de Python debe incluir una función de Python que se use en el argumento entry_point de la lista de opciones de la UDF de Python.
Se debe especificar una versión del entorno de ejecución de Python en la opción runtime_version. La única versión del entorno de ejecución de Python compatible es python-3.11. Para obtener una lista completa de las opciones disponibles, consulta la lista de opciones de la función para la instrucción CREATE FUNCTION.

Para crear una UDF de Python persistente, usa la declaración CREATE FUNCTION sin la palabra clave TEMP o TEMPORARY. Para borrar una UDF de Python persistente, usa la declaración DROP FUNCTION.

Cuando creas una UDF de Python con la instrucción CREATE FUNCTION, BigQuery crea o actualiza una imagen de contenedor basada en una imagen base. El contenedor se compila en la imagen base con tu código y las dependencias de paquetes especificadas. La creación del contenedor es un proceso de larga duración. La primera consulta después de ejecutar la instrucción CREATE FUNCTION podría esperar automáticamente a que se complete la imagen. Sin dependencias externas, la imagen del contenedor se debería crear en menos de un minuto.

Ejemplo

Para ver un ejemplo de cómo crear una UDF de Python persistente, elige una de las siguientes opciones:

Console

En el siguiente ejemplo, se crea una UDF de Python persistente llamada multiplyInputs y se llama a la UDF desde una sentencia SELECT:

Ve a la página de BigQuery.

Ir a BigQuery

En el editor de consultas, ingresa la siguiente declaración CREATE FUNCTION:

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.multiplyInputs(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
LANGUAGE python
OPTIONS(runtime_version="python-3.11", entry_point="multiply")
AS r'''

def multiply(x, y):
    return x * y

''';

-- Call the Python UDF.
WITH numbers AS
    (SELECT 1 AS x, 5 as y
    UNION ALL
    SELECT 2 AS x, 10 as y
    UNION ALL
    SELECT 3 as x, 15 as y)
SELECT x, y,
`PROJECT_ID.DATASET_ID`.multiplyInputs(x, y) AS product
FROM numbers;

Reemplaza PROJECT_ID.DATASET_ID con el ID de tu proyecto y el ID del conjunto de datos.

Haz clic en Ejecutar.

En este ejemplo, se produce el siguiente resultado:

+-----+-----+--------------+
| x   | y   | product      |
+-----+-----+--------------+
| 1   | 5   |  5.0         |
| 2   | 10  | 20.0         |
| 3   | 15  | 45.0         |
+-----+-----+--------------+

Permite trabajar con BigQuery DataFrames.

En el siguiente ejemplo, se usan BigQuery DataFrames para convertir una función personalizada en una UDF de Python:

import bigframes.pandas as bpd

# Set BigQuery DataFrames options
bpd.options.bigquery.project = your_gcp_project_id
bpd.options.bigquery.location = "US"

# BigQuery DataFrames gives you the ability to turn your custom functions
# into a BigQuery Python UDF. One can find more details about the usage and
# the requirements via `help` command.
help(bpd.udf)

# Read a table and inspect the column of interest.
df = bpd.read_gbq("bigquery-public-data.ml_datasets.penguins")
df["body_mass_g"].peek(10)

# Define a custom function, and specify the intent to turn it into a
# BigQuery Python UDF. Let's try a `pandas`-like use case in which we want
# to apply a user defined function to every value in a `Series`, more
# specifically bucketize the `body_mass_g` value of the penguins, which is a
# real number, into a category, which is a string.
@bpd.udf(
    dataset=your_bq_dataset_id,
    name=your_bq_routine_id,
)
def get_bucket(num: float) -> str:
    if not num:
        return "NA"
    boundary = 4000
    return "at_or_above_4000" if num >= boundary else "below_4000"

# Then we can apply the udf on the `Series` of interest via
# `apply` API and store the result in a new column in the DataFrame.
df = df.assign(body_mass_bucket=df["body_mass_g"].apply(get_bucket))

# This will add a new column `body_mass_bucket` in the DataFrame. You can
# preview the original value and the bucketized value side by side.
df[["body_mass_g", "body_mass_bucket"]].peek(10)

# The above operation was possible by doing all the computation on the
# cloud through an underlying BigQuery Python UDF that was created to
# support the user's operations in the Python code.

# The BigQuery Python UDF created to support the BigQuery DataFrames
# udf can be located via a property `bigframes_bigquery_function`
# set in the udf object.
print(f"Created BQ Python UDF: {get_bucket.bigframes_bigquery_function}")

# If you have already defined a custom function in BigQuery, either via the
# BigQuery Google Cloud Console or with the `udf` decorator,
# or otherwise, you may use it with BigQuery DataFrames with the
# `read_gbq_function` method. More details are available via the `help`
# command.
help(bpd.read_gbq_function)

existing_get_bucket_bq_udf = get_bucket.bigframes_bigquery_function

# Here is an example of using `read_gbq_function` to load an existing
# BigQuery Python UDF.
df = bpd.read_gbq("bigquery-public-data.ml_datasets.penguins")
get_bucket_function = bpd.read_gbq_function(existing_get_bucket_bq_udf)

df = df.assign(body_mass_bucket=df["body_mass_g"].apply(get_bucket_function))
df.peek(10)

# Let's continue trying other potential use cases of udf. Let's say we
# consider the `species`, `island` and `sex` of the penguins sensitive
# information and want to redact that by replacing with their hash code
# instead. Let's define another scalar custom function and decorate it
# as a udf. The custom function in this example has external package
# dependency, which can be specified via `packages` parameter.
@bpd.udf(
    dataset=your_bq_dataset_id,
    name=your_bq_routine_id,
    packages=["cryptography"],
)
def get_hash(input: str) -> str:
    from cryptography.fernet import Fernet

    # handle missing value
    if input is None:
        input = ""

    key = Fernet.generate_key()
    f = Fernet(key)
    return f.encrypt(input.encode()).decode()

# We can use this udf in another `pandas`-like API `map` that
# can be applied on a DataFrame
df_redacted = df[["species", "island", "sex"]].map(get_hash)
df_redacted.peek(10)

# If the BigQuery routine is no longer needed, we can clean it up
# to free up any cloud quota
session = bpd.get_global_session()
session.bqclient.delete_routine(f"{your_bq_dataset_id}.{your_bq_routine_id}")

Crea una UDF de Python vectorizada

Puedes implementar tu UDF de Python para procesar un lote de filas en lugar de una sola fila usando la vectorización. La vectorización puede mejorar el rendimiento de las consultas. Puedes crear una UDF vectorizada con Pandas o Apache Arrow.

Para controlar el comportamiento del procesamiento por lotes, especifica la cantidad máxima de filas en cada lote con la opción max_batching_rows en la lista de opciones de CREATE OR REPLACE FUNCTION. Si especificas max_batching_rows, BigQuery determina la cantidad de filas en un lote, hasta el límite de max_batching_rows. Si no se especifica max_batching_rows, la cantidad de filas para el procesamiento por lotes se determina automáticamente.

Cómo usar Pandas

Una UDF de Python vectorizada tiene un solo argumento pandas.DataFrame que debe anotarse. El argumento pandas.DataFrame tiene la misma cantidad de columnas que los parámetros de la UDF de Python definidos en la instrucción CREATE FUNCTION. Los nombres de las columnas en el argumento pandas.DataFrame tienen los mismos nombres que los parámetros de la UDF.

Tu función debe devolver un pandas.Series o un pandas.DataFrame de una sola columna con la misma cantidad de filas que la entrada.

En el siguiente ejemplo, se crea una UDF de Python vectorizada llamada multiplyInputs con dos parámetros: x y y:

Ve a la página de BigQuery.

Ir a BigQuery

En el editor de consultas, ingresa la siguiente declaración CREATE FUNCTION:

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.multiplyVectorized(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
LANGUAGE python
OPTIONS(runtime_version="python-3.11", entry_point="vectorized_multiply")
AS r'''
import pandas as pd

def vectorized_multiply(df: pd.DataFrame):
  return df['x'] * df['y']

''';

Reemplaza PROJECT_ID.DATASET_ID con el ID de tu proyecto y el ID del conjunto de datos.

Llamar a la UDF es igual que en el ejemplo anterior.

Haz clic en Ejecutar.

Usa Apache Arrow

En el siguiente ejemplo, se usa la interfaz RecordBatch de Apache Arrow. Cuando usas la interfaz RecordBatch, la función pasa un lote de filas de columnas de igual longitud al punto de entrada. En el siguiente ejemplo, se usa Apache Arrow para crear una UDF de Python vectorizada llamada multiplyVectorizedArrow.

Ve a la página de BigQuery.

Ir a BigQuery

En el editor de consultas, ingresa la siguiente declaración CREATE FUNCTION:

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.multiplyVectorizedArrow(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
LANGUAGE python
OPTIONS(
  runtime_version="python-3.11",
  entry_point="vectorized_multiply_arrow"
)
AS r'''
import pyarrow as pa
import pyarrow.compute as pc

def vectorized_multiply_arrow(batch: pa.RecordBatch):
    # Access columns directly from the Arrow RecordBatch
    x = batch.column('x')
    y = batch.column('y')

    # Use pyarrow.compute for vectorized operations
    return pc.multiply(x, y)
''';

Reemplaza PROJECT_ID.DATASET_ID con el ID de tu proyecto y el ID del conjunto de datos.

Llamar a la UDF es igual que en los ejemplos anteriores.

Haz clic en Ejecutar.

Tipos de datos de UDF de Python admitidos

En la siguiente tabla, se define la asignación entre los tipos de datos de BigQuery, los tipos de datos de Python y los tipos de datos de Pandas:

Tipo de datos de BigQuery	Tipo de datos integrado de Python que usa la UDF estándar	Tipo de datos de Pandas que usa la UDF vectorizada	Tipo de datos de PyArrow que se usa para ARRAY y STRUCT en la UDF vectorizada
`BOOL`	`bool`	`BooleanDtype`	`DataType(bool)`
`INT64`	`int`	`Int64Dtype`	`DataType(int64)`
`FLOAT64`	`float`	`FloatDtype`	`DataType(double)`
`STRING`	`str`	`StringDtype`	`DataType(string)`
`BYTES`	`bytes`	`binary[pyarrow]`	`DataType(binary)`
`TIMESTAMP`	Parámetro de función: `datetime.datetime` (con la zona horaria UTC establecida) Valor que devuelve la función: `datetime.datetime` (con cualquier zona horaria establecida)	Parámetro de la función: `timestamp[us, tz=UTC][pyarrow]` Valor de retorno de la función: `timestamp[us, tz=*][pyarrow]\(any timezone\)`	`TimestampType(timestamp[us])`, con zona horaria
`DATE`	`datetime.date`	`date32[pyarrow]`	`DataType(date32[day])`
`TIME`	`datetime.time`	`time64[pyarrow]`	`Time64Type(time64[us])`
`DATETIME`	`datetime.datetime` (sin zona horaria)	`timestamp[us][pyarrow]`	`TimestampType(timestamp[us])`, sin zona horaria
`ARRAY`	`list`	`list<...>[pyarrow]`, en el que el tipo de datos del elemento es `pandas.ArrowDtype`	`ListType`
`STRUCT`	`dict`	`struct<...>[pyarrow]`, en el que el tipo de datos del campo es `pandas.ArrowDtype`	`StructType`

Versiones de entorno de ejecución compatibles

Las UDF de Python de BigQuery admiten el tiempo de ejecución de python-3.11. Esta versión de Python incluye algunos paquetes preinstalados adicionales. En el caso de las bibliotecas del sistema, verifica la imagen base del entorno de ejecución.

Versión de entorno de ejecución	Versión de Python	Incluye
python-3.11	Python 3.11	numpy 1.26.3 pyarrow 14.0.2 pandas 2.1.4 python-dateutil 2.8.2 absl-py 2.0.0 pytz 2023.3.post1 tzdata 2023.4 six 1.16.0 grpcio 1.76.0 grpcio-protobuf 6.33.5tools 1.76.0 typing-extensions 4.15.0

Usa paquetes de terceros

Puedes usar la lista de opciones de CREATE FUNCTION para usar módulos que no sean los que proporciona la biblioteca estándar de Python y los paquetes preinstalados. Puedes instalar paquetes desde el índice de paquetes de Python (PyPI) o importar archivos de Python desde Cloud Storage.

Instala un paquete desde el índice de paquetes de Python

Cuando instalas un paquete, debes proporcionar su nombre y, de manera opcional, puedes proporcionar su versión con los especificadores de versión de paquetes de Python.

Si el paquete está en el entorno de ejecución, se usa ese paquete, a menos que se especifique una versión en particular en la lista de opciones CREATE FUNCTION. Si no se especifica una versión del paquete y este no está en el tiempo de ejecución, se usa la versión disponible más reciente. Solo se admiten los paquetes con el formato binario de ruedas.

En el siguiente ejemplo, se muestra cómo crear una UDF de Python que instala el paquete scipy con la lista de opciones CREATE OR REPLACE FUNCTION:

Ve a la página de BigQuery.

Ir a BigQuery

En el editor de consultas, ingresa la siguiente declaración CREATE FUNCTION:

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.area(radius FLOAT64)
RETURNS FLOAT64 LANGUAGE python
OPTIONS (entry_point='area_handler', runtime_version='python-3.11', packages=['scipy==1.15.3'])
AS r"""
import scipy

def area_handler(radius):
  return scipy.constants.pi*radius*radius
""";

SELECT `PROJECT_ID.DATASET_ID`.area(4.5);

Reemplaza PROJECT_ID.DATASET_ID con el ID de tu proyecto y el ID del conjunto de datos.

Haz clic en Ejecutar.

Importa archivos de Python adicionales como bibliotecas

Puedes extender tus UDF de Python con la lista de opciones de funciones importando archivos de Python desde Cloud Storage.

En el código Python de tu UDF, puedes importar los archivos Python desde Cloud Storage como módulos con la instrucción import seguida de la ruta de acceso al objeto de Cloud Storage. Por ejemplo, si importas gs://BUCKET_NAME/path/to/lib1.py, tu instrucción de importación sería import path.to.lib1.

El nombre de archivo de Python debe ser un identificador de Python. Cada nombre de folder en el nombre del objeto (después de /) debe ser un identificador de Python válido. Dentro del rango ASCII (U+0001…U+007F), se pueden usar los siguientes caracteres en los identificadores:

Letras mayúsculas y minúsculas de la A a la Z
Guiones bajos
Los dígitos del cero al nueve, pero un número no puede aparecer como el primer carácter del identificador.

En el siguiente ejemplo, se muestra cómo crear una UDF de Python que importa el paquete de la biblioteca cliente lib1.py desde un bucket de Cloud Storage llamado my_bucket:

Ve a la página de BigQuery.

Ir a BigQuery

En el editor de consultas, ingresa la siguiente declaración CREATE FUNCTION:

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.myFunc(a FLOAT64, b STRING)
RETURNS STRING LANGUAGE python
OPTIONS (
entry_point='compute', runtime_version='python-3.11',
library=['gs://my_bucket/path/to/lib1.py'])
AS r"""
import path.to.lib1 as lib1

def compute(a, b):
  # doInterestingStuff is a function defined in
  # gs://my_bucket/path/to/lib1.py
  return lib1.doInterestingStuff(a, b);

""";

Reemplaza PROJECT_ID.DATASET_ID con el ID de tu proyecto y el ID del conjunto de datos.

Haz clic en Ejecutar.

Configura límites de contenedores para las UDF de Python

Puedes usar la lista de opciones de CREATE FUNCTION para especificar los límites de simultaneidad de solicitudes de CPU, memoria y contenedores para los contenedores que ejecutan UDF de Python.

De forma predeterminada, a los contenedores se les asignan los siguientes recursos:

La memoria asignada es de 512Mi.
La CPU asignada es de 1.0 CPU virtuales.
El límite de simultaneidad de solicitudes de contenedores es de 80.

En el siguiente ejemplo, se crea una UDF de Python con la lista de opciones CREATE FUNCTION para especificar los límites del contenedor:

Ve a la página de BigQuery.

Ir a BigQuery
En el editor de consultas, ingresa la siguiente declaración CREATE FUNCTION:
```
CREATE FUNCTION `PROJECT_ID.DATASET_ID`.resizeImage(image BYTES)
RETURNS BYTES LANGUAGE python
OPTIONS (entry_point='resize_image', runtime_version='python-3.11',
packages=['Pillow==11.2.1'], container_memory='CONTAINER_MEMORY', container_cpu=CONTAINER_CPU,
container_request_concurrency=CONTAINER_REQUEST_CONCURRENCY)
AS r"""
import io
from PIL import Image

def resize_image(image_bytes):
  img = Image.open(io.BytesIO(image_bytes))

  resized_img = img.resize((256, 256), Image.Resampling.LANCZOS)
  output_stream = io.BytesIO()
  resized_img.convert('RGB').save(output_stream, format='JPEG')
  return output_stream.getvalue()
""";
```
Reemplaza lo siguiente:
- PROJECT_ID.DATASET_ID: Tu ID del proyecto y el ID del conjunto de datos
- CONTAINER_MEMORY: Es el valor de la memoria en el siguiente formato: <integer_number><unit>. La unidad debe ser uno de estos valores: Mi (MiB), M (MB), Gi (GiB) o G (GB). Por ejemplo, 2Gi.
- CONTAINER_CPU: Es el valor de la CPU. Las UDF de Python admiten valores de CPU fraccionarios entre 0.33 y 1.0, y valores de CPU no fraccionarios de 1, 2 y 4.
- CONTAINER_REQUEST_CONCURRENCY: Es la cantidad máxima de solicitudes simultáneas por instancia de contenedor de UDF de Python. El valor debe ser un número entero entre 1 y 1000.
Haz clic en Ejecutar.

Valores de CPU admitidos

Las UDF de Python admiten valores de CPU fraccionarios entre 0.33 y 1.0, y valores de CPU no fraccionarios de 1, 2 y 4. Los contenedores que ejecutan UDF de Python se pueden configurar con hasta 4 CPU virtuales. El valor predeterminado es 1.0. Los valores de entrada fraccionarios se redondean a dos decimales antes de aplicarse al contenedor.

Valores de memoria admitidos

Los contenedores de UDF de Python admiten valores de memoria en el siguiente formato: <integer_number><unit>. La unidad debe ser uno de los siguientes valores: Mi, M, Gi o G. La cantidad mínima de memoria que puedes configurar es 256Mi. La cantidad máxima de memoria que puedes configurar es de 16Gi.

Según el valor de memoria que elijas, también debes especificar una cantidad adecuada de CPU. En la siguiente tabla, se muestran los valores mínimos y máximos de CPU para cada valor de memoria:

Memoria	CPU mínima	CPU máxima
De `256Mi` a `512Mi`	`0.33`	`2`
Mayor que `512Mi` y menor o igual que `1Gi`	`0.5`	`2`
Mayor que `1Gi` y menor que `2Gi`	`1`	`2`
De `2Gi` a `4Gi`	`1`	`4`
Mayor que `4Gi` y hasta `8Gi`	`2`	`4`
Mayor que `8Gi` y hasta `16Gi`	`4`	`4`

Como alternativa, si ya determinaste la cantidad de CPU que asignarás, puedes usar la siguiente tabla para determinar el rango de memoria adecuado:

CPU	Memoria mínima	Máximo de memoria
Menos de `0.5`	`256Mi`	`512Mi`
`0.5` a menos de `1`	`256Mi`	`1Gi`
`1`	`256Mi`	`4Gi`
`2`	`256Mi`	`8Gi`
`4`	`2Gi`	`16Gi`

Llama a Google Cloud servicios en línea en código Python

Una UDF de Python accede a un servicio Google Cloud o a un servicio externo con la cuenta de servicio de conexión de recursos de Cloud. Se deben otorgar permisos a la cuenta de servicio de la conexión para acceder al servicio. Los permisos necesarios varían según el servicio al que se accede y las APIs a las que se llama desde tu código de Python.

Si creas una UDF de Python sin usar una conexión de recursos de Cloud, la función se ejecutará en un entorno que bloquea el acceso a la red. Si tu UDF accede a servicios en línea, debes crearla con una conexión de recursos de Cloud. Si no lo haces, la UDF no podrá acceder a la red hasta que se alcance un tiempo de espera de conexión interno.

En el siguiente ejemplo, se muestra cómo acceder al servicio de Cloud Translation desde una UDF de Python. En este ejemplo, hay dos proyectos: uno llamado my_query_project en el que creas la UDF y la conexión de recursos de Cloud, y otro en el que ejecutas Cloud Translation llamado my_translate_project.

Crea una conexión de recursos de Cloud

Primero, crea una conexión de recursos de Cloud en my_query_project. Para crear la conexión del recurso de Cloud, sigue estos pasos.

Selecciona una de las siguientes opciones:

Console

Ve a la página de BigQuery.

Ir a BigQuery
En el panel de la izquierda, haz clic en Explorar.

Si no ves el panel izquierdo, haz clic en Expandir panel izquierdo para abrirlo.
En el panel Explorador, expande el nombre de tu proyecto y, luego, haz clic en Conexiones.
En la página Connections, haz clic en Create connection.
En Tipo de conexión, elige Modelos remotos de Vertex AI, funciones remotas, BigLake y Spanner (Cloud Resource).
En el campo ID de conexión, ingresa un nombre para tu conexión.
En Tipo de ubicación, selecciona una ubicación para tu conexión. La conexión debe estar ubicada junto con tus otros recursos, como los conjuntos de datos.
Haz clic en Crear conexión.
Haz clic en Ir a la conexión.
En el panel Información de conexión, copia el ID de la cuenta de servicio para usarlo en un paso posterior.

SQL

Usa la sentencia CREATE CONNECTION:

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

Ir a BigQuery
En el editor de consultas, escribe la siguiente oración:
```
CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME`
OPTIONS (
  connection_type = "CLOUD_RESOURCE",
  friendly_name = "FRIENDLY_NAME",
  description = "DESCRIPTION"
  );
```
Reemplaza lo siguiente:
- CONNECTION_NAME: Es el nombre de la conexión en formato PROJECT_ID.LOCATION.CONNECTION_ID, LOCATION.CONNECTION_ID o CONNECTION_ID. Si se omiten el proyecto o la ubicación, se infieren del proyecto y la ubicación en los que se ejecuta la instrucción.
- FRIENDLY_NAME (opcional): Es un nombre descriptivo para la conexión.
- DESCRIPTION (opcional): Es una descripción de la conexión.
Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

bq

En un entorno de línea de comandos, crea una conexión:
```
bq mk --connection --location=REGION --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE CONNECTION_ID
```
El parámetro --project_id anula el proyecto predeterminado.

Reemplaza lo siguiente:
- REGION: tu región de conexión
- PROJECT_ID: ID del proyecto de Google Cloud
- CONNECTION_ID: Es un ID para tu conexión.
Cuando creas un recurso de conexión, BigQuery crea una cuenta de servicio del sistema única y la asocia con la conexión.

Solución de problemas: Si recibes el siguiente error de conexión, actualiza el SDK de Google Cloud:
```
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
```

Recupera y copia el ID de cuenta de servicio para usarlo en un paso posterior:

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

El resultado es similar a lo siguiente:

name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

Node.js

Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

Terraform

Usa el recurso google_bigquery_connection.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se crea una conexión de recursos de Cloud llamada my_cloud_resource_connection en la región US:


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Para aplicar tu configuración de Terraform en un proyecto de Google Cloud , completa los pasos de las siguientes secciones.

Prepara Cloud Shell

Inicia Cloud Shell
Establece el proyecto Google Cloud predeterminado en el que deseas aplicar tus configuraciones de Terraform.

Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Las variables de entorno se anulan si configuras valores explícitos en el archivo de configuración de Terraform.

Prepara el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).

En Cloud Shell, crea un directorio y un archivo nuevo dentro de ese directorio. El nombre del archivo debe tener la extensión .tf, por ejemplo, main.tf. En este instructivo, el archivo se denomina main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Si sigues un instructivo, puedes copiar el código de muestra en cada sección o paso.

Copia el código de muestra en el main.tf recién creado.

De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.
Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
Guarda los cambios.
Inicializa Terraform. Solo debes hacerlo una vez por directorio.
```
terraform init
```
De manera opcional, incluye la opción -upgrade para usar la última versión del proveedor de Google:
```
terraform init -upgrade
```

Aplica los cambios

Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas:
```
terraform plan
```
Corrige la configuración según sea necesario.
Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe yes cuando se te solicite:
```
terraform apply
```
Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.
Abre tu proyecto Google Cloud para ver los resultados. En la consola de Google Cloud , navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.

Otorga acceso a la cuenta de servicio de la conexión

Necesitas el ID de la cuenta de servicio que copiaste antes cuando configures los permisos para la conexión. Cuando creas un recurso de conexión, BigQuery crea una cuenta de servicio del sistema única y la asocia con la conexión.

Para otorgar acceso a la cuenta de servicio de conexión de recursos de Cloud a tus proyectos, otórgale el rol de consumidor de uso del servicio (roles/serviceusage.serviceUsageConsumer) en my_query_project y el rol de usuario de la API de Cloud Translation (roles/cloudtranslate.user) en my_translate_project.

Ir a la página IAM.

Ir a IAM
Verifica que my_query_project esté seleccionado.
Haz clic en Otorgar acceso.
En el campo Principales nuevas, ingresa el ID de cuenta de servicio de la conexión a recursos de Cloud que copiaste antes.
En el campo Selecciona un rol, elige Uso del servicio y, luego, selecciona Consumidor de uso del servicio.
Haz clic en Guardar.
En el selector de proyectos, elige my_translate_project.
Ir a la página IAM.

Ir a IAM
Haz clic en Otorgar acceso.
En el campo Principales nuevas, ingresa el ID de cuenta de servicio de la conexión a recursos de Cloud que copiaste antes.
En el campo Selecciona un rol, elige Cloud Translation y, luego, selecciona Usuario de la API de Cloud Translation.
Haz clic en Guardar.

Crea una UDF de Python que llame al servicio de Cloud Translation

En my_query_project, crea una UDF de Python que llame al servicio de Cloud Translation con tu conexión de recursos de Cloud.

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

Ir a BigQuery

Ingresa la siguiente sentencia CREATE FUNCTION en el editor de consultas:

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.translate_to_es(x STRING)
RETURNS STRING LANGUAGE python
WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
OPTIONS (entry_point='do_translate', runtime_version='python-3.11', packages=['google-cloud-translate>=3.11', 'google-api-core'])
AS r"""

from google.api_core.retry import Retry
from google.cloud import translate

project = "my_translate_project"
translate_client = translate.TranslationServiceClient()

def do_translate(x : str) -> str:

    response = translate_client.translate_text(
        request={
            "parent": f"projects/{project}/locations/us-central1",
            "contents": [x],
            "target_language_code": "es",
            "mime_type": "text/plain",
        },
        retry=Retry(),
    )
    return response.translations[0].translated_text

""";

-- Call the UDF.
WITH text_table AS
  (SELECT "Hello" AS text
  UNION ALL
  SELECT "Good morning" AS text
  UNION ALL
  SELECT "Goodbye" AS text)
SELECT text,
`PROJECT_ID.DATASET_ID`.translate_to_es(text) AS translated_text
FROM text_table;

Reemplaza lo siguiente:

PROJECT_ID.DATASET_ID: Tu ID del proyecto y el ID del conjunto de datos
REGION.CONNECTION_ID: La región y el ID de tu conexión

Haz clic en Ejecutar.

El resultado debe verse de la siguiente manera:

+--------------------------+-------------------------------+
| text                     | translated_text               |
+--------------------------+-------------------------------+
| Hello                    | Hola                          |
| Good morning             | Buen dia                      |
| Goodbye                  | Adios                         |
+--------------------------+-------------------------------+

Prácticas recomendadas

Cuando crees UDFs de Python, sigue estas prácticas recomendadas:

Optimiza la lógica de tus consultas para el procesamiento por lotes. Las estructuras de consultas complejas pueden inhabilitar el procesamiento por lotes. Esto obliga a un procesamiento lento, fila por fila, lo que aumenta significativamente la latencia en conjuntos de datos grandes.
Evita las UDF en las expresiones condicionales.
Evita usar UDF para incorporar campos STRUCT directamente.
Aísla las UDF en las proyecciones. Para garantizar el procesamiento por lotes, ejecuta la UDF en una declaración SELECT con una expresión de tabla común (CTE) o una subconsulta. Luego, realiza filtros o uniones en ese resultado en un paso independiente.
Optimiza la carga útil de datos. El tamaño de las filas individuales puede afectar la eficiencia de la función de procesamiento por lotes.
Minimiza el tamaño de la fila. Mantén cada fila lo más pequeña posible para maximizar la cantidad de filas que se pueden procesar en un solo lote.
Configura los límites de los contenedores de manera eficiente. La escalabilidad es una función de la CPU, la memoria y la simultaneidad de solicitudes.
Cuando uses el ajuste iterativo, comienza con los valores predeterminados. Si el rendimiento no es óptimo, analiza las métricas de supervisión para identificar cuellos de botella específicos.
Escala tus recursos. Si las métricas de supervisión muestran niveles de uso altos, aumenta la CPU y la memoria asignadas.
Administrar las dependencias externas y la confiabilidad Las UDF que interactúan con servicios externos requieren una conexión y los permisos adecuados.
Implementa tiempos de espera de la API. Cuando tu UDF de Python acceda a Internet, establece un tiempo de espera en la llamada a la API para evitar comportamientos inesperados. Un ejemplo de acceso a Internet es la lectura desde un bucket de Cloud Storage.

Consulta las métricas de las UDF de Python

Las UDF de Python exportan métricas a Cloud Monitoring. Estas métricas te ayudan a supervisar varios aspectos del estado operativo y el consumo de recursos de tu UDF, y proporcionan estadísticas sobre el rendimiento y el comportamiento de tus instancias de UDF.

Tipo de recurso supervisado

Las métricas de las UDF de Python se registran en el siguiente tipo de recurso de Cloud Monitoring:

Tipo: bigquery.googleapis.com/ManagedRoutineInvocation
Nombre visible: Invocación de rutina administrada de BigQuery
Etiquetas:
- resource_container: Es el ID del proyecto en el que se ejecutó el trabajo de consulta.
- location: Es la ubicación en la que se ejecutó el trabajo de consulta.
- query_job_id: Es el ID del trabajo de consulta que invocó la UDF de Python.
- routine_project_id: Es el ID del proyecto en el que se almacena la rutina invocada.
- routine_dataset_id: Es el ID del conjunto de datos en el que se almacena la rutina invocada.
- routine_id: Es el ID de la rutina invocada.

Métricas

Las siguientes métricas están disponibles para el tipo de recurso bigquery.googleapis.com/ManagedRoutineInvocation:

Métrica	Descripción	Unidad	Tipo de valor
`bigquery.googleapis.com/managed_routine/python/cpu_utilizations`	Cuando se invoca una UDF de Python, esta métrica muestra la distribución del uso de CPU en todas las instancias de UDF de Python para el trabajo de la consulta.	10².%	`DISTRIBUTION`
`bigquery.googleapis.com/managed_routine/python/memory_utilizations`	Cuando se invoca una UDF de Python, esta métrica muestra la distribución del uso de memoria en todas las instancias de UDF de Python para el trabajo de la consulta.	10².%	`DISTRIBUTION`
`bigquery.googleapis.com/managed_routine/python/max_request_concurrencies`	Esta métrica muestra la distribución de la cantidad máxima de solicitudes simultáneas que entrega cada instancia de UDF de Python.	Recuento	`DISTRIBUTION`

Ver métricas

Para ver las métricas de tus UDF de Python, elige una de las opciones de las siguientes secciones.

Detalles del trabajo

Para ver las métricas de las UDF de Python de un trabajo de consulta específico, sigue estos pasos:

Ve a la página de BigQuery.

Ir a BigQuery
Haz clic en Historial de trabajos.
En la columna ID de trabajo, haz clic en el ID del trabajo de la consulta.
En la página Detalles del trabajo de consulta, haz clic en Panel de Cloud Monitoring. Este vínculo muestra un panel filtrado para mostrar las métricas de la UDF de Python para el trabajo.

Explorador de métricas

Para ver las métricas de las UDF de Python en el Explorador de métricas, sigue estos pasos:

Ve a la página Explorador de métricas de Cloud Monitoring.

Ir al Explorador de métricas
Haz clic en Seleccionar una métrica y, en el campo Filtro, escribe BigQuery Managed Routine Invocation o bigquery.googleapis.com/ManagedRoutineInvocation.
Elige Bigquery Managed Routine > Managed_routine.
Haz clic en cualquiera de las métricas disponibles, como las siguientes:
- Uso de CPU de la instancia
- Uso de memoria de la instancia
- Máx. de solicitudes simultáneas
Haz clic en Aplicar.

De forma predeterminada, las métricas se muestran en un gráfico.
Puedes filtrar y agrupar las métricas con las etiquetas definidas en los tipos de recursos de Monitoring. Para filtrar las métricas, sigue estos pasos:
1. En el campo Filtro, elige un tipo de recurso, como query_job_id o routine_id.
2. En el campo Valor, ingresa el ID del trabajo o de la rutina, o elige uno de la lista.

Paneles de Cloud Monitoring

Para ver las métricas de las UDF de Python con los paneles de supervisión, sigue estos pasos:

Ve a la página Paneles de Cloud Monitoring.

Ir a Paneles
Haz clic en el panel Supervisión de consultas de rutina administrada de BigQuery.

En este panel, se proporciona una descripción general de las métricas clave de tus UDF.
Para filtrar este panel, sigue estos pasos:
1. Haz clic en Filtrar.
2. En la lista Filtrar por recurso, elige una opción, como ID del proyecto, ubicación, ID de rutina o ID de trabajo.

Ubicaciones admitidas

Las UDF de Python son compatibles con todas las ubicaciones regionales y multirregionales de BigQuery.

Precios

Las UDF de Python se ofrecen sin cargos adicionales.

Cuando la facturación está habilitada, se aplican las siguientes condiciones:

Los cargos por las UDF de Python se facturan con el SKU de los servicios de BigQuery.
Los cargos son proporcionales a la cantidad de procesamiento y memoria consumidos cuando se invoca la UDF de Python.
A los clientes de UDF de Python también se les cobra el costo de compilar o volver a compilar la imagen del contenedor de la UDF. Este cargo es proporcional a los recursos que se usan para compilar la imagen con el código y las dependencias del cliente.
Si las UDF de Python generan salida de red externa o de Internet, también verás un cargo de salida de Internet de nivel Premium de Cloud Networking.

Cuotas

Consulta Cuotas y límites de UDF.