Version du 6 septembre 2014 à 13:58

L'utilisation du plugin JDONREFv3ES nécessite :

• de disposer d'un cluster elasticsearch !
• de déployer le fichier de synonymes de JDONREFv3ES (voir ici)
• d'installer le plugin JDONREFv3ES (voir ici)
• puis d'indexer le contenu

Vous êtes ensuite libre d'effectuer les recherches souhaitées ! L'API elasticsearch peut bien sûr être utilisée, mais le plugin jdonrefv3es fourni un moyen de chercher efficacement des adresses (c'est à dire avec les résultats auxquels on devrait s'attendre). Cette page décrit une démarche possible en débutant par l'indexation du contenu.

Création de l'index

Commencez par vous créer un index en respectant la configuration fournie par le fichier jdonrefv3es-settings.json de la sorte :

 curl -XPUT 'http://localhost:9200/jdonref/' -d '{
    "index" : {
       "analysis" : {
           "analyzer": {
               "jdonrefv3es_index" : {
                   "type" : "custom",
                   "tokenizer" : "standard",
                   "filter" : ["french_elision", "lowercase", "french_stop",/*/"french_keywords",*/ "french_stemmer","jdonrefv3es_synonyme", "jdonrefv3es_nGram"]
               },
               "jdonrefv3es_codes_index" : {
                   "type" : "custom",
                   "tokenizer" : "standard",
                   "filter" : ["standard", "lowercase"]
               },
               "jdonrefv3es_search" : {
                   "type" : "custom",
                   "tokenizer" : "standard",
                   "filter" : ["french_elision", "lowercase", "french_stop",/*/"french_keywords",*/ "french_stemmer"]
               }
           },
           "filter" : {
               "french_elision": {
                 "type":         "elision",
                 "articles": [ "l", "m", "t", "qu", "n", "s",
                                 "j", "d", "c", "jusqu", "quoiqu",
                                 "lorsqu", "puisqu"
                             ]
               },
               "french_stop": {
                 "type":       "stop",
                 "stopwords":  "_french_" 
               },
 //            "french_keywords": {
 //              "type":       "keyword_marker",
 //              "keywords":   [] 
 //            },
               "french_stemmer": {
                 "type":       "stemmer",
                 "language":   "light_french"
               },
 //            "jdonrefv3es_metaphone" : {
 //                "type" : "phonetic",
 //                "encoder" : "metaphone",
 //                "replace" : true
 //            },
               "jdonrefv3es_synonyme" : {
                   "type" : "synonym",
                   "synonyms_path": "jdonrefv3es_synonym.fr_FR.txt"
               },
               "jdonrefv3es_nGram" : {
                   "type" : "edgeNGram",
                   "min_gram": 5,
                   "max_gram": 15,
                   "token_chars": ["digit"]
               }
           },
           "similarity": {
               "jdonrefv3es" : {
                   "type": "org.apache.lucene.search.similarities.JDONREFv3TermSimilarity"
               }
           }
       }
   }
 }'

A noter que le metaphone n'est plus utilisé pour le moment, car combiné au ngram, il introduit un trop grand nombre de faux positifs. Vous pouvez toutefois le mettre en place à votre guise. Le "french_keywords" peut être rétabli si vous notez quelques mots auxquels l'application du stemmer ne fournis pas de bons résultats.

Création des mappings

Pour que le plugin jdonrefv3es soit efficace, il s'agit de respecter les mappings fournis par jdonref. Cette opération est obligatoire pour que la requête de JDONREF puisse traiter correctement les données indexées.

Indexation du contenu

Il est ensuite possible d'indexer du contenu, comme une commune :

 curl -XPUT 'http://localhost:9200/jdonref/commune/1' -d '{
   "code_insee" : "75056",
   "code_departement" : "75",
   "code_pays" : "1",
   "commune" : "PARIS",
   "code_postal" : "75000",
   "ligne7" : "FRANCE",
   "type" : "commune",
   "t0" : "22/03/2014",
   "geometrie" : {
       "type": "multipolygon",
       "coordinates" : [
          [[102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0], [102.0, 2.0]],
          [[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]],
          [[100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2]]
       ]
   }
 }'

