Dans les articles précédents, on a parlé de l’architecture de Snowflake (storage / compute / cloud services) et des principaux objets : types de tables, types de views.
Mais avant d’atterrir dans une table, tes données viennent de quelque part comme par exemple un fichier sur un serveur, un bucket S3, un blob Azure, du GCS.
Dans Snowflake, cette “zone tampon” entre le monde extérieur et tes tables, c’est ce qu’on appelle un stage.
Si tu te demandes à quoi servent les @%TABLE_NAME, @~ ou @MYSTAGE, c’est exactement ça.
C'est quoi concrètement un stage dans Snowflake ?
Pour faire simple, un stage est un endroit où tu poses des fichiers de données pour que Snowflake puisse les lire (COPY INTO table FROM @stage ...), ou les écrire (COPY INTO @stage FROM table ...).
Derrière, ce stage est mappé soit vers un stockage interne géré par Snowflake, soit vers un cloud storage externe (S3, Azure Blob, GCS).
Snowflake propose donc trois grandes familles de stages :
- Table stage : lié à une table précise
- User stage : lié à un utilisateur
- Named stage : un objet que tu crées toi-même, interne ou externe
Il faut bien noté que le principe est toujours le même, c’est surtout la portée et la façon de les gérer qui changent.
Table stage
Le table stage est automatiquement créé dès que tu crées une table. Tu n’as rien à faire, il est là par défaut. Il est interne à Snowflake, lié à une seule table, et géré par le propriétaire de cette table.
On y accède avec la syntaxe @%NOM_DE_LA_TABLE. Par exemple, si tu as cette table :
CREATE TABLE sales (
id INTEGER,
sale_date DATE,
amount NUMBER(10,2)
);
Snowflake crée en coulisses un stage associé à cette table, accessible via @%sales.
Tu peux alors déposer des fichiers dans ce stage, puis les charger dans la table sales :
COPY INTO sales
FROM @%sales
FILE_FORMAT = (FORMAT_NAME = 'CSV_SALES_FORMAT');
On lit cette commande comme : “copie moi les fichiers qui sont dans le stage de sales vers la table sales”.
C’est pratique quand tu as des fichiers qui sont clairement destinés à une seule table et que plusieurs personnes peuvent être amenées à les charger.
User stage
Le user stage fonctionne un peu sur le même principe, sauf qu’il est lié à un utilisateur et pas à une table. Là encore, Snowflake le crée automatiquement pour toi.
Tu y accèdes avec @~. C’est ton coin perso c-a-d tu peux y pousser des fichiers pour faire des tests, alimenter plusieurs tables. Mais attention, ça reste un espace personnel et il doit être considéré comme tel.
COPY INTO stg_customers
FROM @~
FILE_FORMAT = (FORMAT_NAME = 'CSV_CUSTOMERS_FORMAT');
Named stage
Les named stages sont ceux que tu crées explicitement avec un CREATE STAGE. Contrairement aux deux précédents, ils ne sont pas attachés automatiquement à une table ou à un utilisateur, mais gérés comme un objet de base de données à part entière.
Tu les références avec @NOM_DU_STAGE (ou @DB.SCHEMA.NOM_DU_STAGE si tu veux être précis).
C’est ce que tu vas utiliser dès que tu mets en place un vrai flux de données partagé par plusieurs users ou tables. Tu peux donner des droits dessus, documenter son usage, l’associer à un file format, etc....
Et surtout, un named stage peut être :
- Interne : stockage géré par Snowflake.
- Externe : mappé vers un bucket AWS S3, Azure Blob ou Google Cloud Storage.
Named stage interne
Tu utilises un named stage interne quand tu veux un espace commun pour déposer des fichiers, tout en restant dans le storage Snowflake.
CREATE OR REPLACE STAGE stg_sales_internal
FILE_FORMAT = (FORMAT_NAME = 'CSV_SALES_FORMAT');
Puis :
COPY INTO stg_sales
FROM @stg_sales_internal;
Par rapport à un table stage ou user stage, tu gagnes :
- un endroit central : plusieurs users, plusieurs tables, mêmes fichiers ;
- une gestion plus propre des droits avec la commande (
GRANT USAGE ON STAGE ....).
Named stage externe
Le named stage externe, c’est ton connecteur vers ton data lake ou les cloud storage (aws, gcp, azure).
Exemple (S3) :
CREATE OR REPLACE STAGE ext_raw_events
URL = 's3://mon-bucket/raw/events/'
CREDENTIALS = (AWS_KEY_ID='...' AWS_SECRET_KEY='...')
FILE_FORMAT = (FORMAT_NAME = 'JSON_EVENTS_FORMAT');
Tu peux alors :
- Charger les données depuis S3 vers Snowflake :
COPY INTO raw_events
FROM @ext_raw_events;
- Copier les données dans S3 :
COPY INTO @ext_raw_events
FROM analytics_events;
C’est la brique de base si tu travailles avec :
- Un data lake existant ou tout simplement avec des fichiers externes (applications, outils de logs, etc....)
- Exporter des données Snowflake vers d’autres services.
Comment copier des fichiers vers un stage Snowflake ?
Jusqu’ici, on a surtout parlé des stages comme d’un endroit où tu poses des fichiers. Mais concrètement, comment tu envoies tes fichiers dedans ?
Quand tes fichiers sont sur ta machine locale, c’est la commande PUT qui fait le job. Elle permet d'envoyer un fichier depuis ton poste vers un stage interne (user stage, table stage ou named internal stage).
Par exemple, vers ton user stage :
PUT file:///Users/idriss/data/sales.csv @~/sales/;
Puis tu charges les données dans ta table avec un COPY classique :
``` sql
COPY INTO sales
FROM @~/sales/
FILE_FORMAT = (FORMAT_NAME = 'CSV_SALES_FORMAT');
```
Même idée avec un table stage :
PUT file:///Users/idriss/data/sales.csv @%sales;
ou avec un named internal stage :
PUT file:///Users/idriss/data/sales.csv @stg_sales_internal;
Nb : PUT ne marche que vers les stages internes.
Quoi choisir entre table stage, user stage ou named stage ?
Personnellement j'applique cette logique simple :
- Fichiers destinés à une seule table unique => Table stage
@%TABLE - Fichiers pour les tests, un bac à sable => User stage (
@~) - Flux de prod, partagés, plusieurs tables concernées, ou potentiellement connectés à un cloud storage externe (S3, Azure, GCP) => Named stage (
@STAGE_NAME)
Lien avec les file formats
Les stages et les file formats vont toujours ensemble :
- le stage dit “où sont les fichiers” (et sur quel storage),
- le file format explique “comment les lire” (CSV, JSON, séparateurs, encodage, etc...).
Dans le prochain article, on va regarder dans le détail les file formats en partant directement d’exemples :
CREATE OR REPLACE STAGE stg_sales_internal
FILE_FORMAT = (FORMAT_NAME = 'CSV_SALES_FORMAT');
COPY INTO sales
FROM @stg_sales_internal;
Stages + file formats = la base de tout ce qui rentre et sort de Snowflake. Une fois que tu as compris ces deux briques, les COPY INTO deviennent beaucoup plus simples à manipuler.
