Tutoriel SolR

common/license.adoc

Table of Contents

1. Références
2. Mise en place
3. Initialisation
- 3.1. Création de core
- 3.2. Ajout de données
4. Modification du schéma
5. Exécution de requêtes
- 5.1. Requête basique
- 5.2. Quelques fonctionnalités
6. Analyser l’index

1. Références

Apache Solr Reference Guide [EN]

2. Mise en place

2.1. Prérequis

SolR nécessite l’installation préalable d’un Java Runtime Environment version 1.8+.

Télécharger et installer l’option adéquate en fonction du système d’exploitation.

2.2. Installation

Il n’y a pas d’installation à proprement parler, il suffit de télécharger l’archive et de la décompresser.

Note	Pour les utilisateurs de Homebrew, il est aussi possible d’installer SolR via la commande `brew install solr`.

2.3. Lancement

Se positionner à la racine du répertoire décompressé, puis lancer la commande :

bin/solr start

Vérifier que SolR est lancé en à l’aide de la commande :

bin/solr status

Le résultat est similaire à la sortie suivante :

Found 1 Solr nodes:

Solr process 15840 running on port 8983
{
  "solr_home":"~/solr-6.2.1/server/solr",
  "version":"6.2.1 43ab70147eb494324a1410f7a9f16a896a59bc6f - shalin - 2016-09-15 05:20:53",
  "startTime":"2016-10-29T15:04:01.454Z",
  "uptime":"0 days, 0 hours, 31 minutes, 39 seconds",
  "memory":"40.9 MB (%8.3) of 490.7 MB"}

SolR dispose d’une interface graphique accessible à l’adresse http://localhost:8983/solr.

3. Initialisation

3.1. Création de core

Sur l’écran précédent, il est mentionné qu’il n’y a pas de core: un core est l’emplacement de stockage de l’index. Avant toute manipulation, il est nécessaire d’initialiser cet index.

bin/solr create -c films

Le résultat attendu doit être le suivant :

Creating new core 'films' using command:
http://localhost:8983/solr/admin/cores?action=CREATE&name=films&instanceDir=films

{
  "responseHeader":{
    "status":0,
    "QTime":1005},
  "core":"films"}

Il est possible de vérifier le succès de l’opération:

dans le système de fichiers: server/solr/films
dans l’interface graphique

3.2. Ajout de données

Le core créé précédemment est vide et est donc inutile. Pour aller plus loin, il est nécessaire d’aller d’ajouter des données. Il existe plusieurs sources de données exemple, utilisons l’une d’entre elles avec l’outil fourni:

bin/post -c films example/films/films.json

Le résultat doit être semblable au suivant :

java -classpath ~/solr-6.2.1/dist/solr-core-6.2.1.jar -Dauto=yes -Dc=films -Ddata=files org.apache.solr.util.SimplePostTool ../example/films/films.json
SimplePostTool version 5.0.0
Posting files to [base] url http://localhost:8983/solr/films/update...
Entering auto mode. File endings considered are xml,json,jsonl,csv,pdf,doc,docx,ppt,pptx,xls,xlsx,odt,odp,ods,ott,otp,ots,rtf,htm,html,txt,log
POSTing file films.json (application/json) to [base]/json/docs
SimplePostTool: WARNING: Solr returned an error #400 (Bad Request) for url: http://localhost:8983/solr/films/update/json/docs
SimplePostTool: WARNING: Response: {"responseHeader":{"status":400,"QTime":109},"error":{"metadata":["error-class","org.apache.solr.common.SolrException","root-error-class","java.lang.NumberFormatException"],"msg":"ERROR: [doc=/en/quien_es_el_senor_lopez] Error adding field 'name'='¿Quién es el señor López?' msg=For input string: \"¿Quién es el señor López?\"","code":400}}
SimplePostTool: WARNING: IOException while reading response: java.io.IOException: Server returned HTTP response code: 400 for URL: http://localhost:8983/solr/films/update/json/docs
1 files indexed.
COMMITting Solr index changes to http://localhost:8983/solr/films/update...
Time spent: 0:00:00.271

4. Modification du schéma

Dans cette version de SolR, le schéma est créé lors du premier ajout de données en inférant les champs et leur type. L’erreur précédente provient d’un décalage entre le type du premier élément pour le champ name dans le fichier d’exemple et le type des éléments suivants.

Vérifier le type du champ name à l’aide de l’interface graphique. Cette information est également disponible dans le fichier de configuration.

server/solr/films/conf/managed-schema

<field name="name" type="tdoubles"/>

example/films/films.json

{
  "id": "/en/quien_es_el_senor_lopez",
  "directed_by": [
    "Luis Mandoki"
  ],
  "genre": [
    "Documentary film"
  ],
  "name": "\u00bfQui\u00e9n es el se\u00f1or L\u00f3pez?"
}

