Introduction aux fonctions externes

Cette rubrique décrit les fonctions externes, qui appellent du code exécutable développé, maintenu, stocké et exécuté en dehors de Snowflake.

Ce sujet vous aide dans les actions suivantes :

  • Comprendre ce qu’est une fonction externe.

  • Décider si une fonction externe est la meilleure façon pour vous de mettre en œuvre une UDF (fonction définie par l’utilisateur).

  • Choisir la plateforme Cloud pour votre fonction externe.

Dans ce chapitre :

Qu’est-ce qu’une fonction externe ?

Une fonction externe appelle un code qui est exécuté en dehors de Snowflake.

Le code exécuté à distance est connu sous le nom de service distant.

Les informations envoyées à un service distant sont généralement relayées par un service proxy.

Snowflake stocke les informations sur la fonction externe liée à la sécurité dans une intégration API.

Le diagramme ci-dessous montre le flux d’informations de base d’un programme client, via Snowflake, et vers le service à distance :

../_images/external-functions-overview-07.png

Chacun de ces éléments clés est décrit plus en détail ci-dessous.

Fonction externe :

Une fonction externe est un type d” UDF. Contrairement aux autres UDFs, une fonction externe ne contient pas son propre code ; au lieu de cela, la fonction externe appelle un code qui est stocké et exécuté en dehors de Snowflake.

Dans Snowflake, la fonction externe est stockée comme un objet de base de données qui contient des informations que Snowflake utilise pour appeler le service distant. Ces informations stockées incluent l’URL du service proxy qui relaie les informations vers et depuis le service distant. Ces informations sont spécifiées dans le cadre de la commande CREATE EXTERNAL FUNCTION.

L’objet de base de données qui représente la fonction externe est créé dans une base de données et un schéma spécifiques. La fonction externe peut être appelée en utilisant la notation par points pour représenter le nom entièrement qualifié. Par exemple :

select my_database.my_schema.my_external_function(col1) from table1;
Copy
Service à distance :

Le code exécuté à distance est connu sous le nom de service distant.

Le service distant doit se comporter comme une fonction. Par exemple, il doit renvoyer une valeur.

Snowflake prend en charge les fonctions externes scalaires ; le service distant doit renvoyer exactement une ligne pour chaque ligne reçue.

Pour être appelé par la fonction externe Snowflake, le service distant doit :

Par exemple, un service distant peut être implémenté comme suit :

  • Une fonction AWS Lambda.

  • Une fonction de Microsoft Azure.

  • Un serveur HTTPS (par exemple Node.js) s’exécutant sur une instance EC2.

Un service proxy :

Snowflake n’appelle pas directement un service distant. Au lieu de cela, Snowflake appelle un service proxy, qui relaie les données vers le service distant.

Le service proxy peut accroître la sécurité en authentifiant les demandes adressées au service à distance.

Le service proxy peut prendre en charge la facturation par abonnement d’un service distant. Par exemple, le service proxy peut vérifier qu’un appelant du service distant est un abonné payant.

Le service proxy relaie également la réponse du service distant vers Snowflake.

Voici quelques exemples de services proxy :

  • Amazon API Gateway.

  • Service Gestion des API Microsoft Azure.

Intégration API :

Une intégration est un objet Snowflake qui fournit une interface entre Snowflake et des services tiers. Une intégration API stocke des informations, telles que des informations de sécurité, qui sont nécessaires pour fonctionner avec un service proxy ou un service distant.

L’intégration API est créée avec la commande CREATE API INTEGRATION .

Les utilisateurs peuvent écrire et appeler leurs propres services à distance, ou appeler des services à distance écrits par des tiers. Ces services distants peuvent être écrits à l’aide de n’importe quelle pile de serveurs HTTP, y compris des services de calcul sans serveur Cloud tels que AWS Lambda.

Du point de vue d’un utilisateur exécutant une instruction SQL, une fonction externe se comporte comme n’importe quelle autre UDF . Les fonctions externes suivent ces règles :

  • Les fonctions externes renvoient une valeur.

  • Les fonctions externes peuvent accepter des paramètres.

  • Une fonction externe peut apparaître dans n’importe quelle clause d’une instruction SQL dans laquelle d’autres types de fonctions UDF peuvent apparaître. Par exemple :

    select my_external_function_2(column_1, column_2)
        from table_1;
    
    select col1
        from table_1
        where my_external_function_3(col2) < 0;
    
    create view view1 (col1) as
        select my_external_function_5(col1)
            from table9;
    
    Copy
  • Une fonction externe peut faire partie d’une expression plus complexe :

    select upper(zipcode_to_city_external_function(zipcode))
      from address_table;
    
    Copy
  • La valeur renvoyée peut être une valeur composée, telle qu’un VARIANT qui contient JSON.

  • Les fonctions externes peuvent être surchargées ; deux fonctions différentes peuvent avoir le même nom mais des signatures différentes (nombres différents ou types de données de paramètres d’entrée).

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. Lorsqu’il évalue la fonction externe dans le cadre de l’exécution de la requête, Snowflake lit la définition de la fonction externe et les informations d’intégration API correspondantes.

    • Les informations provenant de la définition de la fonction externe comprennent :

      • L’URL du service proxy.

      • Le nom de l’intégration API correspondante.

    • Les informations provenant de l’intégration API comprennent :

      • 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.

    Snowflake compose alors une commande HTTP POST qui inclut :

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

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

    • Des informations d’authentification de l’intégration API.

    Snowflake envoie ensuite la requête POST au service proxy.

  3. 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.

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

  5. Si le service distant répond avec un code HTTP pour signaler un traitement asynchrone, alors Snowflake envoie une ou plusieurs requêtes HTTP GET pour récupérer le résultat du service distant. Snowflake continue à envoyer des requêtes GET tant qu’il reçoit le code de réponse pour continuer à effectuer les demandes, ou jusqu’à ce que la fonction externe s’arrête ou renvoie une erreur.

