---
title: Récupérer une entité
slug: oip-next/BhLC-rechercher-des-entites
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-17T09:38:28.000Z
---

# Vue d'ensemble

Chaque entité dispose de trois fonctions pour la recherche :

- `$[EntityName]` : le type de retour est `null | T | T[]` ;
- `list[EntityName]` : le type de retour est `null | T[]` ;
- `get[EntityName]` : le type de retour est `null | T`.

# Recherche d'entités par leur type

```javascript
// Search for all `Project` entities
await $Project({}); // result is: null | T | T[]
await $Project({}, { list: true }); // result is: T[]
await listProject(); // result is: T[]

// Search for all `Company` entities linked to `project` entity
await $Company(project, {}); // result is: null | T | T[]
await $Company(project, {}, { list: true }); // result is: T[]
await listCompany(project); // result is: T[]
```

# Recherche d'entités par leur identifiant

```javascript
// Search for the `Project` entity with given id
await $Project(projectId); // result is: null | T
await getProject(projectId); // result is: null | T

// Search for the `Company` entity with given id
await $Company(project, companyId); // result is: null | T
await getCompany(project, companyId); // result is: null | T
```

# Recherche d'entités par des critères

:::BlockQuote
Il n'est pas possible de filtrer sur des propriétés chiffrées.
:::

## Recherche d'entités par des critères simples

```javascript
// Search for all `Project` entities
// having 'status' equals to 'created'
await $Project({ status: 'created' }); // result is: null | T | T[]
await listProject({ status: 'created' }); // result is: null | T | T[]

// Search for the `Project` entity
// having 'externalId' equals to '1234'
await getProject({ externalId: '1234' }); // result is: null | T

// Search for all `Company` entities linked to `project` entity
// having 'name' equals to 'foo'
await $Company(project, { name: 'foo' }); // result is: null | T | T[]
await listCompany(project, { name: 'foo' }); // result is: null | T | T[]

// Search for the `Company` entity linked to `project` entity
// having 'externalId' equals to '1234'
await getCompany(project, { externalId: '1234' }); // result is: null | T
```

## Recherche d'entités par des critères avancés

```javascript
// Search for all `Project` entities
// satisfying predicate: `$Project.key` != `value`
await $Project({ $search: { from: ['!=', 'key', value] } });

// Search for all `Project` entities
// satisfying predicate: `$Project.key` < `value`
await $Project({ $search: { from: ['<', 'key', value] } });

// Search for all `Project` entities
// satisfying predicate: `$Project.key` <= `value`
await $Project({ $search: { from: ['<=', 'key', value] } });

// Search for all `Project` entities
// satisfying predicate: `$Project.key` > `value`
await $Project({ $search: { from: ['>', 'key', value] } });

// Search for all `Project` entities
// satisfying predicate: `$Project.key` >= `value`
await $Project({ $search: { from: ['>=', 'key', value] } });

// Search for all `Project` entities
// satisfying predicate: `$Project.key` like `value`
await $Project({ $search: { from: ['~~', 'key', value] } });

// Search for all `Project` entities
// satisfying predicate: `$Project.key` like `value` (case ignored)
await $Project({ $search: { from: ['~~*', 'key', value] } });

// Search for all `Project` entities
// satisfying predicate: `$Project.key` not like `value`
await $Project({ $search: { from: ['!~~', 'key', value] } });

// Search for all `Project` entities
// satisfying predicate: `$Project.key` not like `value` (case ignored)
await $Project({ $search: { from: ['!~~*', 'key', value] } });

// Search for all `Project` entities
// satisfying predicate: `$Project.key` in `value`
await $Project({ $search: { from: ['in', 'key', value] } });

// Search for all `Project` entities
// satisfying predicate: `$Project.status` == `status_1` or `$Project.status` == `status_2` or `$Project.status` == `status_3`
// i.e. `$Project.status` is in ['status_1', 'status_2', 'status_3']
await $Project({ $search: { from: ['||', ['==', 'status', 'status_1'], ['==', 'status', 'status_2'], ['==', 'status', 'status_3']] } });

// Search for all `Project` entities
// satisfying predicate: `$Project.status` != `status_1` and `$Project.status` != `status_2` and `$Project.status` != `status_3`
// i.e. `$Project.status` is not in ['status_1', 'status_2', 'status_3']
await $Project({ $search: { from: ['&&', ['!=', 'status', 'status_1'], ['!=', 'status', 'status_2'], ['!=', 'status', 'status_3']] } });

// Search for all `Project` entities
// satisfying predicate: `$Project.key` != `value1` and `$Project.key` != `value2`
await $Project({ $search: { from: ['&&', ['!=', 'key', value1], ['!=', 'key', value2]] } });

// Search for all `Project` entities
// satisfying predicate: `$Project.key` != `value1` or `$Project.key` != `value2`
await $Project({ $search: { from: ['||', ['!=', 'key', value1], ['!=', 'key', value2]] } });

// Search for all `Company` entities
// satisfying predicate: `$Company.key` != `value`
await $Company(project, { $search: { from: ['!=', 'key', value] } });
```

L'expression pour `$search.from` est définie par :

```none
from_expr =
  | ['&&', from_expr]
  | ['||', from_expr]
  | [op, key, value]
```

### Opérateurs disponibles

Considérant l'expression `[op, 'key', value]`, `op` correspond à l'une des valeurs suivantes :

