Omni Query

Exécutez des requêtes contre la couche sémantique d'Omni via l'Omni CLI. Omni traduit les sélections de champs en SQL optimisé — vous spécifiez ce que vous voulez (dimensions, mesures, filtres), pas comment l'obtenir.

Astuce : Utilisez d'abord omni-model-explorer si vous ne connaissez pas les topics et champs disponibles.

Prérequis

# 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
# S'il existe plusieurs profils, demandez à l'utilisateur lequel utiliser, puis changez :
omni config use <profile-name>

Vous avez également besoin d'un ID de modèle et de connaître les topics et champs disponibles.

Découvrir les Commandes

omni query --help              # Lister les opérations de requête
omni query run --help          # Afficher les flags pour exécuter une requête
omni ai --help                 # Génération de requête alimentée par l'IA

Astuce : 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 en cas de redirection).

Exécuter une Requête

Requête Basique

omni query run --body '{
  "query": {
    "modelId": "your-model-id",
    "table": "order_items",
    "fields": [
      "order_items.created_at[month]",
      "order_items.total_revenue"
    ],
    "limit": 100,
    "join_paths_from_topic_name": "order_items"
  }
}'

Paramètres de Requête

Nommage des Champs

Les champs utilisent view_name.field_name. Les champs de date supportent les crochets de cadre temporel :

users.created_at[date]      — Quotidien
users.created_at[week]      — Hebdomadaire
users.created_at[month]     — Mensuel
users.created_at[quarter]   — Trimestriel
users.created_at[year]      — Annuel

Tris

"sorts": [
  { "column_name": "order_items.total_revenue", "sort_descending": true }
]

Filtres

"filters": {
  "order_items.created_at": "last 90 days",
  "order_items.status": "complete",
  "users.state": "California,New York"
}

Expressions : "last 90 days", "this quarter", "2024-01-01 to 2024-12-31", "not California", "null", "not null", ">100", "between 10 and 100", "contains sales", "starts with A". Voir references/filter-expressions.md pour la référence complète de la syntaxe des expressions de filtre.

Pivots

{
  "query": {
    "fields": ["order_items.created_at[month]", "order_items.status", "order_items.count"],
    "pivots": ["order_items.status"],
    "join_paths_from_topic_name": "order_items"
  }
}

Gestion et Validation des Résultats

Réponse par défaut : table Apache Arrow codée en base64. Les résultats Arrow sont binaires — vous ne pouvez pas analyser les données de lignes individuelles à partir de la réponse brute. Pour vérifier qu'une requête a renvoyé des données, vérifiez summary.row_count dans la réponse.

Pour des résultats lisibles, demandez plutôt un CSV :

{ "query": { ... }, "resultType": "csv" }

Validation des Résultats

Chaque réponse de requête doit être vérifiée avant de faire confiance aux résultats ou de les présenter à l'utilisateur.

Vérifier les erreurs :

• Si la réponse contient une clé error, la requête a échoué. Causes courantes : mauvais nom de champ, chemin de jointure manquant, expression de filtre malformée, erreur de permission.
• Si la réponse contient remaining_job_ids, la requête est toujours en cours — interrogez avec omni query wait avant de vérifier les résultats.

Vérifier le nombre de lignes :

• summary.row_count == 0 — la requête n'a renvoyé aucune donnée. Cela peut être valide (p. ex., aucune donnée dans la plage du filtre) mais vaut la peine d'être signalé à l'utilisateur. Causes courantes : filtres trop restrictifs, mauvaise plage de dates, champ qui ne correspond à aucune ligne.
• summary.row_count égal à la limit que vous avez définie — les résultats peuvent être tronqués. Si l'utilisateur a besoin de données complètes, relancez avec une limite plus élevée ou null pour illimité.

Vérification ponctuelle des données avec CSV :

Quand l'exactitude est importante, demandez CSV et scannez la sortie :

omni query run --body '{
  "query": { ... },
  "resultType": "csv"
}'

Vérifiez que :

