> 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

Syntaxe de requête supportée par le service API Query du connecteur CMIS Efalia Doc.

## 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://documentation.efalia.com/connecteurs/connecteurs-generiques/cmis/api-query.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
