Paramètres de recherche
=======================

Contenu HTTP
------------

LE contenu de l’appel d'un web-service de recherche doit être un json de recherche contenant les
deux propriétés operation et filtes.

Propriété operation
-------------------

La propriété operation ne peut prendre que les deux valeurs suivantes:

* INTERSECTION : les objets retournés vérifient l'ensemble des conditions;
* UNION : les objets retournés vérifient une des conditions.

Propriété filtres
-----------------

La propriété filtre est une liste non vide d'objets Filtre ou SousFiltre.

Objet Filtre
------------

L'objet Filtre contient les attributs suivants:

======== ===== =================================== =====
Attribut Type  Description                         O/F
======== ===== =================================== =====
filtre   str   attribut de l'objet à filter        O
valeur   mixed valeur simple ou tableau de valeurs O
inverse  bool  inverse le filtre                   F
strict   bool  recheche strict ou flou             F
======== ===== =================================== =====

Objet SousFiltre
----------------

Un objet SousFiltre permet de combiner un filtre principal avec un ou plusieurs filtres secondaires.

Les sous-filtres ne concerne que les rôles des entités.

Dans l'exemple suivant,

.. code-block:: json

   {
     "operation": "INTERSECTION",
     "filtres": [
       {
         "filtre": "RolContactSiteHydro",
         "sousfiltres": [
            {"CdSiteHydro": "F"},
            {"RoleContactSiteHydro": "ADM"}
         ]
       }
     ]
   }

le web-service de recherche de contributeurs va retourner les contact ayant des rôles ADM sur des
sites hydro dont le code commence par la lettre F.

Attribut valeur
---------------

Valeur simple
"""""""""""""

La valeur du filtre peut être une chaîne de caractères, un entier, un flottant un booléen ou un
tableau de valeur.
L'attribut peut prendre la valeur nulle (null).

Tableau de valeurs 
""""""""""""""""""

En fournissant un tableau de valeurs, l'opérateur de recherche est "un parmi".
Le web-service retournera les objets dont la propriété correspond à une des valeurs du tableau. 

Opérateurs SQL de recherche
---------------------------

======================== ====== ============= ========================================================
Type de paramètre        strict opérateur     Commentaire
======================== ====== ============= ========================================================
Texte                    false  ~\*           Recherche par expression régulière insensible à la casse
Texte                    true   ilike         Recherche strict **insensible** à la casse
Code d'entité                   ilike param % Commence par
Date                            >=
CdContact, Cdintervenant        =
======================== ====== ============= ========================================================

Attribut inverse
----------------

L’attribut inverse est un booléen qui peut prendre la valeur true ou false.

Lorsque inverse est égale true, cela inverse le filtre.

On peut utiliser deux fois la même balise pour réaliser des recherches
entre deux bornes min et max.

En utilisant les deux filtres ci-dessous, on pourra récupérer les sites
situés entre 50 et 100 mètres d’altitude.

.. code-block:: json

   {
     "operation": "INTERSECTION",
     "filtres": [
       {
         "filtre": "AltitudeSiteHydro",
         "valeur": 50,
         "inverse": false
       },
       {
         "filtre": "AltitudeSiteHydro",
         "valeur": 100,
         "inverse": true
       },
     ]
   }

Attribut strict
---------------

L’attribut strict est un booléen qui peut prendre la valeur true ou false.

Lorsque l’attribut prend la valeur true, une rechercher floue est
réalisé permettant de trouver des motifs à partir de texte mal
orthographié.

Exemple de substitution:

======= =====================================
Texte   Recherche floue
======= =====================================
Seine   ((s+)|ç)(e|é|è|ê)(i|î|ï)(n+)(e|é|è|ê)
Garonne (g|(gu))(a|à|â)(r+)(o|ô)(n+)(e|é|è|ê)
Loire   (l+)(o|ô)(i|î|ï)(r+)(e|é|è|ê)
======= =====================================

L'attribut strict ne concerne que les chaînes de caractères. Il ne s'applique pas aux entiers,
flottants, booléens, dates et codes.

Recherche de valeurs non définies
---------------------------------

Le web-service permet de filtrer sur des attributs non définis avec l'attribut valeur d'un objet
filtre défini à **null**.

.. code-block:: json

   {
     "operation": "INTERSECTION",
     "filtres": [
       {
         "filtre": "AltitudeSiteHydro",
         "valeur": null,
         "inverse": false
       }
     ]
   }

Dans l'exemple ci-dessous le web-service renverra les sites pour lesquels l’altitude n’est pas
définie.

Enfin il est possible de filtrer entre deux valeurs et en retournant aussi les entités pour
lesquelles la valeur n’a pas été définie :

.. code-block:: json

   {
     "operation": "INTERSECTION",
     "filtres": [
       {
         "filtre": "AltitudeSiteHydro",
         "valeur": [50, null],
         "inverse": false
       },
       {
         "filtre": "AltitudeSiteHydro",
         "valeur": 100,
         "inverse": true
       },
     ]
   }

L'exemple ci-dessus retournera les sites pour lesquels l’altitude n’a pas été définie ou comprise
entre 100 et 1000 mètres.
