Funciones definidas por el usuario en Python

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

Las UDFs de Python se compilan y se ejecutan en recursos gestionados de BigQuery.

Limitaciones

• python-3.11 es el único entorno de ejecución compatible.
• No puedes crear una UDF de Python temporal.
• No puedes usar una función definida por el usuario de Python con una vista materializada.
• Los resultados de una consulta que llama a una FDU de Python no se almacenan en caché porque se supone que el valor devuelto de una FDU de Python siempre es no determinista.
• Las funciones definidas por el usuario de Python no son totalmente compatibles con las vistas de INFORMATION_SCHEMA.
• No puedes crear ni actualizar una función definida por el usuario (UDF) de Python con la API Routine.
• Controles de Servicio de VPC no es compatible.
• Las claves de cifrado gestionadas por el cliente (CMEK) no se admiten.
• No se admiten los siguientes tipos de datos: JSON, RANGE, INTERVAL y GEOGRAPHY.
• Los contenedores que ejecutan funciones definidas por el usuario de Python solo se pueden configurar con un máximo de 2 vCPU y 8 Gi.

Roles de gestión de identidades y accesos necesarios

Los roles de gestión de identidades y accesos necesarios dependen de si eres propietario o usuario de una FDU de Python. El propietario de una función definida por el usuario de Python suele crear o actualizar una función definida por el usuario. Un usuario de UDF de Python invoca una UDF creada por otra persona.

También se necesitan roles adicionales si creas o ejecutas una función definida por el usuario (UDF) de Python que haga referencia a una conexión de recursos de Cloud.

Propietarios de UDF

Si vas a crear o actualizar una función definida por el usuario (UDF) de Python, debes asignar los siguientes roles de gestión de identidades y accesos predefinidos al recurso correspondiente:

Usuarios de FDU

Si invocas una función definida por el usuario (UDF) de Python, se deben conceder los siguientes roles de gestión de identidades y accesos predefinidos en el recurso correspondiente:

Para obtener más información sobre los roles de BigQuery, consulta el artículo sobre los roles de gestión de identidades y accesos predefinidos.

Crear una FDU de Python persistente

Sigue estas reglas cuando crees una función definida por el usuario de Python:

• El cuerpo de la función definida por el usuario 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 de literales entre comillas.

• El cuerpo de la UDF de Python debe incluir una función de Python que se utilice 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 runtime_version opción. La única versión del entorno de ejecución de Python compatible es python-3.11. Para ver una lista completa de las opciones disponibles, consulta la lista de opciones de la función de la instrucción CREATE FUNCTION.

Para crear una FDU de Python persistente, usa la instrucción CREATE FUNCTION sin las palabras clave TEMP ni TEMPORARY. Para eliminar una UDF de Python persistente, usa la instrucció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 crea a partir de la imagen base con tu código y las dependencias de paquetes que hayas especificado. La creación del contenedor es un proceso de larga duración. Es posible que la primera consulta después de ejecutar la instrucción CREATE FUNCTION espere automáticamente a que se complete la imagen. Sin dependencias externas, la imagen de contenedor se suele 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:

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}")

Crear una función definida por el usuario de Python vectorizada

Puedes implementar tu FDU de Python para procesar un lote de filas en lugar de una sola fila mediante la vectorización. La vectorización puede mejorar el rendimiento de las consultas.

Para controlar el comportamiento de la creación de lotes, especifique el número máximo de filas de cada lote mediante la opción max_batching_rows de la lista de opciones CREATE OR REPLACE FUNCTION. Si especificas max_batching_rows, BigQuery determina el número de filas de un lote, hasta el límite de max_batching_rows. Si no se especifica max_batching_rows, el número de filas que se incluirán en el lote se determina automáticamente.

Una función definida por el usuario de Python vectorizada tiene un solo argumento pandas.DataFrame que debe anotarse. El argumento pandas.DataFrame tiene el mismo número de columnas que los parámetros de la función definida por el usuario de Python definidos en la instrucción CREATE FUNCTION. Los nombres de las columnas del argumento pandas.DataFrame son los mismos que los de los parámetros de la función definida por el usuario.

