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 potentiellement tirer parti 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

Les fonctions définies par l'utilisateur (aperçu) vous permettent de transformer votre fonction Python personnalisée en fonction définie par l'utilisateur Python. Pour obtenir un exemple d'utilisation, consultez Créer une UDF Python persistante.

Lorsque vous créez une UDF dans BigQuery DataFrames, une routine BigQuery est créée en tant qu'UDF Python 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 UDF 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.

Effectuer un nettoyage

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

Limites

  • Le code de l'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 l'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.
  • Si vous réexécutez le code de définition de l'UDF après avoir apporté des modifications mineures au code de la fonction (par exemple, en renommant une variable ou en insérant une nouvelle ligne), l'UDF est recréée, 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 devez donc inclure du contenu sensible avec prudence.
  • Un projet peut contenir jusqu'à 1 000 fonctions Cloud Run à la fois dans un emplacement BigQuery.

L'UDF BigQuery DataFrames déploie une fonction Python BigQuery définie par l'utilisateur. Les limitations 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 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 compte de service de la connexion par défaut se voit attribuer le rôle Cloud Run (roles/run.invoker).

  • 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 les fonctions distantes BigQuery DataFrames, vous avez besoin du rôle d'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 aucune vérification d'existence ni d'autorisation. Si vous utilisez la connexion préconfigurée et que vous ignorez la vérification de connexion, vérifiez les points suivants :

  • La connexion est créée au bon endroit.
  • Si vous utilisez les fonctions distantes BigQuery DataFrames, le compte de service dispose du rôle d'invocateur Cloud Run (roles/run.invoker) dans le projet.

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 console Google Cloud , accédez à la page BigQuery.

    Accéder à BigQuery

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

  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 console Google Cloud , accédez à la page BigQuery.

    Accéder à BigQuery

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

  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 :

  1. Accédez à la page Cloud Run

    Accédez à Cloud Run

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

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

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

Effectuer un nettoyage

En plus de nettoyer les artefacts cloud directement dans la console Google Cloud 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 commande bigframes.pandas.clean_up_by_session_id(session_id).

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

Limites

  • Les fonctions distantes sont disponibles en environ 90 secondes lorsque vous les créez. Des dépendances de package supplémentaires peuvent augmenter la latence.
  • Si vous réexécutez le code de définition de la fonction distante après des modifications mineures dans et autour du code de la fonction (par exemple, en renommant une variable, en insérant une nouvelle ligne ou en insérant une nouvelle cellule dans le notebook), la fonction distante peut être recréée, 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.

Étapes suivantes