Omni Model Explorer

Explorez et comprenez un modèle sémantique Omni via l'Omni CLI. C'est le point de départ — comprenez ce qui existe avant de construire, interroger ou modifier quoi que ce soit.

Conseil : Commencez par le modèle Shared — il contient la couche analytics curée.

Prérequis

Configurez l'Omni CLI :

# Vérifiez que l'Omni CLI est installé — sinon, demandez à l'utilisateur de l'installer
# Voir : https://github.com/exploreomni/cli#readme
command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."

# Affichez les profils disponibles et sélectionnez celui approprié
omni config show
# Si plusieurs profils existent, demandez à l'utilisateur lequel utiliser, puis basculez :
omni config use <profile-name>

Clés API : Settings > API Keys (Organization Admin) ou User Profile > Manage Account > Generate Token (Personal Access Token).

Découvrir les commandes

Quand vous ne savez pas quelles opérations ou flags sont disponibles :

omni models --help              # Lister toutes les opérations de modèle
omni models <operation> --help  # Afficher les flags et arguments positionnels

Conseil : Utilisez -o json pour forcer une sortie structurée pour l'analyse programmatique, ou -o human pour des tableaux lisibles. La valeur par défaut est auto (humain dans un TTY, JSON quand piped).

Flux de travail fondamental

Explorez de haut en bas : Lister les modèles → Choisir un modèle → Lister les topics → Inspecter un topic → Explorer les vues et champs.

Étape 1 : Lister les modèles disponibles

omni models list

Retourne les modèles avec id, name, connectionId, et modelKind (SCHEMA ou SHARED). Utilisez le modèle SHARED — il contient la couche sémantique curée.

Pour voir aussi les branches actives sur chaque modèle :

omni models list --include activeBranches

Chaque modèle dans la réponse inclura un tableau branches. Chaque branche a un id (UUID) et un name — utilisez l'id comme paramètre branchId dans les autres appels API.

Étape 2 : Lister les topics dans un modèle

Les topics sont des points d'entrée pour interroger. Chaque topic définit une vue de base et l'ensemble des vues jointes disponibles.

omni models list-topics <modelId>

Retourne les noms des topics, les vues de base, les labels et les descriptions.

Étape 3 : Inspecter un topic

Obtenez les détails complets incluant toutes les vues, dimensions, mesures, relations et contexte IA :

omni models get-topic <modelId> <topicName>

La réponse inclut :

• base_view_name — la table principale
• views[] — toutes les vues accessibles, chacune avec dimensions[] et measures[]
• relationships[] — comment les vues se joignent ensemble
• default_filters — filtres appliqués par défaut
• ai_context — instructions pour Blobby (l'IA d'Omni)

Étape 4 : Lire le YAML du modèle

Pour la définition du modèle sémantique complet :

# Tous les fichiers YAML
omni models yaml-get <modelId>

# Fichier spécifique
omni models yaml-get <modelId> --filename order_items.view

# Filtre regex
omni models yaml-get <modelId> --filename '.*sales.*'

# Depuis une branche (branchId est un UUID de la réponse list models)
omni models yaml-get <modelId> --branchid <branchId>

Le paramètre mode : combined (défaut) fusionne schema + modèle partagé ; extension affiche uniquement les personnalisations du modèle partagé.

Architecture du modèle

Omni a trois couches :

1. Schema Model — auto-généré à partir de votre base de données (lecture seule)
2. Shared Model — personnalisations de l'analytics engineer (dimensions, mesures, labels, topics, contexte IA)
3. Workbook Model — personnalisations par dashboard (ad-hoc, non partagées)

Lors de l'exploration, utilisez la vue combined pour voir tout ce qui est disponible.

Concepts clés

Les vues correspondent aux tables de base de données. Chacune a des dimensions (champs groupables) et des mesures (agrégations).

Les topics joignent les vues ensemble en unités interrogeables — points de départ curés pour l'analyse. Un topic a une vue de base, des vues jointes, des filtres par défaut et un contexte IA.

Les relations définissent les jointures : join_from_view, join_to_view, on_sql, relationship_type (one_to_one, many_to_one, one_to_many, many_to_many), et join_type (always_left, inner, full_outer).

