Concepts des fonctions externes

Cette rubrique fournit une description détaillée du fonctionnement des fonctions externes.

Dans ce chapitre :

Fonctionnement des fonctions externes

Snowflake n’appelle pas directement un service distant. Au lieu de cela, Snowflake appelle le service distant via le service proxy HTTPS natif d’un fournisseur de Cloud, par exemple API Gateway sur AWS.

Les principales étapes pour appeler une fonction externe sont les suivantes :

  1. Le programme client d’un utilisateur transmet à Snowflake une instruction SQL qui appelle une fonction externe.

  2. Lors de l’évaluation de la fonction externe dans le cadre de l’exécution de la requête, Snowflake lit la définition de la fonction externe, qui contient l’URL du service proxy et le nom de l’intégration API qui contient les informations d’authentification pour ce service proxy.

  3. Snowflake lit les informations de l’intégration API et compose une demande HTTP POST qui contient les éléments suivants :

    • Informations d’en-tête HTTP. (Les détails sont documentés dans CREATE EXTERNAL FUNCTION.)

    • Les données à traiter. Ces données sont au format JSON.

    • La « ressource » du service proxy à utiliser. La ressource contient des informations sur le service distant, telles que l’emplacement de ce service.

    • Les informations d’authentification pour cette ressource de service proxy.

    La demande POST est envoyée au service proxy.

  4. Le service proxy reçoit la demande POST, puis traite et transfère la demande au service distant réel. Vous pouvez vaguement considérer le service proxy et la ressource comme une « fonction relais » qui appelle le service distant.

  5. Le service distant traite les données et renvoie le résultat, qui est retransmis via la chaîne à l’instruction SQL d’origine.

Ce diagramme illustre les étapes décrites ci-dessus :

Illustration of the flow of data from external function call to remote service.

Avant qu’un utilisateur puisse appeler une fonction externe, les développeurs et les administrateurs de compte Snowflake doivent configurer Snowflake pour accéder au service proxy. En règle générale, les étapes sont effectuées dans l’ordre approximatif ci-dessous (en partant du côté droit du diagramme ci-dessus et en se déplaçant vers la gauche vers Snowflake).

  1. Un développeur doit écrire le service distant et ce service distant doit être exposé via le service proxy HTTPS. Par exemple, le service distant peut être une fonction Python exécutée sur AWS Lambda et exposée via une ressource dans AWS API Gateway.

  2. Dans Snowflake, un ACCOUNTADMIN ou un rôle avec le privilège CREATE INTEGRATION doit créer un objet « Intégration API » qui contient des informations d’authentification qui permettent à Snowflake de communiquer avec le service proxy. L’intégration API est créée avec la commande SQL CREATE API INTEGRATION.

  3. Un utilisateur Snowflake doit exécuter la commande SQL CREATE EXTERNAL FUNCTION. L’utilisateur doit utiliser un rôle disposant de privilèges USAGE sur l’intégration API et disposant de privilèges suffisants pour créer des fonctions.

    Note

    La commande CREATE EXTERNAL FUNCTION ne crée pas réellement de fonction externe au sens du chargement du code qui sera « exécuté en dehors de Snowflake ». Au lieu de cela, la commande CREATE EXTERNAL FUNCTION crée un objet de base de données qui référence indirectement le code qui s’exécute en dehors de Snowflake. Plus précisément, la commande CREATE EXTERNAL FUNCTION crée un objet qui contient les éléments suivants :

    • L’URL de la ressource dans le service proxy HTTPS qui agit comme une fonction de relais.

    • Le nom de l’intégration API à utiliser pour s’authentifier auprès du service proxy.

    • Un nom qui est en fait un alias pour le service distant. Cet alias est utilisé dans les commandes SQL, par exemple SELECT MyAliasForRemoteServiceXYZ(col1) ...;

L’alias dans Snowflake, le nom de la ressource du service proxy HTTPS et le nom du service distant peuvent tous être différents. (Cependant, l’utilisation du même nom pour les trois peut simplifier l’administration.)

Bien que les étapes décrites ci-dessus soient le moyen le plus courant d’exécuter une fonction externe, certaines variations sont autorisées. Par exemple :

  • Le service à distance n’est peut-être pas la dernière étape de la chaîne ; le service à distance pourrait appeler un autre service à distance pour effectuer une partie du travail.

  • Si le service distant n’accepte pas et ne renvoie pas les données au format JSON, la ressource du service proxy HTTPS (la fonction relais) peut convertir les données du format JSON vers un autre format (et reconvertir les données renvoyées au format JSON).

  • Bien que Snowflake recommande que le service distant se comporte comme une véritable fonction (c’est-à-dire un morceau de code qui accepte 0 ou plus de paramètres d’entrée et renvoie une sortie) qui n’a aucun effet secondaire et ne conserve aucune information d’état, ce n’est pas strictement requis. Le service distant peut effectuer d’autres tâches, par exemple envoyer des alertes si une valeur (telle qu’un relevé de température dans des données) est dangereusement élevée. Dans de rares cas, le service distant peut conserver des informations d’état, par exemple le nombre total d’alertes émises.

