Connecter Snowflake

Axiome se connecte à Snowflake comme un utilisateur de service qui s'authentifie avec une paire de clés. Axiome génère la paire pour votre espace de travail et en conserve la moitié privée ; l'utilisateur Snowflake en porte la moitié publique. Personne ne saisit de mot de passe ni ne manipule de clé privée. Les requêtes passent par l'API SQL de Snowflake, sur un entrepôt que vous choisissez, avec un rôle qui ne fait que lire.

Ce dont vous avez besoin

• L'identifiant de votre compte, orgname-accountname — dans Snowsight, votre nom › Account › View account details. Un localisateur comme xy12345.eu-west-3.aws, ou l'URL du compte, fonctionne aussi.
• La base à analyser. Une connexion lit une base ; dans cette base, les schémas que vous cochez.
• Quelqu'un qui peut exécuter un script en tant qu'ACCOUNTADMIN. Dans un schéma standard, seul un rôle doté du privilège MANAGE GRANTS peut accorder des droits sur les tables créées plus tard, ce que fait le script.

Créer un rôle, un entrepôt et un utilisateur

Le formulaire de connexion écrit le script pour vous — avec les noms saisis, les schémas cochés et la clé publique d'Axiome — sous Script d'installation, avec Copier le script. Exécutez-le en entier dans une feuille de calcul Snowsight, en tant qu'ACCOUNTADMIN. Il peut être relancé : il ne crée que ce qui manque, et attribue à nouveau la clé et les paramètres.

Avec les noms par défaut du formulaire, une base ANALYTICS et les schémas MARTS et FINANCE cochés, il se lit ainsi :

-- L'accès d'Axiome à Snowflake. À exécuter en entier, en tant qu'ACCOUNTADMIN ; il peut être relancé.
USE ROLE ACCOUNTADMIN;

-- Un petit entrepôt qui se suspend après une minute d'inactivité (le défaut de Snowflake, dix minutes, facture dix minutes à chaque réveil).
CREATE WAREHOUSE IF NOT EXISTS AXIOME_WH
  WAREHOUSE_SIZE = XSMALL AUTO_SUSPEND = 60 AUTO_RESUME = TRUE INITIALLY_SUSPENDED = TRUE;

-- Le rôle d'Axiome : il lit, et n'écrit jamais.
CREATE ROLE IF NOT EXISTS AXIOME_READER;
GRANT USAGE ON WAREHOUSE AXIOME_WH TO ROLE AXIOME_READER;
GRANT USAGE ON DATABASE ANALYTICS TO ROLE AXIOME_READER;
-- Ce que le rôle lit : les schémas cochés dans le formulaire d'Axiome.
GRANT USAGE ON SCHEMA ANALYTICS.MARTS TO ROLE AXIOME_READER;
GRANT SELECT ON ALL TABLES IN SCHEMA ANALYTICS.MARTS TO ROLE AXIOME_READER;
GRANT SELECT ON ALL VIEWS IN SCHEMA ANALYTICS.MARTS TO ROLE AXIOME_READER;
GRANT SELECT ON FUTURE TABLES IN SCHEMA ANALYTICS.MARTS TO ROLE AXIOME_READER;
GRANT SELECT ON FUTURE VIEWS IN SCHEMA ANALYTICS.MARTS TO ROLE AXIOME_READER;
GRANT USAGE ON SCHEMA ANALYTICS.FINANCE TO ROLE AXIOME_READER;
GRANT SELECT ON ALL TABLES IN SCHEMA ANALYTICS.FINANCE TO ROLE AXIOME_READER;
GRANT SELECT ON ALL VIEWS IN SCHEMA ANALYTICS.FINANCE TO ROLE AXIOME_READER;
GRANT SELECT ON FUTURE TABLES IN SCHEMA ANALYTICS.FINANCE TO ROLE AXIOME_READER;
GRANT SELECT ON FUTURE VIEWS IN SCHEMA ANALYTICS.FINANCE TO ROLE AXIOME_READER;

-- L'utilisateur avec lequel Axiome se connecte, réservé à Axiome : lui attribuer sa clé remplace toute clé qu'il avait.
CREATE USER IF NOT EXISTS AXIOME_SVC
  TYPE = SERVICE
  DEFAULT_ROLE = AXIOME_READER
  DEFAULT_WAREHOUSE = AXIOME_WH;