ou une voie :

 curl -XPUT 'http://localhost:9200/jdonref/voie/1' -d '{
   "numero_min": "1",
   "numero_max": "192",
   "type_de_voie": "BOULEVARD",
   "article": "DE",
   "voie": "HOPITAL",
   "code_insee" : "75056",
   "code_departement" : "75",
   "code_pays" : "1",
   "commune" : "PARIS",
   "code_postal" : "75000",
   "ligne7" : "FRANCE",
   "t0" : "22/03/2014",
   "geometrie" : {
       "type": "multipolygon",
       "coordinates" : [
          [[102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0], [102.0, 2.0]],
          [[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]],
          [[100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2]]
       ]
   }
 }'

Remarques sur les mappings

Notez bien que pour que l'indexation de la géométrie se déroule correctement, les mappings auront du être définis au préalable.

Vous avez peut-être aussi remarqué l'existence d'un champ calculé "codes". Si vous utilisez les mappings fournis, il se remplit automatiquement à partir du code_postal, code_insee, code_departement, code_arrondissement quelque soit l'objet considéré.

Le champ "fullName" est lui aussi précalculé et contient l'ensemble des termes utilisé par la requête JDONREFv3. Il permet d'effectuer un premier niveau de filtrage sur les résultats, très rapidement.

Prenez aussi attention au champ 'type'. Ce champ est obligatoire pour les adresses, et peut actuellement prendre différentes valeurs : - poizon - adresse - voie - commune - departement - pays

Si la valeur du type n'est pas renseignée pour une adresse, le numéro d'adresse ne sera pas correctement reconnu.

Utiliser les synonymes

Le fichier de synonymes a normalement été utilisé à la création de votre index à partir du fichier jdonrev3es_synonym.fr.txt.

La recherche pourra ainsi par exemple être effectuée avec le type de voie "BD" plutôt que "BOULEVARD". Attention toutefois, si vous modifiez ce fichier, il faut penser aussi à ré-indexer vos données.

Une autre stratégie consisterait à inverser le fonctionnement du fichier de synonyme pour l'utiliser durant la requête et non pas l'indexation. Le fichier de synonyme contiendrait alors des lignes commme :

 residence, res => residence

et la création de l'analyzer serait par exemple:

           "analyzer": {
               "jdonrefv3es_index" : {
                   "type" : "custom",
                   "tokenizer" : "standard",
                   "filter" : ["standard", "lowercase", "jdonrefv3es_nGram"]
               },
               "jdonrefv3es_search" : {
                   "type" : "custom",
                   "tokenizer" : "standard",
                   "filter" : ["standard", "lowercase", "jdonrefv3es_synonyme"]
               }
           },

Utiliser l'analyser

NB: l'analyzer n'est pas fourni dans les versions 0.1beta et 0.2

Si vous ne voulez pas remplir vous-même les champs "ligne4" et "ligne6", il vous sera possible d'utiliser l'analyzer fourni par jdonref :

 curl -XPUT 'http://localhost:9200/jdonref/' -d '{
   "analysis" : {
     "analyzer" : {
       "jdonrefv3es": {
         "tokenizer": "whitespace"
       }
     }
   }
 }'

Si les lignes 4 et 6 ne sont pas spécifiées durant l'indexation, elles sont alors calculées à partir des autres champs disponibles.

Théoriquement, vous devriez pouvoir vous en sortir avec l'attribut copy_to d'elasticsearch.

Indexation en masse

A noter enfin qu'il est conseillé d'utiliser l'API [BULK] d'ElasticSearch pour procéder à l'indexation d'un très grand nombre d'adresses.

Attention, pour que la requête du plugin fonctionne correctement, certains champs doivent être correctement renseignés. L'analyzer fourni permet de remplir ce travail automatiquement.

Recherches

Une fois le contenu indexé, il vous est possible d'effectuer des recherches à loisir !

En version 0.1beta, l'attribut sur lequel doit porter la recherche est "fullName". Il vous est toutefois possible d'effectuer des filtres sur les autres attributs.

Pour être plus clair, 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 qui sera mise à disposition, mais une version ultérieure permettra de le transformer à la volée en Lambert 93.