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.

Dans ce chapitre :

Voir aussi :

CREATE EXTERNAL FUNCTION , CREATE API INTEGRATION

Qu’est-ce qu’une fonction externe ?

Une fonction externe appelle du code qui s’exécute en dehors de Snowflake ; le code exécuté est connu comme un service distant.

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 fonction scalaire. Une instruction SQL effectue les actions suivantes :

  1. Appelle la fonction, en validant éventuellement des paramètres.

  2. Récupère une valeur de la fonction.

Dans les instructions SQL, les fonctions externes se comportent généralement comme des UDFs (fonctions définies par l’utilisateur). Par exemple, les fonctions externes suivent ces règles :

  • A l’intérieur de Snowflake, une fonction externe est représentée comme un objet de base de données. Cet objet est créé dans une base de données et un schéma spécifiques et peut être référencé à l’aide de la notation par points (par exemple MY_DATABASE.MY_SCHEMA.MY_EXTERNAL_FUNCTION()).

  • Une fonction externe peut apparaître dans n’importe quelle clause d’une instruction SQL dans laquelle d’autres types de fonctions peuvent apparaître (par exemple la clause WHERE).

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

  • Une fonction externe peut faire partie d’une expression plus complexe :

    select upper(zipcode_to_city_external_function(zipcode))
      from address_table;
    

Termes fréquemment utilisés pour les fonctions externes

Voici les définitions des termes fréquemment utilisés :

service distant

Un service distant est stocké et exécuté en dehors de Snowflake et renvoie une valeur. Par exemple, les services distants peuvent être implémentés comme suit :

  • Une fonction AWS Lambda.

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

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

  • Exposer un point de terminaison HTTPS.

  • Accepter les entrées JSON et renvoyer les sorties JSON.

    Pour plus d’informations sur les en-têtes HTTP compatibles avec Snowflake et les données au format JSON, voir Format des données.

fonction externe

Une fonction externe est une construction Snowflake qui fait apparaître un service distant comme s’il était à l’intérieur de Snowflake, de sorte que le service distant puisse être appelé par une instruction SQL. En d’autres termes, une fonction externe fait ressembler un service distant à une fonction locale.

Une fonction externe est un ensemble d’informations que Snowflake utilise pour appeler le service distant. Ces informations incluent l’URL du service proxy (par exemple, Amazon API Gateway) 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 » et sont stockées dans un objet de base de données.

fonction définie par l’utilisateur

Une fonction définie par l’utilisateur (UDF) est une fonction écrite par un utilisateur plutôt que par Snowflake. Un UDF peut être :

  • Interne : le code exécutable est stocké et exécuté dans Snowflake.

  • Externe : une fonction externe, telle que définie ici (c’est-à-dire une construction qui fait ressembler un service distant à une fonction locale).

service proxy

Snowflake n’appelle pas directement un service distant ; en revanche, Snowflake appelle indirectement un service distant via un service proxy. Un service proxy relaie une demande ou un appel de fonction (y compris des données) d’un logiciel à un autre, par exemple de Snowflake à un service distant. En règle générale, il relaie également la ou les valeurs renvoyées à l’appelant. L’utilisation d’un service proxy augmente la flexibilité et la sécurité.

L’Amazon API Gateway est un exemple de service proxy.

lot

Un lot est un groupe de 1 lignes ou plus envoyé au service à distance.

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.

asynchrone

Un service à distance asynchrone peut être interrogé pendant que l’appelant attend les résultats. Se distingue de synchrone .

Le traitement asynchrone réduit la sensibilité aux délais d’attente.

Pour plus d’informations sur les services asynchrones, voir la description de Microsoft du modèle de demande-réponse asynchrone . (Les informations ne se limitent pas à Microsoft Azure).

Pour plus de détails sur la façon dont les utilisateurs mettent en œuvre un comportement asynchrone avec Snowflake, voir :

synchrone

Un service synchrone à distance n’envoie aucune réponse tant que les résultats ne sont pas prêts. Il ne peut pas faire l’objet d’une interrogation. Se distingue de asynchrone .

Le code synchrone est plus facile à mettre en œuvre que le code asynchrone.

Avantages des fonctions externes

Les fonctions externes présentent les avantages suivants par rapport aux autres UDFs (fonctions définies par l’utilisateur) :

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

    • Python

    • Go

    • C#

  • Les services distants peuvent utiliser des fonctions et des bibliothèques qui ne sont pas accessibles par des UDFs internes.

    • 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 ont les limitations suivantes :

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

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

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

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

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

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

    • 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. Les fonctions externes sont actuellement incompatibles avec le partage.

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

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 :

  • Frais facturés par le fournisseur du service à distant.

Les frais peuvent varier d’un fournisseur à l’autre.

Considérations supplémentaires sur les fonctions externes

  • 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), en particulier du point de vue de la sécurité.

  • L’écriture d’un service distant personnalisé nécessite généralement la connaissance de sujets tels que HTTP et les APIs REST.

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

  • Les fonctions externes peuvent entraîner des coûts de traitement supplémentaires en dehors de Snowflake.

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

  • 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 Choisissez votre type de point de terminaison : point de terminaison régional vs. point de terminaison privé.

Appel d’une fonction externe

L’appel d’une fonction externe est identique à l’appel de toute autre fonction définie par l’utilisateur. Les fonctions externes peuvent apparaître dans presque toutes les clauses dans lesquelles d’autres fonctions peuvent apparaître.

Voici des exemples d’appel d’une fonction externe scalaire :

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;

Plates-formes prises en charge

Vous aurez besoin d’une plate-forme et d’un compte sur cette plate-forme pour le service distant et pour le service proxy. Dans de nombreux cas, la plate-forme et le compte des services distants sont les mêmes que la plate-forme et le compte du service proxy. Cependant, cela n’est pas obligatoire.

Ces plate-forme(s) et compte(s) sont distincts de votre plate-forme et compte Snowflake.

Plates-formes pour le service distant

Vous aurez 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.

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

  • Une fonction AWS Lambda.

  • Une fonction de Microsoft Azure.

Plateformes pour le service proxy

Vous aurez besoin d’une instance d’un service proxy HTTP natif 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.

  • Service Gestion des API Microsoft Azure.

L’appel d’une fonction externe à partir de SQL est le même pour toutes les plateformes. Les instructions SQL nécessaires pour configurer l’accès à ces services sont les mêmes pour toutes les plateformes. Cependant, les détails administratifs, comme la copie de votre code de fonction externe au service, sont différents selon les plates-formes.

Si votre entrepôt virtuel se trouve sur Google Cloud Platform (GCP), vous pouvez créer une fonction externe qui accède à un service distant via Amazon API Gateway ou via le service Gestion des API Azure.

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 https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-basic-concept.html)

  • 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