Fonctions définies par l'utilisateur en Python

Une fonction définie par l'utilisateur (UDF) Python vous permet d'implémenter une fonction scalaire en Python et de l'utiliser dans une requête SQL. Les fonctions définies par l'utilisateur Python sont semblables aux fonctions définies par l'utilisateur SQL et JavaScript, mais elles offrent des fonctionnalités supplémentaires. Les fonctions définies par l'utilisateur Python vous permettent d'installer des bibliothèques tierces à partir de l'index de packages Python (PyPI) et d'accéder à des services externes à l'aide d'une connexion aux ressources Cloud.

Les fonctions définies par l'utilisateur Python sont créées et exécutées sur des ressources gérées par BigQuery.

Limites

• python-3.11 est le seul environnement d'exécution compatible.
• Vous ne pouvez pas créer de fonction définie par l'utilisateur Python temporaire.
• Vous ne pouvez pas utiliser de fonction définie par l'utilisateur Python avec une vue matérialisée.
• Les résultats d'une requête qui appelle une fonction définie par l'utilisateur Python ne sont pas mis en cache, car la valeur renvoyée par une fonction définie par l'utilisateur Python est toujours considérée comme non déterministe.
• Les fonctions définies par l'utilisateur Python ne sont pas entièrement compatibles avec les vues INFORMATION_SCHEMA.
• Vous ne pouvez pas créer ni mettre à jour une fonction définie par l'utilisateur Python à l'aide de l'API Routine.
• VPC Service Controls n'est pas compatible.
• Les clés de chiffrement gérées par le client (CMEK) ne sont pas prises en charge.
• Les types de données suivants ne sont pas acceptés: JSON, RANGE, INTERVAL et GEOGRAPHY.
• Les conteneurs qui exécutent des fonctions définies par l'utilisateur Python ne peuvent être configurés que pour deux CPU virtuels et 8 Go.

Rôles IAM requis

Les rôles IAM requis dépendent de votre rôle : propriétaire ou utilisateur de fonctions définies par l'utilisateur Python. Un propriétaire de fonction définie par l'utilisateur Python crée ou met généralement à jour une fonction définie par l'utilisateur. Un utilisateur de fonction définie par l'utilisateur Python appelle une UDF définie par l'utilisateur créée par quelqu'un d'autre.

Des rôles supplémentaires sont également requis si vous créez ou exécutez une fonction définie par l'utilisateur Python qui fait référence à une connexion à une ressource Cloud.

Propriétaires des UDF

Si vous créez ou mettez à jour une fonction définie par l'utilisateur Python, les rôles IAM prédéfinis suivants doivent être accordés à la ressource appropriée:

Utilisateurs de l'UDF

Si vous appelez une fonction définie par l'utilisateur Python, les rôles IAM prédéfinis suivants doivent être accordés sur la ressource appropriée:

Pour en savoir plus sur les rôles dans BigQuery, consultez la section Rôles IAM prédéfinis.

Créer une fonction UDF Python persistante

Suivez ces règles lorsque vous créez une fonction définie par l'utilisateur Python:

• Le corps de la fonction définie par l'utilisateur Python doit être une chaîne littérale entre guillemets qui représente le code Python. Pour en savoir plus sur les littéraux de chaîne entre guillemets, consultez la section Formats pour les littéraux entre guillemets.

• Le corps de la fonction définie par l'utilisateur Python doit inclure une fonction Python utilisée dans l'argument entry_point de la liste des options de la fonction définie par l'utilisateur Python.

• Une version d'environnement d'exécution Python doit être spécifiée dans l'option runtime_version. La seule version d'environnement d'exécution Python compatible est python-3.11. Pour obtenir la liste complète des options disponibles, consultez la liste des options de fonction pour l'instruction CREATE FUNCTION.

Pour créer une fonction Python définie par l'utilisateur persistante, utilisez l'instruction CREATE FUNCTION sans le mot clé TEMP ou TEMPORARY. Pour supprimer une fonction UDF Python persistante, utilisez l'instruction DROP FUNCTION.

