> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solya.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingestion (technique)

> Le modèle de spécification d'ingestion, les statuts d'exécution et le flux de validation-puis-promotion du bac à sable.

Ceci est le compagnon technique des guides de [couche données](/fr/data-layer/overview).

<Note>
  Pour la référence **exhaustive, au niveau du champ** — chaque règle de détection, option
  de parsing et type de step de promotion avec ses paramètres et des exemples complets —
  voir [Specs d'ingestion (référence)](/fr/developers/ingestion-specs/overview).
</Note>

## Modèle de spécification d'ingestion

Une spécification d'ingestion décrit comment transformer un fichier entrant en modèle de Solya :

* **Détection** — comment le fichier est appairé : `FILENAME`, `COLUMNS`, `SHEET_NAME`,
  `FILENAME_MATCHES`, `HEADER_CONTAINS`, avec les modes d'appairage `ANY`, `ALL`, `COMPOSITE`.
* **Analyse** — comment les colonnes sont lues (types de champs, formats).
* **Promotion** — le pipeline de transformation. Les types d'étapes incluent `COERCE_TYPES`,
  `FILTER`, `DEDUPLICATE`, `ADD_COLUMN`, `RENAME_COLUMNS`, `SELECT_COLUMNS`,
  `DROP_COLUMNS`, `INJECT_VALUE`, `JOIN` / `SEQUENTIAL_JOIN` / `AGGREGATION_JOIN`,
  `UNPIVOT`, `TAXONOMY_MAPPING`, `ID_MAPPING_OUTPUT` / `ID_MAPPING_JOIN`, `GENERATE_ID`.
  Modes d'écriture : `MERGE`, `APPEND`, `OVERWRITE_PARTITION`.

Une spécification a un **statut** (`DRAFT`, `ACTIVE`, `DEPRECATED`, `ARCHIVED`), une **portée**
(`GLOBAL` ou `ORG`), une `priority` et un flag `isDeployed` (seules les spécifications déployées s'appliquent aux
fichiers en direct). Les spécifications sont versionnées.

```mermaid theme={null}
flowchart TB
  file["Fichier entrant"]
  detect["Détection<br/>(appairage de spec)"]
  parse["Analyse<br/>(lecture de colonnes)"]
  promote["Promotion<br/>(étapes de transformation)"]
  table["Table cible<br/>Silver/Gold"]
  
  file --> detect
  detect --> parse
  parse --> promote
  promote --> table
```

## Exécutions d'ingestion

Une exécution d'ingestion a le statut `PENDING → RUNNING → SUCCESS / FAILED`, un type de déclenchement
(`MANUAL`, `SCHEDULED`, `API`), un lien vers l'exécution Databricks sous-jacente et des
**logs** structurés à `DEBUG` / `INFO` / `WARN` / `ERROR` (plafonnés à 5000 entrées, 2000 caractères par
message). Elle enregistre `triggeredAt`, `startedAt` et `completedAt`.

## Bac à sable : valider puis promouvoir

Le [bac à sable](/fr/data-platform/sandbox) divise l'ingestion en deux exécutions tracées :

* **Exécution d'ingestion de bac à sable** — analyse et valide un fichier téléchargé dans des tables temporaires et
  émet des **conclusions** avec une **gravité** (`error` / `warning` / `info`) et une **étape**
  (detect, parse, map, loader, strict scan, quarantine). Statut
  `PENDING → RUNNING → SUCCESS / FAILED`.
* **Exécution de promotion de bac à sable** — copie les données validées dans la silver. Les mêmes statuts, plus un
  statut terminal **SUCCESS-mais-interrompue** (`stats.aborted = true`) quand l'ingestion avait
  des erreurs et la promotion-avec-erreurs n'était pas autorisée.

```mermaid theme={null}
stateDiagram-v2
  [*] --> PENDING
  PENDING --> RUNNING
  RUNNING --> SUCCESS
  RUNNING --> FAILED
  SUCCESS --> [*]
  FAILED --> [*]
```

Une **exécution de recommandation de spécification** profile un fichier téléchargé et propose une spécification plus des aperçus
par dataset (même ensemble de statuts).

## Enregistrements d'ingestion de fichiers

Les fichiers déposés dans la zone d'arrivée sont tracés avec un statut de `UPLOADED`, `INGESTED`,
`ERROR` ou `DELETED`, et une source de `APP` (upload d'interface utilisateur) ou `CLIENT_IMPORTER` (outil
d'importation externe).

<Note>
  Toutes les exécutions sont limitées à l'organisation et observables à partir de l'interface utilisateur et de l'API, avec le même
  modèle de logs structurés à travers les exécutions d'ingestion, bac à sable, tag et évaluation d'alertes.
</Note>