Écrire des gestionnaires Java pour les procédures stockées créées avec SQL¶

Écrire un gestionnaire Java pour une procédure stockée¶

1. Assurez-vous que votre environnement répond aux conditions préalables.

2. Si vous développez localement, définissez votre environnement pour qu’il utilise Snowpark.

3. Choisissez de déployer votre gestionnaire en ligne ou sur une zone de préparation interne.

4. Suivez les lignes directrices pour la classe, la méthode et la performance du gestionnaire.

5. Mettez en œuvre la prise en charge de fonctions telles que l’accès aux données, la lecture de fichiers, le retour de données tabulaires et la journalisation et le traçage.

6. Rendez les dépendances de votre code disponibles sur Snowflake.

7. Incluez le code de votre gestionnaire en ligne ou importé d’une zone de préparation interne lorsque vous créez la procédure stockée.

Conditions préalables¶

Vous devez utiliser la version 1.3.0 ou une version plus récente de la bibliothèque Snowpark.

Si vous écrivez une procédure stockée, vous devez compiler vos classes pour qu’elles s’exécutent dans l’une des versions suivantes de Java.

• 11.x

• 17.x

Configuration de votre environnement de développement pour Snowpark¶

Si vous développez votre code localement, définissez votre environnement de développement pour qu’il utilise la bibliothèque Snowpark. Voir Configuration de votre environnement de développement pour Snowpark Java.

Structuration et conception du code du gestionnaire¶

Vous pouvez conserver le code source du gestionnaire en ligne avec le code SQL qui crée la procédure ou conserver le résultat compilé du gestionnaire dans un emplacement distinct et y faire référence à partir du code SQL. Pour plus d’informations, voir Conserver le code du gestionnaire en ligne ou dans une zone de préparation.

Pour en savoir plus sur la conception du code source du gestionnaire à utiliser avec une procédure, voir Empaquetage du code de gestionnaire.

Lignes directrices pour la classe du gestionnaire¶

Lorsque vous écrivez la classe, notez ce qui suit :

• La classe et la méthode ne doivent pas être protégées ou privées.

• Si la méthode n’est pas statique et que vous souhaitez définir un constructeur, définissez un constructeur à zéro argument pour la classe. Snowflake appelle ce constructeur à zéro argument au moment de l’initialisation pour créer une instance de votre classe.

• Vous pouvez définir différentes méthodes pour différentes procédures stockées dans la même classe.

Lignes directrices pour la méthode du gestionnaire¶

Lorsque vous écrivez la méthode pour la procédure stockée, notez ce qui suit :

• Spécifiez l’objet Snowpark Session comme premier argument de votre méthode.

  Lorsque vous appelez votre procédure stockée, Snowflake crée automatiquement un objet Session et le transmet à votre procédure stockée. (Vous ne pouvez pas créer l’objet Session vous-même).

• Pour le reste des arguments et pour la valeur de retour, utilisez les types Java qui correspondent aux types de données Snowflake.

• Votre méthode doit renvoyer une valeur. Pour les procédures stockées en Java, une valeur de retour est requise.

• L’exécution d’une procédure stockée se termine au bout d’un certain temps, sauf si le temporisateur est réinitialisé par l’activité du code. Plus précisément, le délai d’attente est réinitialisé par les interactions du code avec les données, notamment les opérations sur les fichiers, les requêtes et l’itération dans un jeu de résultats.

• Lorsque vous exécutez une tâche enfant asynchrone à partir du gestionnaire (handler) d’une procédure, la fonction « fire and forget » n’est pas prise en charge.

  En d’autres termes, si le gestionnaire (handler) émet une requête enfant qui est toujours en cours d’exécution lorsque la tâche de la procédure parent se termine, la tâche enfant est automatiquement annulée.

Gestion des erreurs¶

Vous pouvez utiliser les techniques normales de gestion des exceptions de Java pour détecter les erreurs dans le code du gestionnaire.

Si une exception non détectée se produit à l’intérieur de la méthode, Snowflake génère une erreur qui inclut la trace de la pile pour l’exception. Lorsque l’enregistrement des exceptions non gérées est activé, Snowflake enregistre les données relatives aux exceptions non gérées dans une table d’événements.

Lignes directrices relatives à la performance et à la sécurité du gestionnaire¶

Pour vous assurer que votre code fonctionne bien sur Snowflake, suivez les conseils suivants :

• Limitez la quantité de mémoire consommée.

  Snowflake impose des limites à une méthode ou une fonction en matière de quantité de mémoire nécessaire. Pour plus d’informations sur la manière d’éviter une consommation excessive, voir Concevoir des gestionnaires qui respectent les contraintes imposées par Snowflake.

• Écrivez du code en respectant le niveau de « thread safety »

  Veillez à ce que la méthode ou la fonction de votre gestionnaire respecte le niveau de « thread safety ».

• Comprenez les restrictions de sécurité.

  Le code de votre gestionnaire s’exécute dans un moteur restreint. Veillez donc à respecter les règles décrites dans Pratiques de sécurité pour UDFs et procédures.

• Décidez d’utiliser les droits du propriétaire ou les droits de l’appelant.

  Lorsque vous planifiez l’écriture de votre procédure stockée, déterminez si vous souhaitez que la procédure stockée s’exécute avec les droits de l’appelant ou les droits du propriétaire.

• Gardez à l’esprit le comportement du délai d’attente pour les procédures stockées.

  L’exécution d’une procédure stockée se termine au bout d’un certain temps, sauf si le temporisateur est réinitialisé par l’activité du code. Plus précisément, le délai d’attente est réinitialisé par les interactions du code avec les données, notamment les opérations sur les fichiers, les requêtes et l’itération dans un jeu de résultats.

Mettre les dépendances à la disposition de votre code¶

Si le code de votre gestionnaire dépend d’un code défini en dehors du gestionnaire lui-même (comme les classes d’un fichier JAR) ou de fichiers de ressources, vous pouvez mettre ces dépendances à la disposition de votre code en les chargeant dans une zone de préparation. Lors de la création de la procédure, vous pouvez faire référence à ces dépendances en utilisant la clause IMPORTS.

Pour plus d’informations, voir Mettre les dépendances à la disposition de votre code.