Personnaliser les fonctions Python pour BigQuery DataFrames

BigQuery DataFrames vous permet de transformer vos fonctions Python personnalisées en artefacts BigQuery que vous pouvez exécuter à grande échelle sur des objets BigQuery DataFrames. Cette compatibilité avec l'extensibilité vous permet d'effectuer des opérations qui ne sont pas possibles avec les API BigQuery DataFrames et SQL. Vous pouvez ainsi profiter des bibliothèques Open Source.

Il existe deux variantes de ce mécanisme d'extensibilité : les fonctions définies par l'utilisateur et les fonctions distantes.

Rôles requis

Pour obtenir les autorisations nécessaires pour effectuer les tâches décrites dans ce document, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Fonctions définies par l'utilisateur

Avec les fonctions définies par l'utilisateur (bêta), vous pouvez transformer votre fonction Python personnalisée en fonction Python définie par l'utilisateur. Pour obtenir un exemple d'utilisation, consultez Créer une fonction Python définie par l'utilisateur persistante.

La création d'une UDF dans BigQuery DataFrames crée une routine BigQuery en tant que fonction Python définie par l'utilisateur dans l'ensemble de données spécifié. Pour obtenir la liste complète des paramètres compatibles, consultez bigframes.pandas.udf.

Conditions requises

Pour utiliser une fonction définie par l'utilisateur BigQuery DataFrames, activez l' API BigQuery dans votre projet. Si vous fournissez le paramètre bigquery_connection dans votre projet, vous devez également activer l' API BigQuery Connection.

Libérer de l'espace

En plus de nettoyer les artefacts cloud directement dans la Cloud de Confiance console ou avec d'autres outils, vous pouvez nettoyer les fonctions définies par l'utilisateur BigQuery DataFrames qui ont été créées avec un argument de nom explicite à l'aide de la bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) commande.

