Voir la source de JDONREFv4 Query

La requête jdonrefv4 du [[JDONREFv4_Plugin|plugin]] éponyme permet de chercher efficacement des adresses correspondant aux [[JDONREFv4_Types|types]] de JDONREFv4.

===== Requête et résultat =====

  {
    "query": {
      "jdonrefv4" : {
         "value" : "24 BOULEVARD DE L HOPITAL 75 PARIS"
      }
    }
  }

Les résultats de la requête dépendent de la [[Jdonrefv3es_plugin_configuration|configuration]] du plugin.

En version 0.1beta, l'attribut sur lequel doit porter la recherche est "fullName".

En version 0.2, de nombreux champs sont utilisés (tous ceux qui sont indexés). Avec une requête POST du type :
  curl -XPOST 'http://localhost:9200/jdonref/_search' -d '{
    "query": {
      "jdonrefv3es" : {
        "value" : "24 BOULEVARD DE L HOPITAL 75005 PARIS"
      }
    }
  }'

le résultat est de la forme :
  {
    "_shards":{
        "total" : 5,
        "successful" : 5,
        "failed" : 0
    },
    "hits":{
        "total" : 1,
        "hits" : [
            {
                "_index" : "jdonref",
                "_type" : "adresse",
                "_id" : "1",
                "_score" : 200.0,
                "_source" : {
                    "adr_id" : "123456789X",
                    "code_insee" : "75105",
                    "code_departement": "75",
                    "numero" : "24",
                    "type_de_voie" : "BOULEVARD",
                    "article" : "DE L",
                    "libelle" : "HOPITAL",
                    "commune" : "PARIS",
                    "code_postal" : "75005",
                    "ligne4": "24 BOULEVARD DE L HOPITAL",
                    "ligne6": "75005 PARIS",
                    "ligne7": "FRANCE",
                    "geometrie": { "type" :"point", "coordinates": [123, 456] }
                }
            }
        ]
    }
  }

Les types "voie", "commune", "departement", "pays" peuvent aussi être retournés.
Les coordonnées sont en WGS84 par défaut dans la version 0.2, une version ultérieure permettra de le transformer à la volée en Lambert 93.

=====Filtres=====

Il est possible de la combiner avec des filtres, par exemple pour limiter les résultats à un département précis :

  {
    "filtered" : {
      "query": {
        "jdonrefv3es" : {
          "value" : "24 BOULEVARD DE L HOPITAL 75 PARIS"
        }
      },
      "filter": {
        "term" : { "code_departement" : "75" }
      }
    }
  }

Ou de restreindre la recherche à une zone géographique :

  {
    "filtered" : {
      "query": {
        "jdonrefv3es" : {
          "value" : "24 BOULEVARD DE L HOPITAL 75 PARIS"
        }
      },
      "filter" : {
        "geo_shape": {
           "geometrie" : {
             "shape" : {
                "type" : "enveloppe",
                "coordinates": [[13,53],[14,52]]
             }
           }
        }
      }
    }
  }

=====Principe de fonctionnement=====

ElasticSearch étant un moteur d'indexation à plat, il ne fait pas nativement de distinction entre les termes qu'il indexe. ElasticSearch s'appuie par exemple sur la fréquence des termes dans l'ensemble du corpus.

Toutefois, dans une adresse, les éléments qui la compose peuvent avoir une importance très différente dans l'adresse. Notamment, ce n'est pas toujours leur fréquence qui guide leur importance.

Par exemple concernant la requête :
  57 BD DE L HOPITAL 75 PARIS

A la saisie de cette adresse, on ne s'attendrait pas à retrouver des résultats tels que :
  75 BD DE L HOPITAL 75013 PARIS (le numéro de voie 75)
  75 rue de paris 57 L HOPITAL (la ville l'hopital en moselle, la voie n'existe pas il s'agit d'un exemple)

L'exactitude du numéro d'adresse a ici une importance qui dépasse sa fréquence élevée d'apparition dans le corpus.

Pour mettre en avant les résultats les plus pertinents, ElasticSearch s'appuie sur le moteur lucene qui attribue une note à chaque résultat. JDONREFv3ES surcharge ce système de notation et attribue une nouvelle note à chaque résultat. Pour tout dire, le plugin ne met pas en avant les bons résultats, il dégrade les mauvais.

=====Notation=====

Le système de notation mis en oeuvre par JDONREFv3ES a plusieurs objectifs :
#mettre en avant les résultats les plus pertinents
#disposer d'une notation absolue, permettant à une IA d'effectuer un choix objectif parmi les propositions de résultats (voir le mode bulk plus loin)

