> For the complete documentation index, see [llms.txt](https://documentation.efalia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.efalia.com/connecteurs/connecteurs-generiques/cmis/api-query.md).

# Référence API Query

## Introduction

Le service **API Query** du connecteur CMIS Efalia Doc permet d'effectuer des recherches avancées sur les documents et dossiers stockés dans Efalia Doc via le protocole CMIS. Ce service expose une interface de recherche compatible avec de nombreux cas d'usage métier, avec une gestion spécifique des gabarits et des métadonnées.

## Fonctionnement général

L'API s'appuie sur la syntaxe SQL CMIS, avec les spécificités suivantes pour Efalia Doc :

* les requêtes s'expriment selon la structure `SELECT ... FROM ... WHERE ...` ;
* les recherches s'effectuent toujours sur la base des **identifiants externes** (gabarits et métadonnées) ;
* un contrôle renforcé est effectué entre les métadonnées et le gabarit cible.

## Syntaxe supportée

### Opérateurs logiques

* `AND`, `OR`
* Les clauses `WHERE` peuvent contenir des combinaisons logiques simples.

### Opérateurs de comparaison

* `=` (égalité stricte)
* `LIKE` (recherche de similarité, avec joker)
* `>` (supérieur à), `<` (inférieur à)
* `CONTAINS()` pour la recherche sur les métadonnées uniquement

## Utilisation du champ FROM

* **Obligatoire** : le champ `FROM` doit obligatoirement contenir l'**identifiant externe** du gabarit ciblé (dossier ou document).
* **Recherche multi-gabarits** : si `FROM` vaut `cmis:folder` ou `cmis:document`, la recherche s'applique sur **tous les gabarits du type concerné** (dossiers ou documents). Elle est alors exécutée récursivement sur chaque gabarit de la même armoire, et les résultats sont fusionnés dans la réponse.

## Gestion des métadonnées

Les métadonnées référencées dans le `WHERE` doivent exister pour le gabarit indiqué dans `FROM`.

{% hint style="info" %}
Si une métadonnée ne correspond pas au gabarit, une alerte est remontée — sauf en mode multi-gabarits, où ce comportement est normal (voir Limitations ci-dessous). Cette règle vise à garantir la cohérence des résultats et à éviter toute ambiguïté dans les recherches.
{% endhint %}

## Limitations et particularités

* **Recherches multi-gabarits** (`FROM` = `cmis:folder` ou `cmis:document`) : les erreurs de correspondance de métadonnées ne sont **pas remontées**, car il est attendu que certaines métadonnées ne soient pas présentes sur tous les gabarits. Ce mode permet de faire des recherches génériques sur tout un type de ressources.
* **Identifiants externes obligatoires** : pour les gabarits (`FROM`) et pour les métadonnées (dans `WHERE`), il faut toujours utiliser les identifiants externes, pas les libellés métiers ou techniques internes.
* **Opérateurs non supportés** : les opérateurs ou syntaxes non listés ci-dessus ne sont pas pris en charge à ce jour.
* **Bannettes** : il n'est pas possible de rechercher un document dans une bannette.
* **Recherche full texte** : il n'est actuellement pas possible de rechercher un document par son contenu via cette API.

## Exemple de requête

```
GET https://connectorhub-utilities.efalia.net/connecteurs/cmis/browser.php?repositoryId=ciril-cmis&cmisselector=query&statement=SELECT  FROM efalia:ciril-agent-contrat WHERE efalia:ciril-agent-contrat-type="CDP" OR efalia:ciril-agent-contrat-note LIKE "Avenant" AND efalia:ciril-agent-contrat-version = 45 AND CONTAINS (cmis:document, 'efalia:ciril-agent-contrat-description:\'ajout\'')&searchAllVersions=true&includeAllowableActions=true&includeRelationships=true&maxItems=10&skipCount=0
```

Explications :

* la clause `FROM` cible le gabarit `efalia:ciril-agent-contrat` ;
* plusieurs conditions sur les métadonnées, combinées par `AND`/`OR` ;
* recherche plein texte sur la description du contrat.

## Bonnes pratiques

* Vérifier les identifiants externes avant de formuler la requête.
* Pour des recherches sur plusieurs types, utiliser judicieusement `cmis:folder` ou `cmis:document`.
* Toujours analyser le retour pour détecter d'éventuelles alertes sur les métadonnées.

## FAQ

<details>

<summary>Puis-je utiliser des jointures CMIS ou des sous-requêtes ?</summary>

Non, seul le mode `SELECT ... FROM ... WHERE ...` avec les opérateurs supportés est pris en charge.

</details>

<details>

<summary>Comment obtenir la liste des gabarits disponibles et de leurs métadonnées ?</summary>

Cette API ne fournit pas ces informations ; il faut les récupérer via l'interface d'administration Efalia Doc.

</details>


---

# 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://documentation.efalia.com/connecteurs/connecteurs-generiques/cmis/api-query.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.