# Champs relationnels

Trois types de champs connectent les tables et dérivent des données à partir de ces connexions. Ils forment une chaîne : une `relationship` définit le lien, puis `lookup` et `rollup` lisent ou agrègent les données à travers lui. (Le champ apparenté [`count`](/fr/docs/advanced-fields#count) — classé dans la catégorie Avancé — traverse également une relation.)

| Type           | Objectif                                                                       |
| -------------- | ------------------------------------------------------------------------------ |
| `relationship` | Crée un lien par clé étrangère vers une autre table. Fondation du reste.       |
| `lookup`       | Lit une valeur de champ unique depuis un enregistrement lié. En lecture seule. |
| `rollup`       | Agrège un champ sur de nombreux enregistrements liés (somme, moyenne, …).      |

## `relationship`

Crée un lien par clé étrangère vers une autre table.

| Propriété         | Description                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `relatedTable`    | **Requis.** Nom de la table cible à relier. Doit correspondre à une table existante.                                   |
| `relationType`    | Cardinalité. Par défaut `many-to-one`. Valeurs courantes : `one-to-one`, `many-to-one`, `one-to-many`, `many-to-many`. |
| `foreignKey`      | Nom personnalisé de la colonne de clé étrangère (utilisé pour `one-to-many`). Généré automatiquement lorsqu'omis.      |
| `displayField`    | Champ de la table liée affiché dans l'interface (par ex. `name` au lieu de l'identifiant brut).                        |
| `onDelete`        | Action référentielle lorsque la ligne liée est supprimée (par ex. `cascade`, `set-null`, `restrict`, `no-action`).     |
| `onUpdate`        | Action référentielle lorsque la clé primaire liée est mise à jour.                                                     |
| `reciprocalField` | Nom du champ pour le lien inverse (bidirectionnel) sur la table liée.                                                  |
| `allowMultiple`   | Booléen. Autorise la liaison à plusieurs enregistrements (par défaut `true` pour `many-to-many`).                      |
| `limitToView`     | Restreint les enregistrements liés sélectionnables à ceux visibles dans une vue nommée de la table liée.               |

```yaml
- id: 1
  name: customer
  type: relationship
  relatedTable: Customers
  relationType: many-to-one
  displayField: full_name
  onDelete: set-null
  reciprocalField: orders
```

## `lookup`

Affiche une valeur de champ tirée d'un enregistrement lié via une relation existante. En lecture seule et mis à jour automatiquement.

| Propriété           | Description                                                                            |
| ------------------- | -------------------------------------------------------------------------------------- |
| `relationshipField` | **Requis.** Nom du champ de relation à traverser (doit exister dans la même table).    |
| `relatedField`      | **Requis.** Champ de la table liée dont la valeur doit être affichée.                  |
| `filters`           | Expression de filtre optionnelle restreignant les enregistrements liés pris en compte. |

```yaml
- id: 2
  name: customer_email
  type: lookup
  relationshipField: customer
  relatedField: email
```

## `rollup`

Agrège des valeurs provenant de nombreux enregistrements liés.

| Propriété           | Description                                                                         |
| ------------------- | ----------------------------------------------------------------------------------- |
| `relationshipField` | **Requis.** Nom du champ de relation reliant à la table liée.                       |
| `relatedField`      | **Requis.** Champ de la table liée à agréger.                                       |
| `aggregation`       | **Requis.** Fonction d'agrégation (par ex. `SUM`, `AVG`, `MIN`, `MAX`, `COUNT`).    |
| `format`            | Format d'affichage du résultat agrégé (par ex. `currency`, `number`, `percentage`). |
| `filters`           | Filtre optionnel appliqué avant l'agrégation.                                       |

```yaml
- id: 3
  name: total_sales
  type: rollup
  relationshipField: orders
  relatedField: amount
  aggregation: SUM
  format: currency
```

:::callout
**La chaîne relationnelle.** Commencez par une `relationship` pour créer le lien, puis dérivez des données sans duplication : `orders → customer (relationship) → customer_email (lookup)`, ou agrégez avec `rollup`/`count`. Les champs `count`, `lookup` et `rollup` sont validés au moment de la configuration pour garantir que leur `relationshipField` référence un véritable champ `relationship` dans la même table.
:::

Voir [Relations](/fr/docs/table-relationships) pour un examen plus approfondi des cardinalités, des actions référentielles, des liens réciproques et de `displayField`.