> ## 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.

# Spécifications d'ingestion — analyse

> Types et options de parser, mapping de colonnes, traitement des champs supplémentaires et validation.

L'**analyse** transforme le fichier brut en table typée. Elle a quatre parties :

```json theme={null}
"parsing": {
  "parser": { /* comment lire le fichier */ },
  "mapping": { /* colonne source -> champ cible + type */ },
  "extra_fields": { /* que faire avec les colonnes non mappées */ },
  "validation": { /* colonnes obligatoires, lignes min */ }
}
```

## Parser

L'objet `parser` sélectionne un lecteur (`type`) et le configure.

| `type`        | Pour                                |
| ------------- | ----------------------------------- |
| `csv`         | CSV / texte délimité                |
| `excel`       | Classeurs Excel                     |
| `polaris_sav` | Archives de dump SQL Polaris `.sav` |

### Options communes

| Champ              | Signification                                                          |
| ------------------ | ---------------------------------------------------------------------- |
| `header_row`       | Ligne indexée à 0 contenant les noms de colonnes (par défaut `0`).     |
| `skip_rows`        | Lignes à ignorer avant l'en-tête.                                      |
| `max_rows`         | Limite sur les lignes analysées (`null` = pas de limite).              |
| `strip_columns`    | Colonnes à supprimer (par tableau d'index, ou `true` pour toutes).     |
| `supports_reparse` | Indique si le fichier peut être ré-analysé après l'ingestion initiale. |

### Options CSV

`encoding` (ex. `utf-8`, `iso-8859-1`), `delimiter` (`,`, `;`, `\t`, `|`…), `has_header`.

### Options Excel

`sheet_names` (tableau, ou `null` pour toutes les feuilles), plus **`section_context`** pour les fichiers où les données sont groupées sous des en-têtes de sections :

```json theme={null}
"section_context": [
  { "label": "Magasin", "output_column": "_section_magasin" },
  { "label": "Poste",   "output_column": "_section_poste" }
]
```

Chaque valeur d'en-tête de section reconnue est reportée sur les lignes en dessous, dans la colonne de sortie nommée.

### Options SAV (Polaris)

`sql_filename` (chemin vers le dump SQL dans l'archive, ex. `0-full.sql`), `tables` (noms de table à extraire), `extract_media` (extraire les ressources binaires).

## Mapping de colonnes

`mapping.columns` mappe chaque colonne **source** à un champ **cible** et un type Spark SQL :

```json theme={null}
"mapping": {
  "columns": {
    "Numéro":        { "target": "ticket_number", "type": "STRING" },
    "Montant":       { "target": "amount",         "type": "DOUBLE" },
    "Date":          { "target": "payment_date",   "type": "STRING" }
  }
}
```

`type` est n'importe quel type Spark SQL (une chaîne libre, pas un enum figé). Valeurs
courantes : `STRING`, `INT`, `LONG`, `DOUBLE`, `TIMESTAMP`.

## Champs supplémentaires

Les colonnes non mappées sont traitées par `extra_fields.mode` :

| Mode          | Comportement                                            |
| ------------- | ------------------------------------------------------- |
| `ignore`      | Supprimer les colonnes non mappées.                     |
| `passthrough` | Les conserver telles quelles.                           |
| `collect`     | Les rassembler dans une liste dans `target_column`.     |
| `store_json`  | Les stocker en tant qu'objet JSON dans `target_column`. |

```json theme={null}
"extra_fields": { "mode": "store_json", "target_column": "_extra_fields" }
```

## Validation

Garde-fous appliqués après l'analyse :

```json theme={null}
"validation": {
  "required_columns": ["ticket_number", "payment_method"],
  "min_rows": 1
}
```

* `required_columns` — doivent être présentes et non nulles.
* `min_rows` — nombre de lignes minimum.

<Note>
  Les colonnes analysées s'écoulent ensuite dans le [pipeline de promotion](/fr/developers/ingestion-specs/promotion-steps),
  où elles sont transformées et écrites dans silver/gold.
</Note>