> 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/connexions/api-ksaar/recherche-denregistrements-filtres-tri-et-pagination.md).

# Recherche d'enregistrements (filtres, tri et pagination)

`POST api.ksaar.co/v1/workflows/{id}/records/search` recherche les enregistrements d’un workflow à l’aide d’un **filtre JSON**, avec pagination et tri optionnels.

Cette route permet d’effectuer des recherches avancées avec des options de filtrage, de tri et de pagination des enregistrements.

## ⚙️ Paramètres de la requête <a href="#paramtres-de-la-requte" id="paramtres-de-la-requte"></a>

#### Paramètres

<table><thead><tr><th width="183.59765625">Paramètre</th><th width="185.8515625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>UUID</td><td>Identifiant de la table à interroger</td></tr></tbody></table>

#### En-têtes optionnels

| Header                   | Description                                          |
| ------------------------ | ---------------------------------------------------- |
| `x-ksaar-application-id` | Identifiant de l'application                         |
| `x-ksaar-version-id`     | Identifiant de la version (par défaut la production) |

## 📤 Corps de la requête

Le corps de la requête est composé de trois parties :

```json
{
  "filter": {},
  "pagination": {},
  "sort": {}
}
```

| Propriété    | Description              |
| ------------ | ------------------------ |
| `filter`     | Critères de recherche    |
| `pagination` | Pagination des résultats |
| `sort`       | Ordre de tri             |

## 🔍 Recherche / filtres

La propriété `filter` définit les critères de recherche.

Un filtre est construit sous forme d'arbre logique composé :

* de **groupes** (`and` / `or`)
* de **comparaison** sur les champs

### Filtre simple <a href="#filtre-simple" id="filtre-simple"></a>

Un filtre simple contient :

* `field` : le champ à filtrer.
* `operator` : l’opérateur de comparaison.
* `value` ou `ref` : l’opérande de comparaison en fonction de la comparaison souhaitée
  * `value` : la valeur à comparer, quand l’opérateur l’exige.
  * `ref` : une référence à un autre champ, quand la comparaison se fait entre deux champs.

#### Syntaxe de la propriété `field`

La propriété `field` indique le champ à utiliser pour la comparaison.

Vous pouvez utiliser :

* l'identifiant unique : `"field": "customer_name"`
* l'UUID du champ : `"field": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"`

{% hint style="info" %}
L'utilisation de l'UUID est recommandée lorsque vous souhaitez conserver une référence stable même si le champ est renommé dans Ksaar.
{% endhint %}

Exemple :

```json
{
  "filter": {
    "field": "txt_nom_contact",
    "operator": "equals",
    "value": "Dupont"
  }
}
```

Retourne les enregistrements dont le champ `txt_nom_contact` égal à `Dupont`.

**Champ lié**

Pour filtrer sur un champ lié, utilisez le chemin complet du champ.

Exemple :

```json
"field": ["lnk_client_commande","txt_nom_client"]
```

Ou avec des UUID :

```json
"field": ["f8e2a1b0-3c4d-5e6f-7890-abcdef123456","c9d8e7f6-a5b4-4321-9876-fedcba098765"]
```

On récupérera ainsi les enregistrements dont le nom du client de la commande associée correspond aux critères du filtre.

{% hint style="info" %}
Le chemin peut contenir jusqu’à 2 niveaux de liaison pour les champs liés. Au-delà, il est possible de passer par un champ formule.
{% endhint %}

**Champ plage de dates**

Pour les champs plage de dates et plage de dates et heures, on précise le type `inner` et la clé du sous-champ : `begin` ou `end`.

Exemple :

```json
"field" : [
    "vacationperiod",
    {
        "type": "inner",
        "key": "end"
    }
]
```

**Champs méta**

Certains champs système, comme `createdAt` et `updatedAt`, peuvent être utilisés dans les filtres et le tri .

Exemple :

```json
{
    "field": {
        "type": "meta",
        "key": "createdAt"
    }
}
```

#### Opérateurs disponibles <a href="#oprateurs-disponibles" id="oprateurs-disponibles"></a>

<table><thead><tr><th width="341.65234375">Opérateur</th><th width="373.67578125">Description</th></tr></thead><tbody><tr><td><code>null</code></td><td>Champ vide / non renseigné</td></tr><tr><td><code>not_null</code></td><td>Champ renseigné</td></tr><tr><td><code>equals</code></td><td>Égalité</td></tr><tr><td><code>not_equals</code></td><td>Différent</td></tr><tr><td><code>greater_than</code></td><td>Strictement supérieur</td></tr><tr><td><code>greater_than_equals</code></td><td>Supérieur ou égal</td></tr><tr><td><code>lower_than</code></td><td>Strictement inférieur</td></tr><tr><td><code>lower_than_equals</code></td><td>Inférieur ou égal</td></tr><tr><td><code>in_period</code></td><td>Dans une période (dates)</td></tr><tr><td><code>is_contained</code></td><td>Contenu dans</td></tr><tr><td><code>includes</code></td><td>Contient</td></tr><tr><td><code>excludes</code></td><td>Ne contient pas</td></tr><tr><td><code>intersects</code></td><td>Au moins une valeur en commun</td></tr></tbody></table>

#### Valeurs de comparaison <a href="#valeurs-de-filtre" id="valeurs-de-filtre"></a>

La valeur dépend de l’opérateur et du type de champ .

**Valeur simple**

Pour la plupart des opérateurs, `value` est une valeur directe.

Exemple :

```json
{
  "filter": {
    "field": "status",
    "operator": "equals",
    "value": "open"
  }
}
```