Généralement, lorsqu’une requête comporte un grand nombre de lignes à envoyer à un service distant, les lignes sont divisées en lots. Les lots permettent généralement un plus grand parallélisme et des interrogations plus rapides. Dans certains cas, les lots permettent de réduire la surcharge du service à distance.

Un service à distance renvoie un lot de lignes pour chaque lot reçu. Pour une fonction externe scalaire, le nombre de lignes du lot retourné est égal au nombre de lignes du lot reçu.

Chaque lot a un ID de lot unique, qui est inclus dans chaque requête envoyée par Snowflake au service à distance.

Les opérations de relance (par exemple en raison d’expirations) sont généralement effectuées au niveau du lot.

Avantages des fonctions externes

Les fonctions externes présentent les avantages suivants par rapport aux autres UDFs :

  • Le code du service distant peut être écrit dans des langages dans lesquels les autres UDFs ne peuvent pas être écrits, notamment :

    • Go

    • C#

  • Les services distants peuvent utiliser des fonctions et des bibliothèques qui ne sont pas accessibles par des UDFs internes. Par exemple, les services distants peuvent s’interfacer avec des bibliothèques tierces disponibles dans le commerce, telles que les bibliothèques de notation d’apprentissage automatique.

  • Les développeurs peuvent écrire des services distants qui peuvent être appelés à la fois à partir de Snowflake et à partir d’autres logiciels écrits pour utiliser la même interface.

Limitations des fonctions externes

Les fonctions externes présentent les limitations suivantes, qui peuvent être regroupées en deux catégories : les limitations de temps de création et les limitations de temps d’exécution.

Limitations et exigences en matière de temps de création

  • Avant qu’une fonction externe puisse être appelée la première fois, un administrateur doit effectuer un travail de configuration. Ce travail nécessite une connaissance de la plate-forme Cloud (par exemple, AWS ou Microsoft Azure), notamment en matière de sécurité.

  • Snowflake appelle indirectement des services distants via un service proxy HTTP dans le Cloud (tel que Amazon API Gateway), de sorte que le service distant pour une fonction externe puisse être appelé à partir d’un service proxy. Heureusement, presque toutes les fonctions pouvant servir de point de terminaison HTTPS sont accessibles en tant que fonction externe via un service proxy. L’auteur de la fonction doit programmer le service proxy pour appeler le service distant (par exemple, une fonction exécutée sur AWS Lambda).

  • Certaines plates-formes Cloud peuvent avoir des exigences spécifiques. Par exemple, sur AWS, les fonctions externes nécessitent des points de terminaison régionaux ou privés. Pour plus de détails, voir Plates-formes prises en charge. Pour plus de détails sur les points de terminaison régionaux et privés Amazon API Gateway, voir Choix de votre type de point de terminaison : point de terminaison régional vs. point de terminaison privé.

  • Seules les fonctions, et non les procédures stockées, peuvent être écrites à l’aide de la fonctionnalité de fonctions externes.

  • Les autorisations futures de privilèges sur les fonctions externes ne sont pas prises en charge.

Limitation et problèmes liés au temps d’exécution

  • Etant donné que le service distant est opaque pour Snowflake, l’optimiseur peut ne pas être en mesure d’effectuer certaines optimisations qu’il pourrait effectuer pour des fonctions internes équivalentes.

  • Les fonctions externes ont plus de surcharge que les fonctions internes (fonctions intégrées et UDFs internes) et s’exécutent généralement plus lentement.

  • Actuellement, les fonctions externes doivent être des fonctions scalaires. Une fonction externe scalaire renvoie une valeur unique pour chaque ligne d’entrée.

  • Actuellement, les fonctions externes ne peuvent pas être partagées avec les consommateurs de données via le Secure Data Sharing.

  • La taille maximale de la réponse par lot est 10MB.

  • Les fonctions externes ne peuvent pas être utilisées dans les situations suivantes :

    • Dans le cadre d’un objet de base de données (par exemple, une table, une vue, un UDF ou une politique de masquage) partagé via Secure Data Sharing. Par exemple, vous ne pouvez pas créer une vue partagée qui utilise une fonction externe. Ceci n’est pas pris en charge :

      CREATE VIEW my_shared_view AS SELECT my_external_function(x) ...;
      CREATE SHARE things_to_share;
      ...
      GRANT SELECT ON VIEW my_shared_view TO SHARE things_to_share;
      ...
      
      Copy
    • Une clause DEFAULT d’une instruction CREATE TABLE. En d’autres termes, la valeur par défaut d’une colonne ne peut pas être une expression qui appelle une fonction externe. Si vous essayez d’inclure une fonction externe dans une clause DEFAULT , alors l’instruction CREATE TABLE échoue.

    • Une transformation COPY.

  • Les fonctions externes peuvent soulever des problèmes de sécurité supplémentaires. Par exemple, si vous appelez la fonction d’un tiers, ce tiers peut conserver des copies des données transmises à la fonction.