Limites

  • Le code de la UDF doit être autonome, c'est-à-dire qu'il ne doit contenir aucune référence à une importation ou à une variable définie en dehors du corps de la fonction.
  • Le code de la UDF doit être compatible avec Python 3.11, car il s'agit de l'environnement dans lequel le code est exécuté dans le cloud.
  • La réexécution du code de définition de la UDF après des modifications mineures dans le code de la fonction (par exemple, le changement de nom d'une variable ou l'insertion d'une nouvelle ligne) entraîne la recréation de la UDF, même si ces modifications n'ont aucune incidence sur le comportement de la fonction.
  • Le code utilisateur est visible par les utilisateurs disposant d'un accès en lecture aux routines BigQuery. Vous ne devez donc inclure du contenu sensible qu'avec prudence.
  • Un projet peut contenir jusqu'à 1 000 fonctions Cloud Run à la fois dans un emplacement BigQuery.

La fonction définie par l'utilisateur BigQuery DataFrames déploie une fonction Python BigQuery définie par l'utilisateur, et les limites associées s'appliquent.

Fonctions à distance

BigQuery DataFrames vous permet de transformer vos fonctions scalaires personnalisées en fonctions distantes BigQuery. Pour obtenir un exemple d'utilisation, consultez Créer une fonction distante. Pour obtenir la liste complète des paramètres compatibles, consultez remote_function.

La création d'une fonction distante dans BigQuery DataFrames crée les éléments suivants :

  • Une fonction Cloud Run.

  • Une connexion BigQuery.

    Par défaut, une connexion nommée bigframes-default-connection est utilisée. Si vous le préférez, vous pouvez utiliser une connexion BigQuery préconfigurée. Dans ce cas, la création de la connexion est ignorée. Le rôle Cloud Run (roles/run.invoker) est accordé au compte de service de la connexion par défaut .

  • Une fonction distante BigQuery qui utilise la fonction Cloud Run créée avec la connexion BigQuery

Conditions requises

Pour utiliser les fonctions distantes BigQuery DataFrames, vous devez activer les API suivantes :

Lorsque vous utilisez des fonctions distantes BigQuery DataFrames, vous avez besoin du rôle Administrateur de projet IAM (roles/resourcemanager.projectIamAdmin) si vous utilisez une connexion BigQuery par défaut, ou du rôle Navigateur (roles/browser) si vous utilisez une connexion préconfigurée. Vous pouvez éviter cette exigence en définissant l'option bigframes.pandas.options.bigquery.skip_bq_connection_check sur True. Dans ce cas, la connexion (par défaut ou préconfigurée) est utilisée telle quelle, sans vérification de l'existence ni des autorisations. Si vous utilisez la connexion préconfigurée et que vous ignorez la vérification de la connexion, vérifiez les points suivants :

Afficher et gérer les connexions

Les connexions BigQuery sont créées au même emplacement que la session BigQuery DataFrames, en utilisant le nom que vous fournissez dans la définition de la fonction personnalisée. Pour afficher et gérer les connexions, procédez comme suit :

  1. Dans la Cloud de Confiance console, accédez à la page BigQuery.

    Accéder à BigQuery

  2. Sélectionnez le projet dans lequel vous avez créé la fonction distante.

  3. Dans le volet de gauche, cliquez sur Explorateur:

    Bouton du volet Explorateur mis en évidence.

  4. Dans le volet Explorateur, développez le projet, puis cliquez sur Connexions.

Les fonctions distantes BigQuery sont créées dans l'ensemble de données que vous spécifiez, ou dans un ensemble de données anonyme, qui est un type d' ensemble de données masqué. Si vous ne définissez pas de nom pour une fonction distante lors de sa création, BigQuery DataFrames applique un nom par défaut commençant par le préfixe bigframes. Pour afficher et gérer les fonctions distantes créées dans un ensemble de données spécifié par l'utilisateur, procédez comme suit :

  1. Dans la Cloud de Confiance console, accédez à la page BigQuery.

    Accéder à BigQuery

  2. Sélectionnez le projet dans lequel vous avez créé la fonction distante.

  3. Dans le volet de gauche, cliquez sur Explorateur:

    Bouton du volet Explorateur mis en évidence.

  4. Dans le volet Explorateur, développez le projet, puis cliquez sur Ensembles de données.

  5. Cliquez sur l'ensemble de données dans lequel vous avez créé la fonction distante.

  6. Cliquez sur l'onglet Routines.

Pour afficher et gérer les fonctions Cloud Run, procédez comme suit :

  1. Accédez à la page Cloud Run.

    Accéder à Cloud Run

  2. Sélectionnez le projet dans lequel vous avez créé la fonction.

  3. Dans la liste des services disponibles, filtrez par Type de déploiement de fonction.

  4. Pour identifier les fonctions créées par BigQuery DataFrames, recherchez les noms de fonctions commençant par le préfixe bigframes.

Libérer de l'espace

En plus de nettoyer les artefacts cloud directement dans la Cloud de Confiance console ou avec d'autres outils, vous pouvez nettoyer les fonctions distantes BigQuery qui ont été créées sans argument de nom explicite et leurs fonctions Cloud Run associées de la manière suivante :

  • Pour une session BigQuery DataFrames, utilisez la commande session.close().
  • Pour la session BigQuery DataFrames par défaut, utilisez la commande bigframes.pandas.close_session().
  • Pour une session passée avec session_id, utilisez la bigframes.pandas.clean_up_by_session_id(session_id) commande.

Vous pouvez également nettoyer les fonctions distantes BigQuery qui ont été créées avec un argument de nom explicite et leurs fonctions Cloud Run associées à l'aide de la commande bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Limites

  • Les fonctions distantes sont utilisables en environ 90 secondes lorsque vous les créez. Des dépendances de packages supplémentaires peuvent augmenter la latence.
  • La réexécution du code de définition de la fonction distante après des modifications mineures dans le code de la fonction et autour de celui-ci (par exemple, le changement de nom d'une variable, l'insertion d'une nouvelle ligne ou l'insertion d'une nouvelle cellule dans le notebook) peut entraîner la recréation de la fonction distante, même si ces modifications n'ont aucune incidence sur le comportement de la fonction.
  • Le code utilisateur est visible par les utilisateurs disposant d'un accès en lecture aux fonctions Cloud Run. Vous ne devez donc inclure du contenu sensible qu'avec prudence.
  • Un projet peut contenir jusqu'à 1 000 fonctions Cloud Run à la fois dans une région. Pour en savoir plus, consultez la page consacrée aux quotas.

Étape suivante