JDONREFv4 plugin GettingStarted : Différence entre versions

Version actuelle en date du 27 février 2016 à 00:10

Cette page est destinée aux utilisateurs confirmés d'ElasticSearch qui souhaitent utiliser JDONREF. Si des éléments vous échappent dans cette page, je vous invite à revoir la page des débutants.

L'utilisation du plugin JDONREFv4 nécessite :

de disposer d'un cluster elasticsearch !
d'installer le plugin JDONREFv4 (voir ici)
de créer le ou les index nécessaires
de créer les mappings
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 jdonrefv4 fourni un moyen de chercher efficacement des adresses (c'est à dire avec les résultats auxquels on devrait s'attendre). Cette page suppose que le cluster elasticsearch et que le plugin jdonref (et éventuelles dépendances) sont installés.

Création de l'index

L'index proposé est du type:

 curl -XPUT 'http://localhost:9200/jdonref/' -d @/usr/share/elasticsearch/plugins/jdonrefv4-0.5/jdonrefv4-settings.json

Néanmoins, il est proposé de créer un index par type. Ce découpage est nécessaire car la requête JDONREFv4 se spécialise suivant l'index. Plus précisément, il faut que l'index contienne l'un des mots-clés suivant :

poizon
adresse
voie
commune
departement
pays

