Cubes

Un cube est un fichier YAML qui modélise un ensemble de données dans la couche sémantique : sa table ou sa requête source, ses dimensions, ses mesures et ses jointures vers d’autres cubes.

Structure du fichier

# nom du cube : "orders"

# Source de données (exactement un de sql_table / sql)
sql_table: public.orders

# Métadonnées
title: Commandes
description: Une ligne par ligne de commande. Export du système ERP, actualisé chaque nuit.

dimensions: []
measures: []
joins: []

# Facultatif
segments: []
sql_alias: ord
extends: base_cube_name
meta: {}

Source de données

Exactement une des propriétés suivantes :

Propriété	Utilisation
sql_table	Référence directe à une table : sql_table: public.orders
sql	Une requête SQL personnalisée, pour des jointures, des filtres ou des transformations au niveau de la source

sql: |
  SELECT o.*, c.name AS customer_name
  FROM orders o
  LEFT JOIN customers c ON o.customer_id = c.id
  WHERE o.status != 'deleted'

Métadonnées

Propriété	Type	Description
title	chaîne	Nom d’affichage lisible.
description	chaîne	Notes destinées aux personnes qui maintiennent le modèle (provenance, granularité, cadence d’actualisation). N’atteint pas l’agent — pour du contexte destiné à l’agent, décrivez les dimensions et les mesures individuelles, qui se propagent dans chaque vue qui les inclut.
sql_alias	chaîne	Alias personnalisé du cube dans le SQL généré.
meta	objet	Métadonnées libres (étiquettes, propriétaire, …).

Dimensions

Attributs servant au regroupement et au filtrage.

dimensions:
  - name: id
    sql: id
    type: number
    primary_key: true

  - name: status
    sql: status
    type: string
    description: "'completed', 'pending' ou 'cancelled'. Les commandes de test internes utilisent 'draft'."

  - name: created_at
    sql: created_at
    type: time

  - name: customer_email
    sql: "{customers.email}"   # champ d'un cube joint
    type: string

Propriété	Description
name	Nom du champ (snake_case).
sql	Nom de colonne, expression SQL ou référence {joined_cube.field}.
type	string, number, time, boolean ou geo.
primary_key	Mettez true sur la clé primaire du cube (requis pour des jointures correctes).
description	Destinée à l’agent — se propage dans les vues. Consignez-y les conventions et les mises en garde propres au champ. Voir rédiger de bonnes descriptions.

Mesures

Métriques agrégées.

measures:
  - name: count
    type: count

  - name: total_revenue
    sql: amount
    type: sum
    description: Revenu brut en CAD, avant retours.

  - name: unique_customers
    sql: customer_id
    type: count_distinct

  - name: completed_revenue
    sql: "CASE WHEN {status} = 'completed' THEN {amount} ELSE 0 END"
    type: sum

type	Signification
count	Nombre de lignes
sum / avg / min / max	Agrégations standards sur sql
count_distinct	Nombre de valeurs uniques
number	Calcul SQL personnalisé (p. ex. des ratios d’autres mesures)

Jointures

Relations vers d’autres cubes, qui permettent les requêtes entre cubes et les chemins de jointure des vues.

joins:
  - name: customers
    sql: "{CUBE}.customer_id = {customers}.id"
    relationship: many_to_one

  - name: order_items
    sql: "{CUBE}.id = {order_items}.order_id"
    relationship: one_to_many

Propriété	Description
name	Le nom du cube joint.
sql	Condition de jointure. {CUBE} désigne le cube courant; {other_cube}, le cube joint.
relationship	many_to_one, one_to_many, one_to_one ou many_to_many (ce dernier via un cube intermédiaire).

Segments

Filtres nommés et réutilisables.

segments:
  - name: completed_orders
    sql: "{CUBE}.status = 'completed'"
  - name: high_value
    sql: "{CUBE}.amount > 1000"

Propriétés avancées

Propriété	Description
extends	Hérite de tout le contenu d’un autre cube, avec surcharge sélective.
access_policy	Règles d’accès au niveau des colonnes et des lignes. Voir politiques d’accès.

Conventions

• Noms de cubes et de champs en snake_case : customer_orders, total_revenue.
• Définissez toujours une dimension primary_key.