-- La clé, et les paramètres de session dont dépend le SQL d'Axiome.
ALTER USER AXIOME_SVC SET
  RSA_PUBLIC_KEY = 'MIIBIjANBgkqhkiG9w0BAQEF…IDAQAB'
  DEFAULT_SECONDARY_ROLES = ()
  QUOTED_IDENTIFIERS_IGNORE_CASE = FALSE
  TIMEZONE = 'UTC'
  DATE_INPUT_FORMAT = 'AUTO'
  TIMESTAMP_INPUT_FORMAT = 'AUTO'
  TIMESTAMP_TYPE_MAPPING = 'TIMESTAMP_NTZ'
  WEEK_START = 0;
GRANT ROLE AXIOME_READER TO USER AXIOME_SVC;

À quoi sert chaque partie :

• Un entrepôt à lui : X-Small, suspendu après 60 secondes d'inactivité. Snowflake facture un entrepôt à la seconde, au moins une minute à chaque reprise, et par défaut le laisse tourner dix minutes après la dernière requête — les mêmes alertes coûtent alors environ huit fois plus. Pour utiliser un entrepôt que vous dimensionnez déjà pour la BI, indiquez-le plutôt dans le formulaire et réglez vous-même son AUTO_SUSPEND. Voir Ce que ça coûte.
• Un rôle qui ne fait que lire. Il a USAGE sur l'entrepôt, la base et les schémas cochés, et SELECT sur leurs tables et vues, y compris celles créées plus tard. Snowflake n'a pas de transaction en lecture seule : c'est le rôle qui empêche Axiome d'écrire, ne lui accordez donc rien d'autre.
• Un utilisateur réservé à Axiome. TYPE = SERVICE est le type que Snowflake réserve aux programmes : il s'authentifie avec une clé, jamais avec un mot de passe ni MFA. Lui attribuer sa clé remplace toute clé qu'il portait : ne partagez pas cet utilisateur avec un autre outil.
• Les paramètres de session dont dépend le SQL d'Axiome, attribués à l'utilisateur, car une requête ne peut pas régler la plupart d'entre eux :
  • QUOTED_IDENTIFIERS_IGNORE_CASE = FALSE — avec TRUE, chaque nom qu'Axiome relit revient en majuscules. Le test de connexion refuse un utilisateur qui l'a.
  • DEFAULT_SECONDARY_ROLES = () — seul le rôle de la connexion s'applique, jamais un autre rôle accordé à l'utilisateur. Le test refuse un utilisateur dont des rôles secondaires sont actifs.
  • TIMEZONE = 'UTC' — chaque requête demande UTC de toute façon.
  • DATE_INPUT_FORMAT, TIMESTAMP_INPUT_FORMAT, TIMESTAMP_TYPE_MAPPING et WEEK_START — les requêtes d'Axiome n'en dépendent pas, mais le SQL écrit à la main, comme celui d'Axi, les lit. Le test signale un utilisateur dont les valeurs diffèrent.

Exécutez le script avant le premier test : tant que l'utilisateur ne porte pas la clé, Snowflake refuse Axiome.

Restreindre les droits à certains schémas

Le test de connexion liste les schémas que le rôle voit, si bien que le tout premier script, exécuté avant qu'aucun schéma ne soit coché, accorde à la place la base entière : USAGE sur tous ses schémas, et SELECT sur toutes ses tables et vues, présentes et futures. Pour limiter le rôle aux schémas que vous cochez, révoquez ces droits, puis relancez le script du formulaire — il accorde désormais les droits schéma par schéma :

USE ROLE ACCOUNTADMIN;
REVOKE USAGE ON FUTURE SCHEMAS IN DATABASE ANALYTICS FROM ROLE AXIOME_READER;
REVOKE SELECT ON FUTURE TABLES IN DATABASE ANALYTICS FROM ROLE AXIOME_READER;
REVOKE SELECT ON FUTURE VIEWS IN DATABASE ANALYTICS FROM ROLE AXIOME_READER;
REVOKE USAGE ON ALL SCHEMAS IN DATABASE ANALYTICS FROM ROLE AXIOME_READER;
REVOKE SELECT ON ALL TABLES IN DATABASE ANALYTICS FROM ROLE AXIOME_READER;
REVOKE SELECT ON ALL VIEWS IN DATABASE ANALYTICS FROM ROLE AXIOME_READER;