Evolutivité

Le service distant, le service proxy et toute autre étape entre Snowflake et le service distant doivent pouvoir gérer les pics de charge de travail qui leur sont envoyés.

Evolutivité du service distant

Les développeurs qui écrivent des services à distance devraient considérer les points suivants :

  • Fréquence à laquelle le service distant sera appelé.

  • Le nombre de lignes envoyées par appel.

  • Les ressources nécessaires pour traiter chaque ligne.

  • La répartition temporelle des appels (pic vs moyenne).

La capacité peut devoir augmenter au fil du temps, car les appelants passent de quelques développeurs et testeurs à une organisation entière. Si le service distant est utilisé par plusieurs organisations, la capacité peut devoir augmenter à mesure que le nombre d’organisations augmente. En outre, à mesure que le nombre et la diversité des organisations augmentent, la taille et le calendrier des charges de travail peuvent devenir plus difficiles à prévoir.

Le fournisseur de services à distance est chargé de fournir une capacité suffisante pour gérer les pics en matière de charges de travail. Différentes techniques peuvent être utilisées pour faire évoluer le service. Si le service distant est géré par l’auteur du service distant, l’auteur peut avoir besoin de fournir explicitement le service avec une capacité suffisante pour gérer les pics. Alternativement, l’auteur peut décider d’utiliser un service hébergé à dimensionnement automatique/élastique, tel que AWS Lambda.

Les services distants doivent envisager de renvoyer 429 lorsqu’ils sont surchargés. Si Snowflake voit un code de réponse HTTP de 429, Snowflake réduit la fréquence à laquelle il envoie des lignes et réessaye d’envoyer des lots de lignes qui n’ont pas été traités avec succès.

Pour plus d’informations sur le dépannage des problèmes d’évolutivité, voir Évolutivité.

Évolutivité du service proxy

Le service proxy doit également être évolutif. Heureusement, les services proxy fournis par les principaux fournisseurs de Cloud sont généralement évolutifs. Cependant, les utilisateurs qui développent ou administrent des fonctions externes doivent se souvenir des informations suivantes :

AWS API Gateway

AWS API Gateway est elle-même un service AWS géré, qui s’adapte automatiquement à la charge de travail des utilisateurs. Les utilisateurs doivent connaître les différentes limites de API Gateway : https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html.

AWS API Gateway peut être configuré pour aider à faire évoluer le service distant. Plus précisément, API Gateway peut être configuré pour activer la mise en cache et/ou la limitation des requêtes afin de réduire la charge sur le service distant si nécessaire :

Etant donné que la limitation peut affecter les délais d’attente et les tentatives, les utilisateurs peuvent également vouloir consulter des informations sur la façon dont Snowflake gère les délais d’attente et les tentatives :

Accès simultané

Les besoins en ressources dépendent de la façon dont les lignes sont réparties entre les appels (de nombreux appels parallèles avec quelques lignes chacun contre un appel avec le même nombre total de lignes). Un système qui prend en charge une capacité élevée ne prend pas nécessairement en charge un accès simultané élevé et inversement. Vous devez estimer la simultanéité des pics requise, ainsi que les charges de travail individuelles les plus importantes et fournir suffisamment de ressources pour gérer les deux types de pics.

De plus, l’estimation de la simultanéité devrait tenir compte du fait que Snowflake peut paralléliser les appels de fonctions externes. Une seule requête d’un seul utilisateur peut provoquer plusieurs appels vers le service distant en parallèle. Plusieurs facteurs influent sur le nombre d’appels simultanés de Snowflake vers un service proxy ou un service distant, notamment les suivants :

  • Le nombre d’utilisateurs simultanés qui exécutent des requêtes avec des fonctions externes.

  • La taille de la requête de chaque utilisateur.

  • Le nombre de serveurs dans l’entrepôt virtuel (c’est-à-dire la taille de l’entrepôt).

  • Le nombre de clusters d’entrepôt.

La gestion correcte de la simultanéité peut être particulièrement complexe si les fonctions externes ont des effets secondaires. Les résultats peuvent varier selon l’ordre dans lequel les lignes de l’utilisateur sont traitées. (Snowflake vous recommande d’éviter d’écrire ou d’utiliser des services à distance qui ont des effets secondaires.)

Fiabilité

Selon l’endroit où le service distant s’exécute, vous devrez peut-être prendre en compte les points suivants :

  • Fiabilité.

  • Gestion des erreurs.

  • Débogage.

  • Mise à niveau (si le service distant peut ajouter de nouvelles fonctionnalités ou nécessiter des corrections de bogues).

Si le service distant n’est pas Stateless, vous devrez peut-être également envisager la récupération après l’échec. (Snowflake recommande fortement que les services distants soient Stateless.)

Pour plus d’informations sur les délais d’expiration et les tentatives, voir Tenir compte des erreurs d’expiration de délai et Ne supposez pas que le service distant a validé chaque ligne exactement une fois.