Facturation pour l’utilisation de fonctions externes

L’utilisation de fonctions externes entraîne des coûts normaux associés :

En outre, vous devrez peut-être payer des frais indirects ou de tiers, notamment des frais de fournisseur du service distant. Les frais peuvent varier d’un fournisseur à l’autre.

Note

Les données envoyées via des points de terminaison privés de Amazon API Gateway sont soumises à des frais AWS PrivateLink pour l’entrée et la sortie.

Plates-formes prises en charge

Plateformes qui permettent de faire appel à une fonction externe

En général, une fonction externe peut être appelée depuis un compte Snowflake sur n’importe quelle plateforme Cloud prise en charge par Snowflake :

  • Amazon Web Services (AWS)

  • Microsoft Azure

  • Google Cloud Platform (GCP)

Les exceptions sont énumérées ci-dessous :

La syntaxe SQL pour appeler une fonction externe est la même sur toutes les plateformes.

Les instructions SQL (CREATE EXTERNAL FUNCTION et CREATE API INTEGRATION) pour configurer l’accès à ces services sont les mêmes pour toutes les plateformes. Toutefois, les clauses de ces instructions varient en fonction des plateformes qui hébergent le service proxy et le service à distance.

Plates-formes permettant de créer un service à distance et un service proxy d’une fonction externe

Bien qu’une fonction externe puisse être appelée depuis n’importe quelle plateforme, le service à distance et le service proxy de la fonction externe doivent chacun être créés sur des plateformes spécifiques prises en charge.

Dans de nombreux cas, la plate-forme et le compte du service distant sont les mêmes que la plate-forme et le compte du service proxy. Cependant, cela n’est pas obligatoire. Par exemple, une requête SQL pourrait appeler une fonction Azure (service à distance) via une passerelle AWS API (service de proxy). La requête SQL elle-même pourrait être exécutée sur une instance de Snowflake fonctionnant sur GCP.

Plateformes qui prennent en charge un service à distance

Vous avez besoin d’une pile de serveurs HTTP pour héberger le service distant. Toute pile de serveurs HTTP pouvant prendre en charge le service distant doit être compatible avec les fonctions externes.

Pour créer votre service à distance, vous avez généralement besoin des éléments suivants :

  • Un compte auprès du fournisseur d’une plate-forme Cloud (par exemple, un compte Microsoft Azure pour créer une fonction Azure). Ce compte fournit des services de stockage et de calcul pour le service distant. Ce compte est distinct de votre compte Snowflake.

Snowflake fournit des instructions pour la création d’un service à distance comme :

  • Une fonction AWS Lambda.

  • Une fonction de Microsoft Azure.

  • Une fonction Google Cloud.

Des plateformes qui prennent en charge un service proxy

Vous avez besoin d’une instance d’un service proxy HTTP sur une plate-forme Cloud.

Pour configurer votre service proxy, vous avez généralement besoin des éléments suivants :

  • Un compte auprès du fournisseur d’une plate-forme Cloud (par exemple, un compte Amazon pour utiliser AWS). Ce compte fournit des services de stockage et de calcul pour le service proxy. Ce compte est distinct de votre compte Snowflake.

  • Un rôle de plate-forme Cloud qui dispose des privilèges requis pour configurer un service proxy. Ce rôle de plate-forme Cloud est distinct de vos rôles Snowflake.

Les services proxy HTTPS suivants sont pris en charge :

  • Amazon API Gateway.

  • Le service Gestion des API Microsoft Azure.

  • Google Cloud API Gateway.

Les sections ci-dessous contiennent des informations spécifiques à la plate-forme que les utilisateurs doivent connaître avant de choisir une plate-forme.

Restrictions spécifiques à la plate-forme

AWS:

  • Cette fonctionnalité prend en charge uniquement les points de terminaison régionaux et privés pour Amazon API Gateway. (Pour une description des différents types de points de terminaison, voir Points de terminaison .)

  • Les fonctions externes et les intégrations API de Snowflake ne prennent pas en charge les domaines personnalisés AWS. Pour accéder à une Amazon API Gateway à partir de Snowflake, utilisez l’URL par défaut générée par AWS, qui ressemble à ce qui suit :

    https://api-id.execute-api.region.amazonaws.com/stage
    
    Copy