Tu función debe devolver un pandas.Series o un pandas.DataFrame de una sola columna con el mismo número de filas que la entrada.

En el siguiente ejemplo se crea una función definida por el usuario (UDF) de Python vectorizada llamada multiplyInputs con dos parámetros: x y y.

1. Ve a la página BigQuery.

   Ir a BigQuery

2. En el editor de consultas, introduce la siguiente instrucció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']
   
   ''';

   Reemplazar PROJECT_ID.DATASET_ID por el ID de tu proyecto y el ID del conjunto de datos.

   Llamar a la función definida por el usuario es igual que en el ejemplo anterior.

3. Haz clic en play_circle_filled Ejecutar.

Tipos de datos de funciones definidas por el usuario 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:

Versiones de tiempo de ejecución compatibles

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

Usar paquetes de terceros

Puedes usar la lista de opciones de CREATE FUNCTION para usar módulos distintos de los que proporcionan 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.

Instalar un paquete desde el índice de paquetes de Python

Cuando instalas un paquete, debes proporcionar el nombre del paquete y, opcionalmente, la versión del paquete mediante especificadores de versión de paquetes de Python. Si el paquete está en el tiempo de ejecución, se usará ese paquete, a menos que se especifique una versión concreta en la lista de opciones de CREATE FUNCTION. Si no se especifica una versión del paquete y el paquete no está en el tiempo de ejecución, se usará la última versión disponible. Solo se admiten 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 mediante la lista de opciones CREATE OR REPLACE FUNCTION:

1. Ve a la página BigQuery.

   Ir a BigQuery

2. En el editor de consultas, introduce la siguiente instrucció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);

   Reemplazar PROJECT_ID.DATASET_ID por el ID de tu proyecto y el ID del conjunto de datos.

3. Haz clic en play_circle_filled Ejecutar.

Importar archivos de Python adicionales como bibliotecas

Puedes ampliar tus UDFs 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 de Cloud Storage como módulos mediante la instrucción import seguida de la ruta al objeto de Cloud Storage. Por ejemplo, si vas a importar gs://BUCKET_NAME/path/to/lib1.py, la instrucción de importación sería import path.to.lib1.

El nombre del archivo de Python debe ser un identificador de Python. Cada nombre folder del nombre del objeto (después de /) debe ser un identificador de Python válido. Dentro del intervalo 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 primer carácter del identificador.

En el siguiente ejemplo se muestra cómo crear una función definida por el usuario (UDF) de Python que importa el paquete de la biblioteca de cliente lib1.py desde un segmento de Cloud Storage llamado my_bucket:

1. Ve a la página BigQuery.

   Ir a BigQuery

2. En el editor de consultas, introduce la siguiente instrucció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);
   
   """;

   Reemplazar PROJECT_ID.DATASET_ID por el ID de tu proyecto y el ID del conjunto de datos.

3. Haz clic en play_circle_filled Ejecutar.

Configurar límites de contenedores para funciones definidas por el usuario de Python

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

De forma predeterminada, la memoria asignada a cada instancia de contenedor es de 512 MiB y la CPU asignada es de 0,33 vCPU.

En el siguiente ejemplo se crea una función definida por el usuario (UDF) de Python con la lista de opciones CREATE FUNCTION para especificar los límites del contenedor:

1. Ve a la página BigQuery.

   Ir a BigQuery

2. En el editor de consultas, introduce la siguiente instrucció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='2Gi', container_cpu=1)
   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()
   """;

   Reemplazar PROJECT_ID.DATASET_ID por el ID de tu proyecto y el ID del conjunto de datos.

3. Haz clic en play_circle_filled Ejecutar.

Valores de CPU admitidos

Las UDFs de Python admiten valores de CPU fraccionarios entre 0.33 y 1.0, y valores de CPU no fraccionarios de 1 y 2. Los valores de entrada fraccionarios se redondean a dos decimales antes de aplicarse al contenedor.

Valores de memoria admitidos

Los contenedores de UDFs de Python admiten valores de memoria con el siguiente formato: <integer_number><unit>. La unidad debe ser uno de estos valores: Mi, M, Gi o G. La cantidad mínima de memoria que puedes configurar es de 256 mebibytes (256 Mi). La cantidad máxima de memoria que puedes configurar es de 8 gibibytes (8 Gi).

En función del valor de memoria que elijas, también debes especificar la cantidad mínima de CPU. En la siguiente tabla se muestran los valores mínimos de CPU para cada valor de memoria:

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

Una función definida por el usuario (UDF) de Python accede a un Google Cloud servicio o a un servicio externo mediante la cuenta de servicio Conexión de recursos de Cloud. La cuenta de servicio de la conexión debe tener permisos para acceder al servicio. Los permisos necesarios varían en función del servicio al que se acceda y de las APIs a las que se llame desde tu código Python.

Si creas una función definida por el usuario (UDF) de Python sin usar una conexión de recursos de Cloud, la función se ejecuta en un entorno que bloquea el acceso a la red. Si tu función definida por el usuario accede a servicios online, debes crearla con una conexión de recursos de Cloud. Si no lo haces, se bloqueará el acceso de la UDF 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 Cloud Translation desde una función definida por el usuario (UDF) de Python. En este ejemplo, hay dos proyectos: uno llamado my_query_project, en el que se crea la UDF y la conexión de recursos de Cloud, y otro llamado my_translate_project, en el que se ejecuta Cloud Translation.

Crear 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 de recursos de nube, sigue los pasos que se indican en la página Crear una conexión de recursos de nube.

Después de crear la conexión, ábrela y, en el panel Información de la conexión, copia el ID de la cuenta de servicio. Necesitarás este ID cuando configures los permisos de la conexión. Cuando creas un recurso de conexión, BigQuery crea una cuenta de servicio del sistema única y la asocia a la conexión.

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

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

1. Ve a la página Gestión de identidades y accesos.

   Ir a IAM

2. Verifica que my_query_project esté seleccionado.

3. Haz clic en person_add Conceder acceso.

4. En el campo Nuevos principales, introduce el ID de cuenta de servicio de la conexión de recursos de Cloud que has copiado anteriormente.

5. En el campo Selecciona un rol, elige Uso del servicio y, a continuación, Consumidor de uso del servicio.

6. Haz clic en Guardar.

7. En el selector de proyectos, elige my_translate_project.

8. Ve a la página Gestión de identidades y accesos.

   Ir a IAM

9. Haz clic en person_add Conceder acceso.

10. En el campo Nuevos principales, introduce el ID de cuenta de servicio de la conexión de recursos de Cloud que has copiado anteriormente.

11. En el campo Selecciona un rol, elige Cloud Translation y, a continuación, selecciona Usuario de la API Cloud Translation.

12. Haz clic en Guardar.

Crear una función definida por el usuario (UDF) de Python que llame al servicio Cloud Translation

En my_query_project, crea una función definida por el usuario (UDF) de Python que llame al servicio Cloud Translation mediante tu conexión de recursos de Cloud.

1. Ve a la página BigQuery.

   Ir a BigQuery

2. Introduce la siguiente instrucción 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;

   Haz los cambios siguientes:

   • PROJECT_ID.DATASET_ID: tu ID de proyecto y tu ID de conjunto de datos
   • REGION.CONNECTION_ID: la región de tu conexión y el ID de conexión

3. Haz clic en play_circle_filled Ejecutar.

   La salida debería tener este aspecto:

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

Ubicaciones admitidas

Las funciones definidas por el usuario de Python se admiten en todas las ubicaciones multirregionales y regionales de BigQuery.

Precios

Las UDFs de Python se ofrecen sin ningún cargo adicional.

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

• Los cargos de las UDFs de Python se facturan mediante la SKU de servicios de BigQuery.
• Los cargos son proporcionales a la cantidad de recursos de computación y memoria que se consumen cuando se invoca la función definida por el usuario de Python.
• También se cobra a los clientes de UDFs de Python por el coste de crear o volver a crear la imagen de contenedor de la UDF. Este cargo es proporcional a los recursos utilizados para crear la imagen con el código y las dependencias del cliente.
• Si las UDFs de Python generan tráfico de salida de red externo o de Internet, también verás un cargo de salida de Internet del nivel Premium de Cloud Networking.