> For the complete documentation index, see [llms.txt](https://ksaar.gitbook.io/ksaar-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ksaar.gitbook.io/ksaar-documentation/les-elements/les-formules.md).

# Les Formules

Une formule est une expression qui effectue des calculs sur des valeurs dans votre base de données. Elle peut être aussi simple que l'addition de deux nombres ou aussi complexe que la transformation de plusieurs champs de données selon des critères spécifiques.

La création d'une formule se fait depuis une page d'un **Workflow** ou d'un **Suivi**. Cela peut aussi se faire directement dans une table depuis la vue Data.<br>

<div><figure><img src="/files/laPKPPqdPtdFdhY2b3g4" alt="" width="354"><figcaption><p>Ajouter une formule depuis un workflow ou suivi</p></figcaption></figure> <figure><img src="/files/snKRbEKf30CjDV4bcdtA" alt="" width="252"><figcaption><p>Ajouter une formule depuis la vue Data</p></figcaption></figure></div>

<figure><img src="/files/FBE1hcmvLQqgbcx09RKU" alt=""><figcaption><p>Éditeur de formule</p></figcaption></figure>

### ⬅️ Type de retour

Chaque formule a un type de retour, par exemple la formule `UPPER("hello")` renvoie un texte, et peut alors être utilisée partout où ce type le permet, que ce soit dans les filtres, les conditions ou dans des mises à jour de champs.

{% hint style="warning" %}
Vous devez choisir le type de retour la première fois que vous éditez votre formule et vous ne pourrez plus le changer par la suite.
{% endhint %}

Voici la liste exhaustive des types de retour pouvant être utilisés :&#x20;

* 🔤 **Texte**
* 🔢 **Nombre**
* 📆 **Date** & **Date et heure**
* 🗓️ **Plage de dates** & **Plages de dates avec heure**
* 🎨 **Couleur**
* **⚖️ Booléen**
* 🧾 **JSON**
* 📧 **Email**
* 💻 **HTML**
* Les retours de type “liaisons calculées” doivent retourner un identifiant, sélectionnable depuis les métadonnées :&#x20;
  * 🔗 **Liaison simple**
  * 🔗🔗 **Liaisons multiples**
  * 🙏 **Liaison utilisateur**

{% hint style="info" %}
À noter que pour les types de retour liaison simple et liaisons multiples, il vous sera demandé de spécifier la table liée à la formule ainsi que le champ à afficher dans la vue Data
{% endhint %}

#### 🤓 Focus syntaxe : Formules HTML

Pour une formule de type HTML, il faut surcharger les guillemets du code HTML par des apostrophes et inversement (surcharger des apostrophes par des guillemets). Ceci permet de ne pas interférer avec la syntaxe de la formule et de conserver un code HTML fonctionnel.

Voici des exemples de syntaxe correcte :&#x20;

```
"<p style='color:red;'>" & {nom} & "</p>"
```

Ou

```
'<p style="color:red;">' & {nom} & '</p>'
```

### 🛑 Gestion des erreurs

* **Vérification de la syntaxe** : L'éditeur des formules s'assure de la justesse syntaxique de votre expression. Si la formule est incorrecte, comme dans le cas d'une parenthèse manquante, cela vous sera signalé et elle ne sera pas sauvegardée.
* **Erreurs à l'exécution** : Si une formule génère une erreur lors de son exécution (par exemple si on a  `2 ^ "hello"`), elle retournera une valeur nulle et sera traitée de cette manière.

### ≠ Différence avec les formules de texte

Contrairement aux formules de texte, les formules permettent de manipuler tout type de champs, il est alors nécessaire de placer les variables dans des fonctions ou d'utiliser des opérateurs.

Par exemple, `Utilisateur : {Prénom} {Nom}` dans une formule de texte devient `"Utilisateur : " & {Prénom} & " " & {Nom}` dans une formule.

### 🔗 🔗 Liaisons multiples dans les formules

Il est possible d'utiliser un champ issu d'une **liaison multiple** dans les formules. En passant par une **liaisons multiple**, on obtient la liste des valeurs des enregistrements liés pour le champ choisi, qui peut être manipulé avec les fonctions sur les listes.

Par exemple, `{Liaisons multiples -> Nombre}` peut donner `[5,2,3,2,4]` s'il y a 5 enregistrements dans la liaison, avec ces valeurs pour le champ Nombre.\
Donc `SUM({Liaisons multiples -> Nombre})` donne ici `16`, la somme des nombres des enregistrements qui sont dans cette **liaison multiple**.

{% hint style="info" %}
Depuis une liaison multiple, il n’est pas possible d’aller sélectionner des variables au delà du premier niveau de liaison&#x20;
{% endhint %}

### 🧱 Les littéraux

Les littéraux sont des valeurs écrites en dur dans une formule, par opposition à des champs ou des variables dynamiques. Ces éléments sont importants car chaque fonction Ksaar attend un littéral d'un certain type.

**Les différents types de littéraux possibles avec exemples :**&#x20;

* Texte : `"Bonjour"` ou `"2025"`
* Nombre : `42`, `3.14`
* Booléen : `true`, `false`
* Liste : `[1, 2, 3]`, `["pomme", "banane"]`
* Objet : `{nom: "Jean", age: 30}`
* Objet tableau : `{Liaison multiple -> ville}`

### 🚧 Cas d’usage : Liaisons Calculées

Une table Élève contient une liaison simple vers les enregistrements d’une table Classe. Cette table Classe contient une liaison simple vers une table Niveau.

<figure><img src="/files/Xs8AithXSIU4JZhI2Op1" alt=""><figcaption><p>Graphique des tables</p></figcaption></figure>

On voudrait conditionner l’affichage d’une ligne en fonction du Niveau auquel les enregistrements de notre table Élève appartiennent.

Pour ce faire, on ajoute un champ Formule de type Liaison Simple dans la table Élève. Cette formule passe par les deux niveaux de liaisons et vient récupérer l’identifiant de l’enregistrement lié :&#x20;

<figure><img src="/files/PUtgxKPMbvdN0WAH0Hby" alt="" width="536"><figcaption><p>Variables à sélectionner dans la formule</p></figcaption></figure>

On lie donc notre formule à la table Niveau et le champ à afficher au nom du Niveau.

Dans les conditions d’affichage de la ligne, il est maintenant possible d’aller chercher le nom du Niveau de l’enregistrement en cours de la table Élève.

<figure><img src="/files/6I81xyNQSFGvYpFI0xYX" alt=""><figcaption><p>Condition d’affichage de la ligne</p></figcaption></figure>

### 📖 Fonctions disponibles dans les formules

{% hint style="success" %}
Les fonctions sur les formules sont disponibles dans chacune des sous-pages dédiées :&#x20;

* [Opérateurs](/ksaar-documentation/les-elements/les-formules/operateurs.md)
* [Fonctions de texte](/ksaar-documentation/les-elements/les-formules/fonctions-de-texte.md)
* [Fonctions mathématiques](/ksaar-documentation/les-elements/les-formules/fonctions-mathematiques.md)
* [Fonctions de date](/ksaar-documentation/les-elements/les-formules/fonctions-de-date.md)
* [Fonctions de formatage](/ksaar-documentation/les-elements/les-formules/fonctions-de-formatage.md)
* [Fonctions de liste](/ksaar-documentation/les-elements/les-formules/fonctions-de-liste.md)
* [Fonctions sur des champs Ksaar](/ksaar-documentation/les-elements/les-formules/fonctions-sur-des-champs-ksaar.md)
* [Fonctions de Logique et autres](/ksaar-documentation/les-elements/les-formules/fonctions-de-logique-et-autres.md)

Des exemples de formules prêtes à l'emploi se trouvent ici : [Bibliothèque de formules classiques](/ksaar-documentation/les-elements/les-formules/bibliotheque-de-formules-classiques.md)
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ksaar.gitbook.io/ksaar-documentation/les-elements/les-formules.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