L'algorithme de notation reprend celui de JDONREFv2 et JDONREFv3, adapté à une recherche par index inversé.

Plutôt que d'affecter un poids à chaque élément de l'adresse, il s'appuie simplement sur une version légèrement adapté de la classe DefaultSimilarity d'ElasticSearch.
Il est (sera) possible de choisir les éléments qui participent à cette notation.

Le mode bulk permet de disposer d'un notation absolue, c'est à dire dont la note maximale est 200. Le plafond est déterminé par la note maximale qu'il est possible d'avoir pour chaque document. Le score est ensuite rapporté sur 200 par une simple règle de trois, par simple commodité (sinon tous les scores seraient inférieurs ou égaux à 1).
A noter que ce mode bulk nécessite un peu plus de calcul que la note traditionnelle, c'est pourquoi il s'agit d'une option.
Le mode bulk n'est pas nécessaire lorsqu'un être humain peut choisir l'adresse parmi plusieurs propositions. Par contre, le fait de disposer d'une note plafonnée (sur 200) va permettre à une IA de choisir lui-même la proposition en lui fixant un seuil (par exemple, l'adresse est choisie si sa note est supérieure à 180).

Pour le moment, les éléments pris en compte sont présentés dans le tableau ci-dessous.
{| border="1"
 | '''éléments'''
 | '''remarque'''
|-
 | ligne 1
 | 
|-
 | ligne 4
 | Elle peut ou pas contenir le numéro d'adresse. La présence du numéro conditionne un malus.
|-
 | codes
 | Il est construit à partir des champs code postal / code insee / code departement / code arrondissement. Contrairement aux autres champs, il suffit d'avoir l'un d'entre eux présent pour obtenir la note maximale.
|-
 | commune
 | 
|-
 | ligne 7
 | 
|-
 | code_pays
 | Le code pays n'est actuellement pas pris en compte, mais aura probablement le même poids que la ligne7.
|}

Plusieurs malus sont ensuite appliqués à la somme totale :
#si l'ordre des termes appartenant à un élément ne sont pas consécutifs. Sa valeur est de 0.5 pour chaque terme discordant. C'est très pénalisant.
#s'il s'agit d'une adresse, et que l'adresse n'est pas présente (ou erronée), la note est 0. Les résultats disposant d'un numéro d'adresse erroné ne sont donc pas retournés (le nombre de faux positif est trop important).
#si le document ne dispose pas de numéro d'adresse, mais qu'un numéro est présent devant la voie, un malus de 0.5 est appliqué (cela complète en quelque sorte le malus sur l'ordre des termes)
#s'il s'agit d'un POI ou d'une Zone, la ligne1 ou la ligne4 doit être présente, sinon la note est 0.
#s'il s'agit d'une voie ou d'une adresse, la ligne4 et codes ou commune doit être présent, sinon la note est 0.
#s'il s'agit d'une commune, le champ codes ou commune doit être présent, sinon la note est 0.
#s'il s'agit d'un département, le champ codes doit être présent, sinon la note est 0.
#s'il s'agit d'un pays, le champ ligne7 doit être présent, sinon la note est 0.

=====Modes (mode bulk)=====

Le mode bulk s'active simplement en utilisant le paramètre "mode" avec la valeur "bulk" de la sorte :

  {
    "query": {
      "jdonrefv3es" : {
         "value" : "24 BOULEVARD DE L HOPITAL 75 PARIS",
         "mode": "bulk"
      }
    }
  }

Le paramètre mode prend deux valeurs actuellement.
#"autocomplete", il s'agit du mode par défaut, le calcul de la note correspond à la somme de la note des termes trouvés
#"bulk", la note de l'autocomplete est divisée par la somme des termes qui auraient pu être trouvés, rapporté sur 200.

=====Exemples de calcul en mode bulk=====

Les exemples qui suivent ne sont pas exhaustifs mais présentent le comportement recherché par la requête en mode bulk.
La note donnée ici est indicative, car en réalité elle s'appuie sur la fréquence des termes recherchés et trouvés, suivant la logique du moteur à indexation inverse.

{| border="1"
 | '''requête'''
 | '''résultat'''
 | '''note indicative'''
 | '''calcul'''
|-
 | 130 RUE REMY DUHEM 59500 DOUAI
 | 130 RUE REMY DUHEM 59500 DOUAI FRANCE
 | 200
 | Tous les éléments de ligne4, code postal, et commune sont présents. Le pays est absent, mais son poids est de 0.
|-
 | 130 RUE REMY DUHEM 59 DOUAI
 | 130 RUE REMY DUHEM 59500 DOUAI FRANCE
 | 200
 | Tous les éléments de ligne4 et commune sont présents. Le code de département est correct. Le pays est absent, mais son poids est de 0.
|-
 | 130 RUE REMY 59500 DOUAI DUHEM
 | 130 RUE REMY DUHEM 59500 DOUAI FRANCE
 | 166 = ((50 + 50 + 50 + 50)*0.5/4 + 50 + 50 + 0)*200/150
 | Tous les éléments de ligne4 (50+50+50+50), code postal et commune (50+50) sont présents. Le pays est absent, mais son poids est de 0. L'ordre des éléments de la ligne 4 n'est pas respecté (*0.5). Le tout pondéré (/150) et ramené à 200 (*200).
|-
 | RUE REMY DUHEM 59500 DOUAI
 | RUE REMY DUHEM 59500 DOUAI FRANCE
 | 200
 | Tous les éléments de ligne4, code postal, et commune sont présents. Le pays est absent, mais son poids est de 0.
|-
 | RUE REMY DUHEM 59500 DOUAI
 | 130 RUE REMY DUHEM 59500 DOUAI FRANCE 
 | 0
 | Tous les éléments du code postal et commune sont présents. Le pays est absent, mais son poids est de 0. Un malus est toutefois appliqué du fait de l'absence du numéro d'adresse dans la requête, ce qui attribue une note de 0 au total.
|-
 | RUE REMY 59 DOUAI
 | RUE REMY DUHEM 59500 DOUAI FRANCE
 | 177 = ((50 + 50)/3 + 50 + 50 + 0) * 200 / 150
 | Le code postal et la commune sont présent (50 + 50). Le pays est absent, mais son poids est de 0. Seuls 2 termes sur 3 sont présents dans la ligne 4 ((50 + 50)/3). Le tout pondéré (/150) et ramené à 200 (*200).
|-
 | RUE REMY 59 DOUAI
 | RUE REMY DUHEM 59500 DOUAI FRANCE
 | 177 = ((50 + 50)/3 + 50 + 50 + 0) * 200 / 150
 | Le code postal et la commune sont présent (50 + 50). Le pays est absent, mais son poids est de 0. Seuls 2 termes sur 3 sont présents dans la ligne 4 ((50 + 50)/3). Le tout pondéré (/150) et ramené à 200 (*200).
|-
 | RUE REM DUH 59 DOUAI
 | RUE REMY DUHEM 59500 DOUAI FRANCE
 | 163 = ((50*75/100 + 50*60/100)/3 + 50 + 50 + 0) * 200 / 150
 | Le code postal et la commune sont présent (50 + 50). Le pays est absent, mais son poids est de 0. Seuls 2 termes sur 3 sont présents dans la ligne 4, et partiels ((50*75/100 + 50*60/100)/3). Le tout pondéré (/150) et ramené à 200 (*200).
|-
 | 59500 DOUAI
 | 59500 DOUAI FRANCE
 | 200
 | Le code postal et la commune sont présent. Le pays est absent, mais son poids est de 0.
|-
 | 59500 DOUAI
 | RUE REMY DUHEM 59500 DOUAI FRANCE
 | 133 = (0 + 50 + 50 + 0) * 200 / 150
 | Le code postal et la commune sont présent (50+50). La ligne 4 est absente (0). Le pays est absent, mais son poids est de 0. Le tout pondéré (/150) et ramené à 200 (*200).
|-
 | 59505 DOUAI
 | 59500 DOUAI FRANCE
 | 100 = (0 + 50 + 0) * 200 /100
 | La commune est présente (50), mais le code postal est faux (0). Le pays est absent, mais son poids est de 0. NB: pour améliorer cette note (le code postal est très proche), une évolution du TokenFilter de JDONREF devrait être effectuée).
|-
 | 59
 | 59 FRANCE
 | 200
 | Le code département est présent.
|-
 | FRANCE
 | FRANCE
 | 200
 | La ligne 7 est présente.
|}

Ces exemples ne présentent pas la prise en compte de la phonétique, qui n'intervient pas dans la notation. Deux requêtes qui disposent de la même phonétique ont les mêmes résultats.

=====Effets de bord=====

Les exemples présentés ci-dessus induisent nécessairement des effets de bords compréhensibles sur certaines recherches.

Par exemple :
#Il ne faut pas s'attendre à trouver comme meilleur résultat l'avenue de France en effectuant une recherche sur le seul mot clé "FRANCE". C'est bien entendu le pays qui aura la meilleure note ...