Un schéma qui a ses propres droits futurs ignore ceux de la base : accordez-y SELECT ON FUTURE TABLES (et les vues) dans le schéma lui-même, comme le fait le script par schéma.

Un moniteur de ressources

Un moniteur de ressources plafonne ce que l'entrepôt peut dépenser en un mois. Le script n'en crée pas ; celui-ci prévient à 80 % de 20 crédits et suspend l'entrepôt à 100 % :

USE ROLE ACCOUNTADMIN;
CREATE RESOURCE MONITOR IF NOT EXISTS AXIOME_MONITOR
  WITH CREDIT_QUOTA = 20 FREQUENCY = MONTHLY START_TIMESTAMP = IMMEDIATELY
  TRIGGERS ON 80 PERCENT DO NOTIFY
           ON 100 PERCENT DO SUSPEND;
ALTER WAREHOUSE AXIOME_WH SET RESOURCE_MONITOR = AXIOME_MONITOR;

Une fois l'entrepôt suspendu par le moniteur, chaque tableau de bord, alerte et question à Axi sur la connexion échoue jusqu'au mois suivant ou à un quota plus élevé : dimensionnez-le d'après Ce que ça coûte.

Ajouter la connexion

1. Allez dans Paramètres → Espace de travail → Données, cliquez sur Ajouter une connexion et choisissez Snowflake dans le catalogue des sources.
2. Dans Général, nommez la connexion.
3. Dans Identifiants, saisissez le Compte. La ligne en dessous indique l'hôte auquel Axiome se connectera. Utilisateur, Rôle et Entrepôt commencent à AXIOME_SVC, AXIOME_READER et AXIOME_WH, les noms du script ; saisissez la Base. Les noms se lisent comme Snowflake les lit : sans guillemets, en majuscules ; entre guillemets doubles, tels qu'écrits.
4. Sous Clé publique d'Axiome, cliquez sur Générer la clé — une fois par espace de travail : toutes ses connexions Snowflake utilisent la même clé.
5. Sous Script d'installation, cliquez sur Copier le script et exécutez-le dans Snowsight, en tant qu'ACCOUNTADMIN (ci-dessus).
6. Cliquez sur Tester la connexion en haut de la page. Le test se connecte et lit les métadonnées de Snowflake — il ne réveille jamais l'entrepôt — et liste les schémas que le rôle voit. Quand quelque chose ne va pas, il dit quoi, du plus fondamental au moins, chacun avec le SQL qui le corrige (Dépannage).
7. Dans Schémas, cochez ceux à analyser — voir ci-dessous.
8. Cliquez sur Créer la connexion.

Rien dans une connexion Snowflake n'est secret : la moitié privée de la clé appartient à l'espace de travail, conservée dans Google Cloud Secret Manager et utilisée uniquement côté serveur. Pour changer plus tard le compte, l'utilisateur, le rôle, l'entrepôt ou la base, ouvrez les Paramètres de la connexion.

Schémas

Le test liste les schémas de la base que le rôle voit (hors INFORMATION_SCHEMA). Cochez-en au moins un. Comme sur PostgreSQL :

• Le premier coché est le schéma principal (choisissez-en un autre dans Schéma principal). Ses tables gardent leur nom simple.
• Les tables des autres schémas reçoivent un modèle sémantique nommé d'après les deux — FINANCE__BUDGETS pour BUDGETS dans FINANCE, affiché finance__budgets.
• Axiome ne lit que les schémas nommés avec des lettres, chiffres, _ et $ : un schéma dont le nom demande des guillemets doubles ne peut pas être coché.
• Une autre base, c'est une autre connexion.

Voir Datasets et schémas pour la recherche, la sélection de plusieurs schémas d'un coup et le changement de principal.

Comment vos tables se lisent dans Axiome

Axiome lit le schéma avec des commandes SHOW — tables, vues, colonnes, clés primaires et étrangères — qui s'exécutent sur les services cloud de Snowflake et ne réveillent jamais l'entrepôt, aussi souvent que tourne le rafraîchissement en arrière-plan. Avec les colonnes, il lit les commentaires des tables et des colonnes, qui deviennent les descriptions des modèles générés, et les clés déclarées, qui deviennent leurs jointures.

