Tutoriel : Votre premier build

Dans ce tutoriel, vous allez créer un tenant, écrire un Signal, construire un Knowledge Store (KLS) et explorer les résultats dans le navigateur. Pas de domain pack nécessaire — vous construisez tout de zéro.

Durée : 15 minutes Prérequis : jinflow installé (Démarrage rapide)

1. Créer un tenant

Un tenant est votre espace de travail analytique — il contient vos données, instruments et sortie de build.

jinflow init --tenant my_first_analysis --source-system opale

Cela crée une structure de répertoires :

~/.jinflow/live/default/my_first_analysis/
  afs/        ← your instruments go here
  raw/        ← your source CSVs go here
  build/      ← intermediaries (managed by jinflow)
  store/      ← KLS output (managed by jinflow)

Définissez-le comme défaut pour ne pas devoir taper --tenant à chaque fois :

jinflow us --tenant default.my_first_analysis

2. Ajouter des données source

Placez des fichiers CSV dans le répertoire raw/. Pour ce tutoriel, créez un jeu de données minimal :

# Find your tenant's raw directory
jinflow us
# Look for "Live root" in the output, then navigate to:
# {live_root}/default/my_first_analysis/raw/opale/csv/

Créez un fichier cases.csv :

case_id,case_type,admission_date,discharge_date,cost_center_id,status
CASE_001,inpatient,2025-01-15,2025-01-20,CC_OR1,closed
CASE_002,outpatient,2025-01-16,,CC_ER,open
CASE_003,inpatient,2025-01-17,2025-01-25,CC_OR1,closed
CASE_004,day_case,2025-01-18,2025-01-18,CC_DAY,closed
CASE_005,inpatient,2025-01-19,2025-01-22,CC_OR2,closed

Et un fichier billing_events.csv :

billing_id,case_id,material_id,quantity,unit_price,billing_date,status
BILL_001,CASE_001,MAT_A,2,150.00,2025-01-20,posted
BILL_002,CASE_001,MAT_B,1,500.00,2025-01-20,posted
BILL_003,CASE_003,MAT_A,3,150.00,2025-01-25,posted
BILL_004,CASE_005,MAT_C,1,2000.00,2025-01-22,pending

Remarquez : CASE_002 et CASE_004 n’ont pas d’événements de facturation. C’est l’anomalie que votre Signal va détecter.

3. Écrire votre premier Signal

Créez un fichier dans votre AFS à afs/probes/probe_unbilled_cases.yaml :

probe_id: probe_unbilled_cases
version: "1.0.0"
contract: "gold.v1"
type: mandatory_item
severity: high
description: "Detect cases that have no billing events"

scope:
  entity_type: Case
  group_by: [case_id]
  time:
    entity: Case
    field: admission_date
    bucket: month

qualifying:
  entity: Case
  join_key: case_id

required:
  entity: BillingEvent
  join_key: case_id
  min_count: 1

money_at_risk_fixed: 500

Ce Signal dit : « Pour chaque cas, il devrait y avoir au moins un événement de facturation. Signaler ceux qui n’en ont pas. »

4. Construire

jinflow make

jinflow va :

1. Valider vos CSV
2. Compiler votre YAML de Signal en SQL
3. Exécuter dbt (Bronze → Silver → Gold → Signals)
4. Estampiller le KLS

Observez la sortie — vous devriez voir votre Signal être compilé et construit.

5. Explorer

jinflow explore

Cela ouvre l’Explorer dans votre navigateur à localhost:4000. Naviguez vers :

• Signals — vous verrez probe_unbilled_cases listé
• Findings — vous verrez des findings pour CASE_002 et CASE_004 (les cas non facturés), chacun avec severity high et money_at_risk 500

6. Itérer

Essayez maintenant de modifier votre Signal. Ouvrez afs/probes/probe_unbilled_cases.yaml et changez severity: high en severity: medium. Puis :

jinflow make

Rafraîchissez l’Explorer — les findings montrent maintenant une sévérité medium. C’est le cycle make → explore → evolve qui anime tout le travail jinflow.

7. Snapshot

Satisfait de votre analyse ? Figez-la :

jinflow make --snapshot first-analysis

Cela crée une copie immuable de votre KLS. Vous pouvez toujours y revenir :

jinflow explore --snapshot first-analysis

Ce que vous avez appris

• Un tenant est votre espace de travail analytique
• Les Signals sont des fichiers YAML qui définissent des requêtes diagnostiques
• jinflow make compile YAML → SQL → DuckDB
• jinflow explore sert les résultats dans une interface web
• Les snapshots figent votre travail pour référence future

Prochaines étapes

• Tutoriel : Du Finding au Verdict — écrire une Thesis et un Verdict
• Guide Instruments — tous les types d’instruments
• Référence YAML Signal — tous les champs et types de Signal
• Glossaire — chaque terme expliqué