Configuration — noria.yml

Le fichier noria.yml est la configuration centrale de tout projet Noria. Il décrit la base de données, les paramètres globaux, et l'ensemble des tâches du pipeline.

Structure complète

name: mon_pipeline                  # (requis) identifiant du pipeline
description: "Description courte"  # (optionnel)
version: "1"                        # (optionnel) version du pipeline

database:
  dialect: duckdb                   # duckdb | postgresql | bigquery
  database: data/warehouse.db       # chemin fichier (DuckDB) ou nom BDD
  host: localhost                   # PostgreSQL / BigQuery
  port: 5432
  user: mon_user
  password: "${DB_PASSWORD}"        # supporte ${ENV_VAR}
  schema: mon_schema

params:
  schema: main
  env: prod
  annee: 2024

params_file: params/prod.yml        # fichier YAML de params supplémentaires
macros_dir: sql/macros              # répertoire des macros Jinja2 utilisateur
sql_dir: sql                        # répertoire des fichiers SQL
tracking_db: .noria/tracking.db    # base SQLite de suivi des exécutions

monitoring:
  enabled: false
  host: 127.0.0.1
  port: 7070
  auto_open: false

notifications:
  on_failure:
    - "https://hooks.slack.com/services/xxx"
    - "email:ops@mycompany.com"
  on_success: []
  timeout_s: 10

nodes:
  nom_tache:
    # ... voir référence des tâches ci-dessous

Section `database`

Champ	Type	Défaut	Description
`dialect`	string	`duckdb`	Moteur : `duckdb`, `postgresql`, `bigquery`
`database`	string	`:memory:`	Chemin fichier DuckDB, nom BDD PostgreSQL, ou project ID BigQuery
`host`	string	—	Hôte PostgreSQL
`port`	int	—	Port (défaut PostgreSQL : 5432)
`user`	string	—	Utilisateur
`password`	string	—	Mot de passe — utiliser `${ENV_VAR}` ou `.noria/.env`
`schema`	string	—	Schéma par défaut

Section `params`

Paramètres globaux accessibles dans tous les fichiers SQL via {{ params.nom }} ou directement {{ nom }}.

params:
  schema: main
  env: prod
  date_debut: "2024-01-01"

SELECT * FROM {{ params.schema }}.commandes
WHERE date_op >= '{{ params.date_debut }}'

Priorité des paramètres (du plus faible au plus fort)

params: dans noria.yml
params_file: (fichier YAML externe)
params: au niveau de la tâche
--param k=v en CLI
--params-file fichier.yml en CLI

Champs d'une tâche

Identification

Champ	Type	Défaut	Description
`type`	string	`sql`	Type : `sql`, `assert`, `seed`
`sql`	string	—	Chemin du fichier SQL
`target`	string	—	Table cible `schema.table` (Jinja2 compilé)
`description`	string	—	Description de la tâche
`active`	bool	`true`	Désactiver sans supprimer
`tags`	list	`[]`	Tags pour filtrage CLI (`--only-tags`)

Chargement

Champ	Type	Défaut	Description
`output_write`	string	`replace`	Stratégie d'écriture (voir Modes d'écriture)
`merge_key`	list	—	Clés pour `merge`
`incremental_key`	string	—	Colonne de partition pour `incremental`
`safe_replace_min_rows`	int	`1`	Seuil minimum de lignes pour `safe_replace`
`scd2_key`	list	—	Clé métier pour `scd2`
`update_key`	list	—	Clés de recherche pour `update`
`update_cols`	list	—	Colonnes à mettre à jour (toutes si absent)

Resilience

Champ	Type	Défaut	Description
`retry`	int	`0`	Nombre de réessais
`retry_delay_s`	float	`0.0`	Secondes entre les réessais
`timeout`	int	—	Timeout en secondes
`soft_fail`	bool	`false`	Ne pas bloquer le pipeline si échec
`always_run`	bool	`false`	Exécuter même si une dépendance a échoué

Dépendances

Champ	Type	Défaut	Description
`needs`	list	`[]`	Tâches qui doivent terminer avant celle-ci
`params`	dict	`{}`	Paramètres locaux (surchargent les params globaux)

Hooks

pre_hook:
  file: sql/hooks/avant.sql
  soft_fail: false   # true = log l'erreur mais continue
post_hook:
  file: sql/hooks/apres.sql
  soft_fail: true

Seeds

Champ	Type	Défaut	Description
`seed_file`	string	—	Chemin du fichier (CSV, Parquet, JSON)
`seed_delimiter`	string	`,`	Séparateur CSV
`seed_encoding`	string	`utf-8`	Encodage
`seed_null_value`	string	`""`	Valeur considérée comme NULL

Freshness check

freshness_check:
  column: updated_at   # colonne timestamp
  max_hours: 24        # échoue si plus vieux que 24h

Variables d'environnement

Les valeurs ${NOM_VAR} sont résolues depuis .noria/.env (auto-chargé) puis le shell.

# .noria/.env  (non versionné — ajoutez-le à .gitignore)
DB_PASSWORD=mon_mot_de_passe
SLACK_WEBHOOK=https://hooks.slack.com/services/xxx

database:
  password: "${DB_PASSWORD}"
notifications:
  on_failure:
    - "${SLACK_WEBHOOK}"

Exemple complet

name: pipeline_ventes
description: "Pipeline de reporting des ventes"
version: "2"

database:
  dialect: duckdb
  database: data/ventes.db

params:
  schema: main
  schema_raw: staging
  annee: 2024

params_file: params/prod.yml

notifications:
  on_failure:
    - "${SLACK_WEBHOOK}"

nodes:
  ref_products:
    type: seed
    seed_file: data/produits.csv
    target: "{{ params.schema }}.ref_products"
    description: "Référentiel produits"
    tags: [ref]

  commandes:
    sql: sql/commandes.sql
    target: "{{ params.schema }}.commandes"
    output_write: incremental
    incremental_key: date_commande
    description: "Commandes {{ params.annee }}"
    tags: [daily]
    retry: 2
    retry_delay_s: 30
    timeout: 600
    needs: [ref_products]

  monthly_stats:
    sql: sql/monthly_stats.sql
    target: "{{ params.schema }}.monthly_stats"
    output_write: replace
    description: "Statistiques par mois"
    tags: [daily, reporting]
    needs: [commandes]

  assert_stats:
    type: assert
    sql: sql/assert_stats.sql
    description: "Vérifie que les stats sont alimentées"
    needs: [monthly_stats]