• Les en-têtes de colonne correspondent aux champs que vous avez demandés
• Les valeurs sont dans les plages attendues (p. ex., le revenu n'est pas négatif, les dates ne sont pas dans le futur)
• Les agrégations ont du sens (p. ex., un nombre ne retourne pas une somme)

Valider le comportement du filtre :

Si votre requête comprend des filtres, vérifiez qu'ils sont appliqués :

# Exécutez la même requête sans filtres
omni query run --body '{ "query": { ... (no filters) ... }, "resultType": "csv" }'

# Comparez les nombres de lignes — filtré doit être <= non filtré

Si les deux requêtes renvoient le même nombre de lignes, le filtre peut ne pas s'appliquer (mauvais nom de champ, expression non supportée, ou le bogue connu où les filtres booléens sont supprimés avec les pivots).

Liste de Contrôle de Validation

Décodage des Résultats Arrow

import base64, pyarrow as pa
arrow_bytes = base64.b64decode(response["data"])
reader = pa.ipc.open_stream(arrow_bytes)
df = reader.read_all().to_pandas()

Requêtes Longues

Si la réponse inclut remaining_job_ids, interrogez jusqu'à la fin :

omni query wait --jobids job-id-1,job-id-2

Exécuter des Requêtes à partir de Tableaux de Bord

Extrayez et relancez les requêtes qui alimentent les tableaux de bord existants :

# Récupérer toutes les requêtes d'un tableau de bord
omni documents get-queries <dashboardId>

# Exécuter en tant qu'utilisateur spécifique
omni query run --body '{ "query": { ... }, "userId": "user-uuid-here" }'

# Politique de cache (valeurs valides : Standard, SkipRequery, SkipCache)
omni query run --body '{ "query": { ... }, "cache": "SkipCache" }'

Génération de Requête Alimentée par l'IA

Au lieu de construire manuellement la requête JSON, vous pouvez décrire ce que vous voulez en langage naturel et laisser l'IA d'Omni générer la requête.

Générer une Requête (synchrone)

Le chemin le plus rapide — retourne une requête JSON générée de manière synchrone. Passez --run-query false pour obtenir uniquement la structure de la requête sans l'exécuter (par défaut exécute la requête).

# Générer uniquement la requête JSON (pas d'exécution)
omni ai generate-query your-model-id "Show me revenue by month" --run-query false

Réponse :

{
  "query": {
    "fields": ["order_items.created_at[month]", "order_items.total_revenue"],
    "table": "order_items",
    "filters": {},
    "sorts": [{"column_name": "order_items.created_at[month]", "sort_descending": false}],
    "limit": 500
  },
  "topic": "order_items",
  "error": null
}

# Générer et exécuter en un seul appel
omni ai generate-query your-model-id "Top 10 customers by lifetime spend"

Flags optionnels :

• --branch-id — tester contre une branche de modèle spécifique
• --current-topic-name — contraindre la sélection de topic à un topic spécifique

Sélectionner un Topic

Vérifiez quel topic l'IA sélectionnerait pour une question, sans générer une requête complète :

omni ai pick-topic your-model-id "How many users signed up last month?"

Requêtes Agentives (asynchrone)

Pour l'expérience Blobby complète — analyse multi-étapes, tool use, et sélection de topic comme l'IA l'aurait réellement en production. Ceci est asynchrone : soumettez un job, interrogez le statut, puis récupérez le résultat.

# 1. Soumettre un job
omni ai job-submit your-model-id "Analyze revenue trends and identify our fastest growing product category"
# → retourne { "jobId": "job-uuid", "conversationId": "conv-uuid" }

# 2. Interroger la fin (QUEUED → EXECUTING → COMPLETE)
omni ai job-status <jobId>

# 3. Récupérer le résultat
omni ai job-result <jobId>

Le résultat contient un tableau actions avec chaque étape que l'IA a prise — cherchez les actions avec type: "generate_query" pour extraire les requêtes générées. La réponse inclut également resultSummary avec l'interprétation narrative de l'IA.

Commandes de job supplémentaires :

• omni ai job-cancel <jobId> — annuler un job en cours d'exécution
• omni ai job-visualization <jobId> — obtenir la sortie de visualisation

Quand Utiliser Quelle Approche

Modèle d'Analyse Multi-Étapes

Pour l'analyse complexe, enchaînez les requêtes :

1. Requête large — comprendre la forme des données
2. Inspecter les résultats — identifier les segments ou motifs intéressants
3. Suivis ciblés — filtrer selon les découvertes
4. Synthétiser — combiner les résultats en une narration

Modèles de Requête Courants

Série Temporelle : champs + dimension de date + tri ascendant + filtre de date

Top N : champs + métrique + tri descendant + limite

Agrégation avec Ventilation : dimensions multiples + mesures multiples + tri descendant par métrique clé

Bogues Connus

• Le filtre IS_NOT_NULL génère IS NULL (bogue Omni signalé) — solution de contournement : inverser la logique du filtre ou utiliser la vue de base pour appliquer le filtre différemment.
• Les filtres booléens peuvent être silencieusement supprimés quand un tableau pivots est présent — si les filtres booléens ne s'appliquent pas, supprimez le pivot et testez à nouveau.

Lien vers les Résultats

Les requêtes sont éphémères — il n'y a pas d'URL persistante pour un résultat de requête. Pour donner à l'utilisateur un lien partageable :

• Pour les tableaux de bord existants : {OMNI_BASE_URL}/dashboards/{identifier} (l'identifier provient de la réponse de l'API de document)
• Pour une nouvelle analyse : Créez un document via omni-content-builder avec la requête comme queryPresentation, puis partagez {OMNI_BASE_URL}/dashboards/{identifier}

Référence de Documentation

• Query API · Running Document Queries · Querying Documentation · Filter Syntax

Compétences Associées

• omni-model-explorer — découvrir les champs et topics avant de faire des requêtes
• omni-content-explorer — trouver les tableaux de bord dont vous pouvez extraire les requêtes
• omni-content-builder — transformer les résultats de requête en tableaux de bord
• omni-ai-eval — benchmarker et tester la précision de la génération de requête par l'IA