Types acceptés :

* string
* number
* boolean
* date ISO

**Valeur de type liste**

Certains opérateurs acceptent une liste de valeurs.

Une liste est **obligatoire** pour `intersects`.\
Elle est également **possible** pour `includes` et `excludes` lorsque le champ est un champ Multi-Select ou Liaisons Multiples.

Exemple :

```json
{
  "filter": {
    "field": "tags",
    "operator": "includes",
    "value": ["vip", "premium"]
  }
}
```

**Valeur de type période**

Pour `in_period`, la valeur peut être :

* une période prédéfinie : `thisWeek`, `lastWeek`, `thisMonth`, `lastMonth`, `nextWeek`, `thisQuarter`, `lastQuarter`, `thisYear`, `lastYear`, `nextYear` .
* une plage de dates :

```json
"value": {
    "type": "dateRange",
    "begin": "2025-01-01",
    "end": "2025-03-31"
}
```

#### **Comparer deux champs** <a href="#comparer-deux-champs" id="comparer-deux-champs"></a>

La propriété `ref` permet de comparer un champ à un autre champ du même enregistrement.

Exemple :

```json
{
  "filter": {
    "field": "order_amount",
    "operator": "greater_than",
    "ref": {
      "type": "field",
      "field": "quote_amount"
    }
  }
}
```

Retourne les enregistrements dont le montant de commande est supérieur au montant du devis.

{% hint style="info" %}
`value` et `ref` ne peuvent pas être utilisés simultanément.
{% endhint %}

#### Combiner plusieurs filtres <a href="#combiner-plusieurs-filtres" id="combiner-plusieurs-filtres"></a>

Pour construire des filtres complexes, utilisez un groupe de filtres avec `logic` et `group` :

* `logic` : opérateur logique entre les filtres (**ET** / **OU**)
* `group` : liste de filtres composant le groupe

<details>

<summary>Exemple : AND - Tous les filtres doivent être vrais.</summary>

```json
{
  "filter": {
    "logic": "and",
    "group": [
      {
        "field": "status",
        "operator": "equals",
        "value": "open"
      },
      {
        "field": "archived_at",
        "operator": "null"
      }
    ]
  }
}
```

</details>

<details>

<summary>Exemple : OR - Au moins un filtre doit être vrai.</summary>

```json
{
  "filter": {
    "logic": "or",
    "group": [
      {
        "field": "tags",
        "operator": "includes",
        "value": "vip"
      },
      {
        "field": "tags",
        "operator": "includes",
        "value": "premium"
      }
    ]
  }
}
```

</details>

#### Groupes imbriqués <a href="#groupes-imbriqus" id="groupes-imbriqus"></a>

Les groupes peuvent être imbriqués afin de construire des conditions plus avancées.

L'exemple suivant recherche :

* les enregistrements dont le statut est `open` **ou** la priorité est `high`
* **et** créés après le 1er janvier 2024

```json
{
  "logic": "and",
  "group": [
    {
      "logic": "or",
      "group": [
        {
          "field": "status",
          "operator": "equals",
          "value": "open"
        },
        {
          "field": "priority",
          "operator": "equals",
          "value": "high"
        }
      ]
    },
    {
      "field": {
        "type": "meta",
        "key": "createdAt"
      },
      "operator": "greater_than",
      "value": "2024-01-01"
    }
  ]
}
```

## 📄 Pagination <a href="#pagination" id="pagination"></a>

La pagination permet de limiter le nombre de résultats retournés.

```json
{
  "pagination": {
    "page": 2,
    "limit": 50
  }
}
```

### Paramètres

| Champ   | Type    | Défaut | Description                  |
| ------- | ------- | ------ | ---------------------------- |
| `page`  | integer | `1`    | Numéro de page               |
| `limit` | integer | `100`  | Nombre de résultats par page |

{% hint style="info" %}
La propriété `pagination` est optionnelle. Si elle n'est pas renseignée, les valeurs par défaut sont appliquées.
{% endhint %}

### Contraintes

* `page >= 1`
* `limit >= 1`
* `limit <= 500`

## ↕️ Tri <a href="#tri" id="tri"></a>

Le tri est configuré avec la propriété `sort`.

```json
{
  "sort": {
    "field": "customer_name",
    "direction": "asc"
  }
}
```

| Champ       | Type            | Défaut      | Description                    |
| ----------- | --------------- | ----------- | ------------------------------ |
| `field`     | Field Reference | `createdAt` | Champ utilisé pour le tri      |
| `direction` | string          | `asc`       | Ordre de tri (`asc` ou `desc`) |

La propriété `field` utilise la même syntaxe que celle décrite dans la section Filtres.

{% hint style="info" %}
La propriété `sort` est optionnelle. Si elle n'est pas renseignée, les valeurs par défaut sont appliquées.
{% endhint %}

## 📦 Réponse

La route retourne un résultat paginé :&#x20;

```json
{
  "total": 42,
  "lastPage": 5,
  "currentPage": 2,
  "results": [
    {
      "id": "...",
      "customer_name": "Ksaar",
      "createdAt": "2025-03-15T10:00:00.000Z"
    }
  ]
}
```

### Propriétés

| Champ         | Description                                            |
| ------------- | ------------------------------------------------------ |
| `total`       | Nombre total d'enregistrements correspondant au filtre |
| `lastPage`    | Dernière page disponible                               |
| `currentPage` | Page retournée                                         |
| `results`     | Enregistrements de la page courante                    |


---

# 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/connexions/api-ksaar/recherche-denregistrements-filtres-tri-et-pagination.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.