Note	L’ajout d’entrées dans l’index est séquentiel. Vérifier que les entrées précédentes du fichier sont bien compatibles avec le type `tdoubles`.

Pour modifier le schéma, deux options sont possibles :

Editer le fichier server/solr/films/conf/managed-schema. Il est alors nécessaire de redémarrer le serveur pour prendre en compte les modifications. De plus, l’accès au système de fichiers n’est généralement pas autorisé.
Exécuter un appel l’API de gestion de schéma

En utilisant l’une des deux méthodes proposées, de préférence la seconde, modifier le type du champ name en text_general.

Retenter alors l’indexation comme ci-dessus. Le résultat doit maintenant être différent :

java -classpath ~/solr-6.2.1/dist/solr-core-6.2.1.jar -Dauto=yes -Dc=films -Ddata=files org.apache.solr.util.SimplePostTool ../example/films/films.json
SimplePostTool version 5.0.0
Posting files to [base] url http://localhost:8983/solr/films/update...
Entering auto mode. File endings considered are xml,json,jsonl,csv,pdf,doc,docx,ppt,pptx,xls,xlsx,odt,odp,ods,ott,otp,ots,rtf,htm,html,txt,log
POSTing file films.json (application/json) to [base]/json/docs
1 files indexed.
COMMITting Solr index changes to http://localhost:8983/solr/films/update...
Time spent: 0:00:00.471

5. Exécution de requêtes

L’exécution de requêtes se fait par l’intermédiaire d’une API REST.

Afin d’expérimenter avec celle-ci, il est possible d’utiliser :

La commande curl (systèmes *Nix)
L’interface graphique. Celle-ci génère également l’URL complète.
Postman

Tip	L’utilisation de Postman est recommandé : il s’agit d’une application qui permet d’exécuter des appels REST et de les sauvegarder pour un usage futur. Elle permet également d’exporter chaque requête en tant qu’URL (comme pour l’interface SolR).

5.1. Requête basique

Exécuter la requête suivante :

curl 'http://localhost:8983/solr/films/select?indent=on&q=*:*&wt=json'

Analyser la réponse retournée :

Le nombre d’éléments de la réponse
Le nombre d’éléments totaux
La différence entre la structure de la réponse et la structure du fichier JSON original (example/films/films.json)

5.2. Quelques fonctionnalités

Limite des champs de résultat

// TODO

Limite du nombre d’éléments

Par défaut, le nombre d’éléments retournés est de 10. Cette valeur par défaut peut être modifiée à l’aide du paramètre rows.

Limiter le résultat à 12 éléments.

Tri

L’ensemble des éléments retournés peut être trié en utilisant le paramètre sort avec le nom du champ et asc/desc.

Trier les résultats par ordre inverse de leur name.

Terme de recherche

Le paramètre de requête est q=*:*. Ce paramètre indique que la q(uery) est *:*. Le premier caractère joker est le champ de recherche, le second le terme de recherche. Si aucun champ n’est spécifié, la recherche s’effectue dans le champ par défaut _text_.

Limiter les résultats aux éléments comprenant le terme "john".

Effectuer la même requête mais en limitant le terme au champ name. Comparer les résultats.

Opérateurs booléens

Le paramètre q accepte la combinaison de termes via les opérateurs booléens AND et OR. Cette combinaison peut être appliquée que le terme s’applique à un champ ou non.

Limiter les résultats aux éléments comprenant le terme "john" et "thriller".
Puis, exécuter une nouvelle requête en limitant les résultats comportant les termes "fun" dans le champ name et "Comedy" dans le champ genre.

Recherche à facettes

La recherche à facettes permet d’implémenter la fonctionnalité "classique" de recherche par catégorie dans les sites d’e-commerce, par exemple par couleur. Si l’on adopte un point de vue SQL, il s’agit de la combinaison de commandes GROUP BY et COUNT.

Pour effectuer une recherche à facettes, utiliser les paramètres suivants :

facet
facet.field avec comme valeur le champ sur lequel doit s’exercer la facette

Exécuter une recherche à facettes sur le champ genre. Analyser la structure du résultat retourné.

Tip

Pour ajouter une facette à chaque requête, il est possible d’utiliser l’API de paramètres de requête.

Balisage

La fonctionnalité de balisage permet de retourner une structure comportant déjà des balises autour des termes de recherche dans les résultats. Il suffit d’ajouter les paramètres :

hl=true
hl.fl avec pour valeur le nom du champ qui doit recevoir le balisage

Par défaut, la balise est <em> mais il est possible de personnaliser le balisage avec les paramètres respectifs hl.simple.pre pour la balise de début et hl.simple.post pour la balise de fin.

Exécuter à nouveau la requête sur le terme "john" dans le champ name en activant cette fois le balisage sur ce champ. Analyse la structure du résultat.

6. Analyser l’index

En utilisant le paramètre précédent, chercher les films dont un des genre est "thriller". Quel est le résultat?

formations/solr-foundations