Si vos données sont présentes dans un index dont le nom ne contient pas l'un de ces mots, la requête ne s'applique pas. Il est aussi préférable de ne pas mélanger les types au sein de ces index (avec un nom d'index qui contiendrait le nom des deux types !). Pour des raisons de performance le type n'est pas vérifié dans la requête.

D'une manière générale, l'effet de bord de la fréquence d'un type sur un autre n'est pas positif. Par exemple, les communes sont 36 000, mais au sein des adresses, elles sont représentées 18 000 000 de fois.

Vous pouvez noter plusieurs choses au sujet de cette configuration d'index :

Par défaut, les nGram est les synonymes ne sont pas utilisés.
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.

Un alias

Ces remarques signifient surtout que ce plugin n'est qu'un outil. Vous pouvez l'utiliser à votre guise, modifier le fichier de configuration fourni, et adapter les analyzers à votre propre cas de figure.

A titre d'exemple, vous souhaiterez sans doute effectuer des mises à jour de JDONREF. Si vous effectuez une mise à jour en masse de l'ensemble de vos adresses, vous aurez une interruption de service. Plutôt que d'utiliser un index, elasticsearch vous propose d'utiliser un alias :

 curl -XPUT 'http://localhost:9200/jdonref_20141201/' -d @/usr/share/elasticsearch/plugins/jdonrefv4-0.3/jdonrefv4-settings_beginner.json
 ... indexation ...
 curl -XPOST 'http://localhost:9200/_aliases/' -d '{ "actions" : [ {"add" : {"index" : "jdonref_20141201", "alias" : "jdonref"}}]}'

Ce qui vous permettra d'utiliser l'alias "jdonref" tout comme un index, et de réindexer sous un autre nom pour effectuer une mise à jour :

 curl -XPUT 'http://localhost:9200/jdonref_20141202/' -d @/usr/share/elasticsearch/plugins/jdonrefv4-0.3/jdonrefv4-settings_beginner.json
 ... réindexation ...
 curl -XPOST 'http://localhost:9200/_aliases/' -d '{ "actions" : [ {"add" : {"index":"jdonref_20141202", "alias":"jdonref"}}, {"remove" : {"index":"jdonref_20141201", "alias":"jdonref"}}]}'

Si vous avez bien compris, il va vous falloir doubler votre DD, soit environ 20 Go pour la France entière.

Bon. Cela dit j'avais présupposé dans l'introduction que vous étiez familiers de elasticsearch ... Vous ne m'y reprendrez plus. Passons aux choses sérieuses !

JDONREFv4 plugin GettingStarted : Différence entre versions

Version actuelle en date du 27 février 2016 à 00:10

Création de l'index

Un alias

Menu de navigation

Affichages

Outils personnels

FusionForge

Navigation

Rechercher

Outils

@@ Ligne 1 : / Ligne 1 : @@
-L'utilisation du plugin JDONREFv3ES nécessite :
+Cette page est destinée aux utilisateurs confirmés d'ElasticSearch qui souhaitent utiliser JDONREF.
+Si des éléments vous échappent dans cette page, je vous invite à revoir la page des [[JDONREFv4_Plugin_BeginnersMode|débutants]].
+L'utilisation du plugin JDONREFv4 nécessite :
 * de disposer d'un cluster [http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/setup.html elasticsearch] !
-* de déployer le fichier de synonymes de JDONREFv3ES (voir [[JDONREFv3ES_Plugin#Pr.C3.A9requis_avant_d.27utiliser_le_plugin|ici]])
+* d'installer le [[JDONREFv4_Plugin|plugin]] JDONREFv4 (voir [[JDONREFv4_Plugin#Installation_du_plugin| ici]])
-* d'installer le [[JDONREFv3ES_Plugin|plugin]] JDONREFv3ES (voir [[JDONREFv3ES_Plugin#Installation_du_plugin| ici]])
+* de créer le ou les index nécessaires
+* de créer les mappings
 * 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).
+Vous êtes ensuite libre d'effectuer les recherches souhaitées ! L'API elasticsearch peut bien sûr être utilisée, mais le plugin jdonrefv4 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.
+Cette page suppose que le cluster elasticsearch et que le plugin jdonref (et éventuelles dépendances) sont installés.
 ==== 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 :
+L'index proposé est du type:
-  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 [[JDONREFv3ES_Mappings|mappings]] fournis par jdonref.
-Cette opération est obligatoire pour que la requête de JDONREF puisse traiter correctement les données indexées.
-Par exemple, pour que l'indexation de la géométrie se déroule correctement, les mappings auront du être définis au préalable, car ElasticSearch ne détecte pas automatiquement les géométries.
-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é. Il est cependant vrai que dans le fond, vous pouvez vous en occuper vous-même.
-Le champ "fullName" est lui aussi précalculé et contient l'ensemble des termes utilisé par la requête JDONREFv3. Il n'est ainsi pas uniquement la concaténation des champs ligne1, ligne4, et ligne6, mais dispose aussi des champs indexés dans "codes". Il permet d'effectuer un premier niveau de filtrage sur les résultats, très rapidement.
-Enfin, le nom des types attribués à chaque mapping doit pour le moment être respecté. Dans le cas contraire, les malus ne pourront pas être appliqués.
-===== 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'[[JDONREFv3ES_Analyzer|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.
+  curl -XPUT 'http://localhost:9200/jdonref/' -d @/usr/share/elasticsearch/plugins/jdonrefv4-0.5/jdonrefv4-settings.json
-Théoriquement, vous devriez pouvoir vous en sortir avec l'attribut [http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/mapping-core-types.html#copy-to copy_to] d'elasticsearch.
-==== Indexation du contenu ====
+Néanmoins, il est proposé de créer un index par type. Ce découpage est nécessaire car la requête JDONREFv4 se spécialise suivant l'index.
+Plus précisément, il faut que l'index contienne l'un des mots-clés suivant :
+# poizon
+# adresse
+# voie
+# commune
+# departement
+# pays
+Si vos données sont présentes dans un index dont le nom ne contient pas l'un de ces mots, la requête ne s'applique pas.
+Il est aussi préférable de ne pas mélanger les types au sein de ces index (avec un nom d'index qui contiendrait le nom des deux types !). Pour des raisons de performance le type n'est pas vérifié dans la requête.
-Il est ensuite possible d'indexer du contenu, comme une commune :
+D'une manière générale, l'effet de bord de la fréquence d'un type sur un autre n'est pas positif. Par exemple, les communes sont 36 000, mais au sein des adresses, elles sont représentées 18 000 000 de fois.
-  curl -XPUT 'http://localhost:9200/jdonref/commune/1' -d '{
+Vous pouvez noter plusieurs choses au sujet de cette configuration d'index :
-    "code_insee" : "75056",
+* Par défaut, les nGram est les synonymes ne sont pas utilisés.
-    "code_departement" : "75",
+* 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.
-    "code_pays" : "1",
+* Le "french_keywords" peut être rétabli si vous notez quelques mots auxquels l'application du stemmer ne fournis pas de bons résultats.
-    "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 :
+==== Un alias ====
-  curl -XPUT 'http://localhost:9200/jdonref/voie/1' -d '{
+Ces remarques signifient surtout que ce plugin n'est qu'un outil. Vous pouvez l'utiliser à votre guise, modifier le fichier de configuration fourni, et adapter les analyzers à votre propre cas de figure.
-    "numero_min": "1",
-    "numero_max": "192",
-    "type_de_voie": "BOULEVARD",
-    "article": "DE",
-    "voie": "HOPITAL",
-    "code_insee_commune" : "75056",
-    "code_postal" : "75013",
-    "code_insee": "75113",
-    "code_departement" : "75",
-    "code_pays" : "FR1",
-    "commune" : "PARIS",
-    "ligne4" : "BOULEVARD DE L HOPITAL",
-    "ligne6" : "75013 PARIS",
-    "ligne7" : "FRANCE",
-    "type": "voie",
-    "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]]
-        ]
-    }
-  }'
-===== Indexation en masse =====
+A titre d'exemple, vous souhaiterez sans doute effectuer des mises à jour de JDONREF. Si vous effectuez une mise à jour en masse de l'ensemble de vos adresses, vous aurez une interruption de service.
+Plutôt que d'utiliser un index, elasticsearch vous propose d'utiliser un [http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-aliases.html alias] :
-A noter qu'il est conseillé d'utiliser l'API [[http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/docs-bulk.html BULK]] d'ElasticSearch pour procéder à l'indexation d'un très grand nombre d'adresses.
+  curl -XPUT 'http://localhost:9200/jdonref_20141201/' -d @/usr/share/elasticsearch/plugins/jdonrefv4-0.3/jdonrefv4-settings_beginner.json
+  ... indexation ...
+  curl -XPOST 'http://localhost:9200/_aliases/' -d '{ "actions" : [ {"add" : {"index" : "jdonref_20141201", "alias" : "jdonref"}}]}'
-Attention, pour que la [[JDONREFv3ES_Query|requête]] du [[JDONREFv3ES_Plugin|plugin]] fonctionne correctement, certains champs doivent être correctement renseignés. L'[[JDONREFv3ES_Analyzer|analyzer]] fourni permet de remplir ce travail automatiquement.
+Ce qui vous permettra d'utiliser l'alias "jdonref" tout comme un index, et de réindexer sous un autre nom pour effectuer une mise à jour :
-==== Recherches ====
+  curl -XPUT 'http://localhost:9200/jdonref_20141202/' -d @/usr/share/elasticsearch/plugins/jdonrefv4-0.3/jdonrefv4-settings_beginner.json
+  ... réindexation ...
+  curl -XPOST 'http://localhost:9200/_aliases/' -d '{ "actions" : [ {"add" : {"index":"jdonref_20141202", "alias":"jdonref"}}, {"remove" : {"index":"jdonref_20141201", "alias":"jdonref"}}]}'
-Une fois le contenu indexé, il vous est possible d'effectuer des [[JDONREFv3ES_Query|recherches]] à loisir !
-==== Debug ====
+Si vous avez bien compris, il va vous falloir doubler votre DD, soit environ 20 Go pour la France entière.
-Pour les experts, un mode debug est disponible avec le paramètre debugDoc de la sorte :
+Bon. Cela dit j'avais présupposé dans l'introduction que vous étiez familiers de elasticsearch ... Vous ne m'y reprendrez plus. Passons aux choses sérieuses !
-  curl -XPOST 'http://localhost:9200/jdonref/_search' -d '{
-    "query": {
-      "jdonrefv3es" : {
-        "value" : "24 BOULEVARD DE L HOPITAL 75005 PARIS",
-        "debugDoc": 2154
-      }
-    }
-  }'
-Cela permet d'afficher au niveau debug (niveau log4j), dans les logs d'elasticsearch, l'exécution détaillée du calcul de la note associée au document d'id "debugDoc". Il ne s'agit toutefois pas de l'id du document correspondant à _id, mais l'id du document relativement au shard considéré. Pour l'identifier, il suffit d'exécuter une requête dont le résultat inclus le document recherché, en mode explain (l'explication fait référence à l'id relatif au shard !).