Nommage des champs : view_name.field_name avec notation entre crochets pour la granularité temporelle : orders.created_at[week].

Motifs d'exploration

« Quelles données avons-nous sur X ? » — Lister les topics → inspecter celui le plus pertinent → examiner les vues et champs.

« Comment ces tables se rapportent-elles ? » — Inspecter le relationships[] du topic — vérifier join_from_view, join_to_view, on_sql, et relationship_type.

« Quelles mesures sont disponibles pour Y ? » — Inspecter le topic contenant la vue Y → examiner le tableau measures[] avec les définitions aggregate_type et sql.

Secours : Vue attendue manquante de yaml-get

Utilisez ce motif seulement quand l'exploration normale ne suffit pas — l'utilisateur nomme une vue spécifique et elle est absente de la réponse yaml-get ou get-topic, ou une relation référence une vue qui n'apparaît pas. Si yaml-get a retourné ce que vous attendiez, ignorez cette section.

Pourquoi c'arrive : yaml-get ne retourne que les vues des schémas actuellement chargés. Si un schéma est offloaded ou inactif, ses vues n'apparaîtront pas. L'appel get-schemas affiche tous les schémas que la connexion connaît — incluant les offloaded et inactifs — c'est donc l'étape logique suivante avant de dire à l'utilisateur « non trouvé ».

Récupération en deux étapes :

# 1. Lister chaque schéma (chargé, offloaded et inactif)
omni models get-schemas <modelId>
# → {"schemas": ["ANALYTICS", "PUBLIC", "STAGING", ...]}

# 2. Si le schéma cible est dans la liste, charger juste ce schéma
omni models yaml-get <modelId> --includeschemas PUBLIC

Si le schéma n'est pas du tout dans la liste, ce n'est pas un problème de lazy-load — la connexion n'a probablement pas accès ou le schéma n'est pas synchronisé. Vérifiez auprès d'un Connection Admin.

Règles pour --includeschemas :

• Accepte exactement un nom de schéma par appel — les virgules sont rejetées par l'API. Chargez les schémas un à la fois si vous en avez besoin de plusieurs.
• Quand défini, la réponse contient uniquement les vues appartenant à ce schéma. Les relations sont préservées même quand elles référencent des vues dans d'autres schémas.
• Pour limiter à une branche, ajoutez --branchid <id> à yaml-get ou --branch-id <id> à get-schemas (les noms des flags diffèrent par commande — cela correspond à la casse sous-jacente de l'API).

Champs calculés

Les champs calculés du modèle utilisent un format différent des dimensions/mesures régulières. La clé du champ est calc_name et la propriété expression est sql_expression — pas name/sql.

Analyse d'impact des champs

Évaluez le rayon d'impact d'une migration ou suppression de champ avant de pousser les changements vers dbt :

1. Créez une branche de modèle avec omni-model-builder où le champ est supprimé ou renommé
2. Lancez le validateur de contenu contre cette branche :

omni models content-validator-get <modelId> --branch-id <branchId>

Cela retourne tous les dashboards et tiles avec des références cassées au champ supprimé.

3. Cherchez le YAML du modèle pour des références supplémentaires (exécutez en parallèle avec l'étape 2) :

omni models yaml-get <modelId> --filename '.*'

Cherchez dans la réponse le nom du champ pour trouver les références dans d'autres vues, topics et champs calculés.

4. Rapport : Combinez les résultats du validateur de contenu (dashboards/tiles cassés) avec les résultats de la recherche YAML (références du modèle) dans un rapport structuré du rayon d'impact.

NE paginez PAS les documents et ne vérifiez pas les requêtes individuellement — le validateur de contenu fait cela pour vous en un appel.

Référence docs

• Models API · Topics API · Modeling Overview · Views · Topics · Dimensions · Measures
• List model schemas · Get model YAML

Skills connexes

• omni-model-builder — créer ou modifier des vues, topics et champs
• omni-query — exécuter des requêtes sur les champs découverts
• omni-ai-optimizer — inspecter et améliorer le contexte IA sur les topics