Lorsque vous créez une fonction définie par l'utilisateur Python à l'aide de l'instruction CREATE FUNCTION, BigQuery crée ou met à jour une image de conteneur basée sur une image de base. Le conteneur est créé sur l'image de base à l'aide de votre code et de toutes les dépendances de paquets spécifiées. La création du conteneur est un processus de longue durée. La première requête après l'exécution de l'instruction CREATE FUNCTION peut attendre automatiquement la fin de l'image. Sans dépendances externes, l'image du conteneur devrait généralement être créée en moins d'une minute.

Exemple

Pour voir un exemple de création d'une fonction définie par l'utilisateur Python persistante, choisissez l'une des options suivantes:

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

Créer une UDF Python vectorisée

Vous pouvez implémenter votre fonction définie par l'utilisateur Python pour traiter un lot de lignes au lieu d'une seule ligne à l'aide de la vectorisation. La vectorisation peut améliorer les performances des requêtes.

Pour contrôler le comportement de traitement par lot, spécifiez le nombre maximal de lignes dans chaque lot à l'aide de l'option max_batching_rows dans la liste d'options CREATE OR REPLACE FUNCTION. Si vous spécifiez max_batching_rows, BigQuery détermine le nombre de lignes dans un lot, jusqu'à la limite max_batching_rows. Si max_batching_rows n'est pas spécifié, le nombre de lignes à traiter par lot est déterminé automatiquement.

Une fonction définie par l'utilisateur Python vectorisée comporte un seul argument pandas.DataFrame qui doit être annoté. L'argument pandas.DataFrame comporte le même nombre de colonnes que les paramètres de fonction définie par l'utilisateur Python définis dans l'instruction CREATE FUNCTION. Les noms de colonne de l'argument pandas.DataFrame sont identiques à ceux des paramètres de l'UDF.

Votre fonction doit renvoyer un pandas.Series ou un pandas.DataFrame à une seule colonne avec le même nombre de lignes que l'entrée.

L'exemple suivant crée une fonction définie par l'utilisateur Python vectorisée nommée multiplyInputs avec deux paramètres : x et y :

1. Accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans l'éditeur de requête, saisissez l'instruction CREATE FUNCTION suivante:

   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']
   
   ''';

   Remplacez PROJECT_ID.DATASET_ID par l'ID de votre projet et l'ID de l'ensemble de données.

   L'appel de la UDF est identique à celui de l'exemple précédent.

3. Cliquez sur play_circle_filled Exécuter.

Types de données compatibles avec les fonctions définies par l'utilisateur Python

Le tableau suivant définit la correspondance entre les types de données BigQuery, les types de données Python et les types de données Pandas:

Versions d'exécution compatibles

Les fonctions définies par l'utilisateur Python de BigQuery sont compatibles avec l'environnement d'exécution python-3.11. Cette version de Python inclut des packages préinstallés supplémentaires. Pour les bibliothèques système, vérifiez l'image de base de l'environnement d'exécution.

Utiliser des packages tiers

Vous pouvez utiliser la liste d'options CREATE FUNCTION pour utiliser des modules autres que ceux fournis par la bibliothèque standard Python et les packages préinstallés. Vous pouvez installer des packages à partir de l'index de packages Python (PyPI) ou importer des fichiers Python à partir de Cloud Storage.

Installer un package à partir de l'index de packages Python

Lorsque vous installez un package, vous devez indiquer son nom, et vous pouvez éventuellement indiquer sa version à l'aide de spécificateurs de version de package Python. Si le package se trouve dans l'environnement d'exécution, il est utilisé, sauf si une version particulière est spécifiée dans la liste d'options CREATE FUNCTION. Si aucune version de package n'est spécifiée et que le package n'est pas inclus dans l'environnement d'exécution, la dernière version disponible est utilisée. Seuls les packages au format binaire wheels sont acceptés.

L'exemple suivant montre comment créer une fonction définie par l'utilisateur Python qui installe le package scipy à l'aide de la liste d'options CREATE OR REPLACE FUNCTION:

1. Accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans l'éditeur de requête, saisissez l'instruction CREATE FUNCTION suivante:

   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);

   Remplacez PROJECT_ID.DATASET_ID par l'ID de votre projet et l'ID de l'ensemble de données.

3. Cliquez sur play_circle_filled Exécuter.

Importer des fichiers Python supplémentaires en tant que bibliothèques

Vous pouvez étendre vos fonctions définies par l'utilisateur Python à l'aide de la liste d'options de fonction en important des fichiers Python à partir de Cloud Storage.

Dans le code Python de votre UDF par l'utilisateur, vous pouvez importer les fichiers Python à partir de Cloud Storage en tant que modules à l'aide de l'instruction d'importation suivie du chemin d'accès à l'objet Cloud Storage. Par exemple, si vous importez gs://BUCKET_NAME/path/to/lib1.py, votre instruction d'importation sera import path.to.lib1.

Le nom de fichier Python doit être un identifiant Python. Chaque nom folder dans le nom de l'objet (après /) doit être un identifiant Python valide. Dans la plage ASCII (U+0001 à U+007F), les caractères suivants peuvent être utilisés dans les identifiants:

• Lettres majuscules et minuscules de A à Z
• Traits de soulignement.
• Les chiffres de zéro à neuf, mais un chiffre ne peut pas apparaître comme premier caractère de l'identifiant.

L'exemple suivant montre comment créer une fonction définie par l'utilisateur Python qui importe le package de bibliothèque cliente lib1.py à partir d'un bucket Cloud Storage nommé my_bucket:

1. Accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans l'éditeur de requête, saisissez l'instruction CREATE FUNCTION suivante:

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

   Remplacez PROJECT_ID.DATASET_ID par l'ID de votre projet et l'ID de l'ensemble de données.

3. Cliquez sur play_circle_filled Exécuter.

Configurer les limites de conteneur pour les fonctions définies par l'utilisateur Python

Vous pouvez utiliser la liste d'options CREATE FUNCTION pour spécifier des limites de processeur et de mémoire pour les conteneurs qui exécutent des fonctions définies par l'utilisateur Python.

Par défaut, la mémoire allouée à chaque instance de conteneur est de 512 Mio et le processeur alloué est de 0,33 vCPU.

L'exemple suivant crée une fonction définie par l'utilisateur Python à l'aide de la liste d'options CREATE FUNCTION pour spécifier les limites de conteneur:

1. Accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans l'éditeur de requête, saisissez l'instruction CREATE FUNCTION suivante:

   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()
   """;

   Remplacez PROJECT_ID.DATASET_ID par l'ID de votre projet et l'ID de l'ensemble de données.

3. Cliquez sur play_circle_filled Exécuter.

Valeurs de processeur acceptées

Les fonctions définies par l'utilisateur Python acceptent les valeurs de CPU fractionnaires comprises entre 0.33 et 1.0, ainsi que les valeurs de CPU non fractionnaires de 1 et 2. Les valeurs d'entrée fractionnaires sont arrondies à deux décimales avant d'être appliquées au conteneur.

Valeurs de mémoire acceptées

Les conteneurs de fonctions définies par l'utilisateur Python acceptent les valeurs de mémoire au format suivant : <integer_number><unit>. L'unité doit être l'une des valeurs suivantes: Mi, M, Gi ou G. La quantité de mémoire minimale que vous pouvez configurer est de 256 mébioctets (256 Mo). La quantité maximale de mémoire que vous pouvez configurer est de 8 gibioctets (8 Gi).

En fonction de la valeur de mémoire que vous choisissez, vous devez également spécifier la quantité minimale de processeurs. Le tableau suivant indique les valeurs de processeur minimales pour chaque valeur de mémoire:

Appeler des services Google Cloud ou en ligne dans le code Python

Une fonction définie par l'utilisateur Python accède à un service Google Cloud ou à un service externe à l'aide du compte de service Connexion aux ressources cloud. Le compte de service de la connexion doit disposer d'autorisations pour accéder au service. Les autorisations requises varient en fonction du service auquel vous accédez et des API appelées à partir de votre code Python.

Si vous créez une fonction définie par l'utilisateur Python sans utiliser de connexion à une ressource Cloud, la fonction est exécutée dans un environnement qui bloque l'accès au réseau. Si votre UDFutilisateur accède à des services en ligne, vous devez UDF créer avec une connexion à une ressource Cloud. Dans le cas contraire, l'UDF ne peut pas accéder au réseau tant qu'un délai avant expiration de la connexion interne n'est pas atteint.

L'exemple suivant montre comment accéder au service Cloud Translation à partir d'une fonction définie par l'utilisateur Python. Cet exemple comporte deux projets : un projet nommé my_query_project dans lequel vous créez la fonction définie par l&#UDF et la connexion de ressources Cloud, et un projet dans lequel vous exécutez la Cloud Translation nommée my_translate_project.

Créer une connexion de ressource Cloud

Commencez par créer une connexion de ressource Cloud dans my_query_project. Pour créer la connexion de ressource cloud, suivez les étapes décrites sur la page Créer une connexion de ressource Cloud.

Une fois la connexion créée, ouvrez-la et, dans le volet Informations de connexion, copiez l'ID du compte de service. Vous aurez besoin de cet ID lorsque vous configurerez les autorisations pour la connexion. Lorsque vous créez une ressource de connexion, BigQuery crée un compte de service système unique et l'associe à la connexion.

Accorder l'accès au compte de service de la connexion

Pour accorder au compte de service de connexion aux ressources Cloud l'accès à vos projets, attribuez-lui le rôle de client de l'utilisation du service (roles/serviceusage.serviceUsageConsumer) dans my_query_project et le rôle d'utilisateur de l'API Cloud Translation (roles/cloudtranslate.user) dans my_translate_project.

1. Accédez à la page IAM.

   Accéder à IAM

2. Vérifiez que my_query_project est sélectionné.

3. Cliquez sur person_add Accorder l'accès.

4. Dans le champ Nouveaux comptes principaux, saisissez l'ID du compte de service de la connexion de ressource cloud que vous avez copié précédemment.

5. Dans le champ Sélectionner un rôle, choisissez Service usage (Utilisation du service), puis Service usage consumer (Consommateur Service usage).

6. Cliquez sur Enregistrer.

7. Dans le sélecteur de projet, sélectionnez my_translate_project.

8. Accédez à la page IAM.

   Accéder à IAM

9. Cliquez sur person_add Accorder l'accès.

10. Dans le champ Nouveaux comptes principaux, saisissez l'ID du compte de service de la connexion de ressource cloud que vous avez copié précédemment.

11. Dans le champ Sélectionner un rôle, sélectionnez Cloud Translation, puis Utilisateur de l'API Cloud Translation.

12. Cliquez sur Enregistrer.

Créer une fonction définie par l'utilisateur Python qui appelle le service Cloud Translation

Dans my_query_project, créez une fonction définie par l'utilisateur Python qui appelle le service Cloud Translation à l'aide de votre connexion à une ressource Cloud.

1. Accédez à la page BigQuery.

   Accéder à BigQuery

2. Saisissez l'instruction CREATE FUNCTION suivante dans l'éditeur de requête:

   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;

   Remplacez les éléments suivants :

   • PROJECT_ID.DATASET_ID : ID de votre projet et de votre ensemble de données
   • REGION.CONNECTION_ID : région et ID de votre connexion

3. Cliquez sur play_circle_filled Exécuter.

   Le résultat doit se présenter sous la forme suivante :

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

Pays acceptés

Les UDF Python sont compatibles avec tous les emplacements multirégionaux et régionaux de BigQuery.

Tarifs

Les fonctions définies par l'utilisateur Python sont proposées sans frais supplémentaires.

Lorsque la facturation est activée, les conditions suivantes s'appliquent:

• Les frais liés aux fonctions UDF Python sont facturés à l'aide du SKU des services BigQuery.
• Les frais sont proportionnels à la quantité de calcul et de mémoire consommée lorsque la fonction définie par l'utilisateur Python est appelée.
• Les clients utilisant des UDF Python sont également facturés pour le coût de création ou de recréation de l'image de conteneur de l'UDF. Cette facturation est proportionnelle aux ressources utilisées pour créer l'image avec le code et les dépendances du client.
• Si les fonctions définies par l'utilisateur Python génèrent une sortie réseau externe ou Internet, vous verrez également un débit sortant Internet Premium facturé par Cloud Networking.