CREATE PIPE

Crée un canal dans le système pour définir l’instruction COPY INTO <table> utilisée par Snowpipe pour charger les données d’une file d’attente d’acquisition dans des tables.

Voir aussi :

ALTER PIPE, DROP PIPE , SHOW PIPES , DESCRIBE PIPE

Syntaxe

CREATE [ OR REPLACE ] PIPE [ IF NOT EXISTS ] <name>
  [ AUTO_INGEST = [ TRUE | FALSE ] ]
  [ ERROR_INTEGRATION = <integration_name> ]
  [ AWS_SNS_TOPIC = '<string>' ]
  [ INTEGRATION = '<string>' ]
  [ COMMENT = '<string_literal>' ]
  AS <copy_statement>
Copy

Paramètres requis

name

Identificateur du canal ; doit être unique pour le schéma dans lequel le canal est créé.

L’identificateur doit commencer par un caractère alphabétique et ne peut pas contenir d’espaces ou de caractères spéciaux à moins que toute la chaîne d’identificateur soit délimitée par des guillemets doubles (p. ex. "My object"). Les identificateurs entre guillemets doubles sont également sensibles à la casse.

Pour plus de détails, voir Exigences relatives à l’identificateur.

copy_statement

Instruction COPY INTO <table> utilisée pour charger des données à partir de fichiers en file d’attente dans une table Snowflake. Cette instruction sert de texte/définition pour le canal, et elle est affichée dans la sortie SHOW PIPES.

Note

Nous ne recommandons pas actuellement d’utiliser les fonctions suivantes dans le copy_statement pour Snowpipe :

  • CURRENT_DATE

  • CURRENT_TIME

  • CURRENT_TIMESTAMP

  • GETDATE

  • LOCALTIME

  • LOCALTIMESTAMP

  • SYSDATE

  • SYSTIMESTAMP

Il est connu que les valeurs horaires insérées à l’aide de ces fonctions peuvent être antérieures de quelques heures aux valeurs LOAD_TIME retournées par la fonction COPY_HISTORY ou la vue COPY_HISTORY.

Il est recommandé d’interroger METADATA$START_SCAN_TIME à la place, qui fournit une représentation plus précise du chargement de l’enregistrement.

Paramètres facultatifs

AUTO_INGEST = TRUE | FALSE

Indique si les fichiers de données de la zone de préparation externe et du chemin facultatif spécifiés doivent être chargés automatiquement lorsque des notifications d’événements sont reçues d’un service de messagerie configuré :

  • TRUE active le chargement automatique des données.

    Snowpipe prend en charge le chargement à partir de zones de préparation externes (Amazon S3, Google Cloud Storage ou Microsoft Azure).

  • FALSE désactive le chargement automatique des données. Vous devez appeler les points de terminaison REST API Snowpipe pour charger des fichiers de données.

    Snowpipe prend en charge le chargement depuis des zones de préparation internes (c’est-à-dire les zones de préparation nommées ou de table Snowflake mais pas les zones de préparation utilisateur) ou externes (Amazon S3, Google Cloud Storage ou Microsoft Azure).

ERROR_INTEGRATION = 'integration_name'

Requis uniquement lors de la configuration de Snowpipe pour envoyer des notifications d’erreur vers un service de messagerie dans le Cloud.

Spécifie le nom de l’intégration de notification utilisée pour communiquer avec le service de messagerie. Pour plus d’informations, voir Notifications d’erreur Snowpipe.

AWS_SNS_TOPIC = 'string'

Requis uniquement lors de la configuration de AUTO_INGEST pour les zones de préparation Amazon S3 qui utilisent SNS.

Spécifie l’ARN (Amazon Resource Name) du sujet SNS de votre compartiment S3. L’instruction CREATE PIPE souscrit la file d’attente Amazon Simple Queue Service (SQS) au sujet SNS spécifié. Le canal copie les fichiers dans la file d’attente d’intégration déclenchée par des notifications d’événement via le sujet SNS. Pour plus d’informations, voir Automatisation de Snowpipe pour Amazon S3.

INTEGRATION = 'string'

Requis uniquement lors de la configuration de AUTO_INGEST pour Google Cloud Storage ou les zones de préparation Microsoft Azure.

Spécifie l’intégration de notification existante utilisée pour accéder à la file d’attente de stockage. Pour plus d’informations, voir :

Le nom de l’intégration doit être saisi en majuscules.

COMMENT = 'string_literal'

Spécifie un commentaire pour la barre verticale.

Par défaut : aucune valeur