- `==` : la valeur de la propriété `key` est égale à `value` ;
- `!=` : la valeur de la propriété `key` est différente de `value` ;
- `<` : la valeur de la propriété `key` est strictement inférieure à `value` ;
- `<=` : la valeur de la propriété `key` est inférieure ou égale à `value` ;
- `>` : la valeur de la propriété `key` est strictement supérieure à `value` ;
- `>=` : la valeur de la propriété `key` est supérieure ou égale à `value` ;
- `~~` : la valeur de la propriété `key` correspond à l'expression régulière `value` ;
- `~~*` : la valeur de la propriété `key` correspond à l'expression régulière `value` (casse ignorée) ;
- `!~~` : la valeur de la propriété `key` ne correspond pas à l'expression régulière `value` ;
- `!~~*` : la valeur de la propriété `key` ne correspond pas à l'expression régulière `value` (casse ignorée) ;
- `in` : la valeur de la propriété `key` est égale à l'une des valeurs présentes dans la liste `value`.

## Recherche d'entités par des critères sur leurs sous-entités

:::BlockQuote
Ce type de recherche n'est disponible que pour l'entité racine `Project`.
:::

```javascript
// Search for all `Project` entities
// satisfying predicate: `$Project.status` == `status`
// and having a direct `Customer` entity satisfying predicate:
//   `$Customer.lastName` == `lastName`
await $Project({
  $search: {
    from: ['==', 'status', status],
    with: [['Customer'], [['==', 'lastName', lastName]]]
  }
});

// Search for all `Project` entities
// satisfying predicate: `$Project.status` == `status`
// and having a direct `Customer` entity satisfying predicate:
//   `$Customer.lastName` == `lastName`
//   and having a direct `Address` entity satisfying predicate:
//     `$Address.street` == `street`
await $Project({
  $search: {
    from: ['==', 'status', status],
    with: [['Customer', 'Address'], [['==', 'lastName', lastName], ['==', 'street', street]]]
  }
});

// Search for all `Project` entities
// having either a direct `Customer` entity satisfying predicate:
//   `$Customer.lastName` like `lastName` or
//   `$Customer.firstName` like `firstName` or
//   `$Customer.email` like `email`
// or a direct `Policy` entity satisfying predicate:
//   `$Policy.externalId` like `externalId`
await $Project({
  $search: {
    with: [
      '||',
      [['Customer'], [['||', ['~~', 'lastName', lastName], ['~~', 'firstName', firstName], ['~~', 'email', email]]]],
      [['Policy'], [['~~', 'externalId', externalId]]]
    ]
  }
});

// Search for all `Project` entities
// having either
//   a direct `Customer` entity satisfying predicate:
//     `$Customer.lastName` like `lastName` or
//     `$Customer.firstName` like `firstName` or
//     `$Customer.email` like `email`
//   and a direct `Grantee` entity satisfying predicate:
//     `$Grantee.lastName` == `lastName`
// or a direct `Policy` entity satisfying predicate:
//   `$Policy.externalId` like `externalId`
await $Project({
  $search: {
    with: [
      '||',
      [
        '&&',
        [['Customer'], [['||', ['~~', 'lastName', lastName], ['~~', 'firstName', firstName], ['~~', 'email', email]]]],
        [['Grantee'], [['==', 'lastName', lastName]]]
      ],
      [['Policy'], [['~~', 'externalId', externalId]]]
    ]
  }
});
```

L'expression pour `$search.with` est définie par :

```none
with_expr =
  | ['&&', with_expr]
  | ['||', with_expr]
  | [[path_expr], [from_expr]]
```

À noter que :

- `path_expr` est une liste de types d'entités ;
- `from_expr` est l'expression définie précédemment pour `$search.from` ;
- `path_expr` et `from_expr` doivent avoir le même nombre d'éléments.

### Tri selon des propriétés de sous-entités

La clé `orderBy` définit les critères de tri des résultats. Elle peut prendre l'une des formes suivantes :

```javascript
orderBy:
  | [field, order]
  | [path[], field, order]
  | [[path[], filter[][]], field, order]
```

- Le premier format correspond à un tri standard : le tri est effectué selon la propriété `field` de l'entité `Project` ;
- Le deuxième format permet de trier selon la propriété `field` d'une sous-entité de `Project`, accessible via le chemin défini par `path`.
- Le troisième format permet de trier selon la propriété `field` d'une sous-entité de `Project`, accessible via le chemin défini par `path`, après application des filtres définis par `filter`.
- La valeur de `order` indique le sens du tri : `asc` pour un tri croissant ou `desc` pour un tri décroissant.

```javascript
let project1 = await $Project();
project1 = setProjectExternalId('p1', project1);
project1 = await updateProject(project1);

let project2 = await $Project();
project2 = setProjectExternalId('p2', project2);
project2 = await updateProject(project2);

let project3 = await $Project();
project3 = setProjectExternalId('p3', project3);
project3 = await updateProject(project3);

let customer1 = await $Customer(project1);
customer1 = setCustomerLastName('Charlie', customer1);
await updateCustomer(customer1);

let customer2 = await $Customer(project2);
customer2 = setCustomerLastName('Alpha', customer2);
await updateCustomer(customer2);

let customer3 = await $Customer(project2);
customer3 = setCustomerLastName('Bravo', customer3);
await updateCustomer(customer3);

// `projects1` is [`project2`, `project3`, `project1`] 
const projects1 = await $Project({}, { orderBy: [['Customer'], 'lastName', 'asc'] });

// `projects2` is [`project2`, `project1`, `project3`]
// Only "Alpha" (linked to project2) matches the filter; the other
// project has a linked customer, but it doesn't match, so it's treated
// as unmatched and sorted last.
const projects2 = await $Project({}, { orderBy: [[['Customer'], [['~~*', 'lastName', '^A']]], 'lastName', 'asc'] });
```