• Les noms. Snowflake stocke un nom sans guillemets en majuscules, et Axiome le garde exactement ainsi — le SQL qu'il écrit cite toujours le nom exact entre guillemets. Un nom en majuscules s'affiche en minuscules : ORDERS et ORDER_DATE se lisent orders et order_date dans les éditeurs et dans les réponses d'Axi. Un nom entre guillemets, comme "Order Date", s'affiche tel quel, de même que deux noms qui se liraient pareil (ORDERS à côté d'un "orders" entre guillemets).
• Les types. Nombres, textes, booléens, dates et horodatages sont des champs comme les autres ; les colonnes DATE et TIMESTAMP sont des dimensions temporelles. Une colonne TIME est une catégorie, car aucun grain du calendrier ne convient à une heure de la journée. Les colonnes VARIANT, OBJECT, ARRAY, GEOGRAPHY, GEOMETRY et VECTOR sont listées sur la page de la table mais pas proposées comme champs.
• Les fuseaux horaires. Chaque requête s'exécute en UTC. Une valeur TIMESTAMP_TZ est lue à son instant UTC et une TIMESTAMP_LTZ en UTC, si bien qu'un jour est un jour UTC, comme sur BigQuery ; une TIMESTAMP_NTZ est lue telle qu'écrite. Les semaines commencent le lundi (ou le premier jour de la semaine de votre espace de travail), jamais au WEEK_START du compte.
• Les vues sémantiques ne sont pas listées comme des tables.
• dbt. Un projet dbt qui construit sur Snowflake s'importe comme les autres, ses noms rattachés comme Snowflake les stocke : voir Importer depuis dbt.

Ce qu'Axiome exécute sur votre entrepôt

Chaque requête qu'envoie Axiome nomme son rôle, son entrepôt et sa base, s'exécute en UTC, contient une seule instruction et porte une limite de temps — 30 secondes pour les composants et les requêtes d'Axi, 20 secondes pour les lectures de valeurs. Passé ce délai, Axiome annule l'instruction dans Snowflake.

Étiquetées. Chaque requête porte une étiquette de requête (query tag), pour que vous distinguiez les requêtes d'Axiome dans QUERY_HISTORY et dans les vues de coûts de Snowsight — {"app":"axiome","surface":"dashboard","connection":"…"}, avec l'identifiant Axiome de votre connexion. Elle ne contient aucun nom ni aucune adresse e-mail. La surface dit ce que la requête a servi :

Surface	Ce qui s'exécute
dashboard	Les composants et leurs données, l'Aperçu d'une table, les exécutions de métriques de la section Données, les graphiques des réponses d'Axi
axi	Ce qu'exécutent les outils d'Axi, y compris les résumés et vérifications d'alertes qu'Axi lance
alert	Les vérifications d'alertes et les rapports planifiés, et le bouton Envoyer un test d'une alerte
summary	Un résumé IA que quelqu'un génère ou actualise
forecast	L'historique que lit une prévision ou la projection d'un KPI
lookup	La liste de valeurs d'un filtre, le profil d'une colonne, une recherche de valeur, une vérification de clé
schema · test	La lecture du schéma, et Tester la connexion

Pour lire la dernière semaine de requêtes d'Axiome, avec un rôle qui voit l'usage du compte (elle s'exécute sur votre propre entrepôt) :

SELECT START_TIME, TRY_PARSE_JSON(QUERY_TAG):surface::STRING AS SURFACE,
       TOTAL_ELAPSED_TIME / 1000 AS SECONDS, WAREHOUSE_NAME
FROM SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY
WHERE USER_NAME = 'AXIOME_SVC' AND START_TIME > DATEADD('day', -7, CURRENT_TIMESTAMP())
ORDER BY START_TIME DESC;

Servies par le cache de résultats. Le SQL qu'écrit Axiome ne change pas entre deux exécutions du même composant : une période relative comme les 30 derniers jours est écrite avec ses dates. Quand les données n'ont pas changé, Snowflake répond donc à une répétition depuis son cache de résultats, jusqu'à 24 heures, sans l'entrepôt.

En file d'attente. Un entrepôt X-Small exécute huit requêtes à la fois ; au-delà, Snowflake les met en file, et le temps passé en file compte dans la limite de temps. Axi cherche une valeur dans trois colonnes à la fois, pour que ses recherches ne remplissent pas l'entrepôt. Une équipe dont les tableaux de bord dépassent le délai aux heures chargées a besoin d'un entrepôt plus grand, ou multi-cluster (édition Enterprise).

En lecture seule, quel que soit l'auteur du SQL. Le SQL écrit par Axi s'exécute avec le même rôle, une instruction à la fois, et il est vérifié comme Snowflake le lit avant d'être envoyé.

Ce que ça coûte

Le test de connexion et les lectures du schéma ne réveillent jamais l'entrepôt : ils s'exécutent sur les services cloud de Snowflake, que Snowflake ne facture qu'au-delà d'un dixième du calcul quotidien des entrepôts. Tout le reste s'exécute sur l'entrepôt, et un entrepôt suspendu reprend pour cela — facturé à la seconde à partir de là jusqu'à sa nouvelle suspension, et au moins une minute. Avec l'entrepôt du script (X-Small, un crédit par heure, suspendu après 60 secondes) :

Ce que fait Axiome	Temps d'entrepôt
Le test de connexion, la lecture du schéma et son rafraîchissement en arrière-plan	aucun
Une requête dont la réponse est dans le cache de résultats	aucun
Un tableau de bord ouvert pendant que l'entrepôt dort	environ 70 à 100 secondes : ses requêtes, puis la minute que l'entrepôt attend avant de se suspendre
Une alerte horaire, sur un entrepôt sinon inactif	environ 30 à 40 minutes par jour
Une alerte toutes les 30 minutes	jusqu'à 1 à 1,5 heure par jour
Une alerte toutes les 15 minutes	jusqu'à 2 à 3 heures par jour

Les alertes qui vérifient toutes les 15 ou 30 minutes, ou toutes les heures, le font à heure fixe — à l'heure pile, à la demie, au quart — si bien que les alertes d'un espace de travail dues en même temps partagent un seul réveil. Sur une connexion Snowflake, l'éditeur d'alertes indique ce que coûte une vérification toutes les 15 ou 30 minutes avant que vous l'enregistriez. Avec le défaut de Snowflake, dix minutes avant la suspension, chaque réveil facture dix minutes au lieu d'une.

Politiques réseau

Les serveurs d'Axiome ne se connectent pas encore depuis des adresses fixes, il n'y a donc aucune adresse à autoriser : une politique réseau qui s'applique à l'utilisateur d'Axiome le refuse, et le test indique La politique réseau de votre compte refuse l'adresse d'Axiome.

Une politique attribuée au compte s'applique à chaque utilisateur qui n'en a pas en propre, et Snowflake applique la politique propre d'un utilisateur à la place de celle du compte. Avec une politique sur le compte, l'utilisateur d'Axiome ne se connecte donc que sous une politique à lui qui autorise toute adresse — il ne s'authentifie toujours qu'avec la clé d'Axiome. Que cela convienne à votre compte est la décision de votre équipe sécurité. La connexion par PrivateLink n'est pas prise en charge.

Changer la clé

Une seule clé sert toutes les connexions Snowflake de l'espace de travail. Pour la remplacer — au rythme que fixe votre politique de sécurité, ou parce que vous la pensez exposée :

1. Ouvrez les Paramètres d'une connexion Snowflake (ou la page d'une nouvelle connexion Snowflake) et, sous Clé publique d'Axiome, cliquez sur Régénérer.

2. Lisez la confirmation : elle indique combien de connexions Snowflake ne peuvent plus se connecter tant que leurs utilisateurs ne portent pas la nouvelle clé. Confirmez avec Régénérer. Axiome cesse immédiatement d'utiliser l'ancienne clé et en supprime la moitié privée.

3. Attribuez la nouvelle clé à l'utilisateur de chaque connexion Snowflake, en tant qu'ACCOUNTADMIN — relancez le script d'installation de chaque connexion, qui contient la nouvelle clé, ou :

   ALTER USER AXIOME_SVC SET RSA_PUBLIC_KEY = 'MIIBIjANBgkqhkiG9w0BAQEF…IDAQAB';

Entre les deux étapes, les tableaux de bord, alertes et questions à Axi Snowflake de l'espace de travail échouent avec le message sur la clé : exécutez la ligne sans attendre. Deux administrateurs ne peuvent pas changer la clé deux fois par erreur : un administrateur qui voit encore l'ancienne clé reçoit la nouvelle au lieu de la remplacer à son tour.

Dépannage

Le test de connexion formule ce qu'il a trouvé dans votre langue et, quand du SQL le corrige, donne la ligne à exécuter (Copier), adaptée à vos noms :

Le test indique	Cause	Correction
Aucun compte Snowflake ne répond à …	L'identifiant ne désigne aucun compte	Copiez l'identifiant depuis Snowsight : votre nom › Account › View account details
Snowflake a refusé la clé d'Axiome pour …	L'utilisateur ne porte pas la clé, n'existe pas, ou se trouve dans un autre compte. Une URL de compte change les tirets bas d'un nom de compte en tirets	Exécutez le script d'installation, ou la ligne ALTER USER … SET RSA_PUBLIC_KEY que donne le test. Des échecs répétés bloquent l'utilisateur un moment : ALTER USER AXIOME_SVC SET MINS_TO_UNLOCK = 0;
Générez d'abord la clé d'Axiome…	L'espace de travail n'a pas encore de clé	Générer la clé, puis exécutez le script d'installation
Le rôle … n'est pas accordé à …, ou n'existe pas	Le script n'a pas été exécuté, ou un autre rôle a été saisi	GRANT ROLE AXIOME_READER TO USER AXIOME_SVC;
Le rôle … ne peut pas utiliser l'entrepôt …	L'entrepôt n'existe pas, ou le rôle n'a pas USAGE dessus	GRANT USAGE ON WAREHOUSE AXIOME_WH TO ROLE AXIOME_READER;
Le rôle … ne voit pas la base …	La base n'existe pas, ou le rôle n'a pas USAGE dessus	GRANT USAGE ON DATABASE ANALYTICS TO ROLE AXIOME_READER;
Le rôle … ne voit aucun schéma dans …, ou ne voit pas ces schémas	Pas de USAGE sur les schémas	Les lignes GRANT USAGE ON SCHEMA que donne le test
Des paramètres de … sous lesquels le SQL d'Axiome ne peut pas fonctionner	QUOTED_IDENTIFIERS_IGNORE_CASE = TRUE, ou des rôles secondaires actifs	La ligne ALTER USER que donne le test
À aligner (une note ; le test réussit)	WEEK_START, les formats de saisie ou TIMESTAMP_TYPE_MAPPING diffèrent de ceux du script	La ligne ALTER USER, pour le SQL écrit à la main
La politique réseau de votre compte refuse l'adresse d'Axiome	Une politique réseau s'applique à l'utilisateur	Voir Politiques réseau
Snowflake n'a pas répondu en 20 secondes	Un compte lent ou chargé	Testez à nouveau

Une fois connecté :

Symptôme	Cause probable
Un composant ou Axi indique que le rôle n'a pas de privilège sur une table	La table se trouve dans un schéma qui a ses propres droits futurs, ou a été créée par un rôle que les droits n'atteignent pas : GRANT SELECT ON TABLE … TO ROLE AXIOME_READER;. Le message d'Axi nomme le droit à accorder
Les composants dépassent le délai aux heures chargées	Les requêtes ont attendu l'entrepôt : le temps en file compte dans la limite de 30 secondes. Agrandissez l'entrepôt, ou donnez à Axiome le sien
Une table ou une colonne manque	Son schéma n'est pas coché, ou le rôle ne peut pas la lire (SELECT). Une colonne VARIANT, OBJECT, ARRAY, GEOGRAPHY, GEOMETRY ou VECTOR n'est pas proposée comme champ
Une date transformée en texte — par le TOTEXT d'une formule, ou dans le SQL d'Axi — se lit dans un autre format	Le DATE_OUTPUT_FORMAT de l'utilisateur (ou celui d'un horodatage) : ALTER USER AXIOME_SVC UNSET DATE_OUTPUT_FORMAT;
Toutes les requêtes s'arrêtent d'un coup	Le moniteur de ressources a suspendu l'entrepôt, ou la clé a été régénérée et les utilisateurs ne la portent pas encore