Notes sur l’utilisation

  • Cette commande SQL requiert les autorisations minimales suivantes :

    Privilège

    Objet

    Remarques

    CREATE PIPE

    Schéma

    USAGE

    Définition de la zone de préparation d’un canal

    Zones de préparation externes uniquement

    READ

    Définition de la zone de préparation d’un canal

    Zones de préparation internes uniquement

    SELECT, INSERT

    Table dans la définition du canal

    Les opérations SQL sur les objets de schéma nécessitent également le privilège USAGE sur la base de données et le schéma qui contiennent l’objet.

  • Toutes les options de copie COPY INTO <table> sont prises en charge à l’exception des suivantes :

    • FILES = ( 'file_name1' [ , 'file_name2', ... ] )

    • ON_ERROR = ABORT_STATEMENT

    • SIZE_LIMIT = num

    • PURGE = TRUE | FALSE (c.-à-d. purge automatique pendant le chargement)

    • FORCE = TRUE | FALSE

      Notez que vous pouvez supprimer manuellement les fichiers d’une zone de préparation interne (par exemple, Snowflake) (après leur chargement) à l’aide de la commande REMOVE.

    • RETURN_FAILED_ONLY = TRUE | FALSE

    • VALIDATION_MODE = RETURN_n_ROWS | RETURN_ERRORS | RETURN_ALL_ERRORS

  • L’option de copie PATTERN = 'regex_pattern' filtre l’ensemble de fichiers à charger à l’aide d’une expression régulière. La correspondance de modèle se comporte comme suit en fonction de la valeur du paramètre AUTO_INGEST :

    • AUTO_INGEST = TRUE : l’expression régulière filtre la liste des fichiers dans la zone de préparation et le chemin facultatif (c’est-à-dire l’emplacement de stockage sur le Cloud) dans l’instruction COPY INTO <table>.

    • :AUTO_INGEST = FALSE : l’expression régulière filtre la liste des fichiers soumis lors des appels au point de terminaison Snowpipe API REST insertFiles.

    Notez que Snowpipe supprime tous les segments de chemin dans la définition de la zone de préparation de l’emplacement de stockage et applique l’expression régulière à tous les segments de chemin et noms de fichiers restants. Pour visualiser la définition de la zone de préparation, exécutez la commande DESCRIBE STAGE pour la zone de préparation. La propriété URL est constituée du nom du compartiment ou du conteneur et de zéro ou plusieurs segments de chemin d’accès. Par exemple, si l’emplacement FROM dans une instruction COPY INTO <table> est @s/path1/path2/ et que la valeur URL de la zone de préparation @s est s3://mybucket/path1/, Snowpipe extrait /path1/ de l’emplacement de stockage dans la clause FROM et applique l’expression régulière à path2/ et aux noms de fichiers du chemin d’accès.

    Important

    Snowflake recommande d’activer le filtrage des événements dans le Cloud pour Snowpipe afin de réduire les coûts, le bruit des événements et la latence. N’utilisez l’option PATTERN que lorsque la fonction de filtrage des événements de votre fournisseur de Cloud n’est pas suffisante. Pour plus d’informations sur la configuration du filtrage des événements pour chaque fournisseur de Cloud, consultez les pages suivantes :

  • L’utilisation d’une requête comme source de l’instruction COPY pour la réorganisation des colonnes, l’omission de colonnes et les conversions (c’est-à-dire la transformation des données pendant un chargement) est disponible. Pour des exemples d’utilisation, voir Transformation des données lors d’un chargement. Notez que seules les instructions simples SELECT sont prises en charge. Le filtrage à l’aide d’une clause WHERE n’est pas pris en charge.

  • Les définitions de barres verticales ne sont pas dynamiques (autrement dit, une barre verticale n’est pas automatiquement mise à jour si la zone de préparation ou la table sous-jacente change, en cas de destruction ou de changement de nom, par exemple). En revanche, vous devez créer un nouveau canal et soumettre le nom de ce canal dans de futurs appels d’API REST de Snowpipe.

  • Concernant les métadonnées :

    Attention

    Les clients doivent s’assurer qu’aucune donnée personnelle (autre que pour un objet utilisateur), donnée sensible, donnée à exportation contrôlée ou autre donnée réglementée n’est saisie comme métadonnée lors de l’utilisation du service Snowflake. Pour plus d’informations, voir Champs de métadonnées dans Snowflake.

  • Les instructions CREATE OR REPLACE <objet> sont atomiques. En d’autres termes, lorsqu’un objet est remplacé, l’ancien objet est supprimé et le nouvel objet est créé dans une seule transaction.

Important

Si vous recréez un canal (à l’aide de la syntaxe CREATE OR REPLACE PIPE), consultez Recréation de canaux pour connaître les considérations et les meilleures pratiques associées.

Exemples

Créer un canal dans le schéma actuel qui charge toutes les données des fichiers de la zone de préparation mystage dans mytable :

create pipe mypipe as copy into mytable from @mystage;
Copy

Comme dans l’exemple précédent, mais avec une transformation de données. Charger uniquement les données des 4e et 5e colonnes dans les fichiers mis en zone de préparation, dans l’ordre inverse :

create pipe mypipe2 as copy into mytable(C1, C2) from (select $5, $4 from @mystage);
Copy

Créer un canal dans le schéma actuel pour le chargement automatique de données à l’aide de notifications d’événements reçues d’un service de messagerie :

Amazon S3

create pipe mypipe_s3
  auto_ingest = true
  aws_sns_topic = 'arn:aws:sns:us-west-2:001234567890:s3_mybucket'
  as
  copy into snowpipe_db.public.mytable
  from @snowpipe_db.public.mystage
  file_format = (type = 'JSON');
Copy

Google Cloud Storage

create pipe mypipe_gcs
  auto_ingest = true
  integration = 'MYINT'
  as
  copy into snowpipe_db.public.mytable
  from @snowpipe_db.public.mystage
  file_format = (type = 'JSON');
Copy

Microsoft Azure

create pipe mypipe_azure
  auto_ingest = true
  integration = 'MYINT'
  as
  copy into snowpipe_db.public.mytable
  from @snowpipe_db.public.mystage
  file_format = (type = 'JSON');
Copy