Fulltext

Indexation FULLTEXT

Performance

Sur une base de test comportant 200 000 articles, la vitesse de la recherche (hors rendu de la page, qui se fait à temps constant) passe de 5 secondes à 10 millisecondes ; sur deux mots, on passe de 15 secondes à 0,1 seconde.

Pertinence

Les résultats sont beaucoup plus pertinents, puisque si on tape deux mots (ou plus), le moteur FULLTEXT va trouver comme avant l’ensemble des articles contenant ces deux mots, mais attribuera un score plus important à ceux qui disposent de ces deux mots consécutifs. Ce score est comptabilisé par la balise #POINTS.

Fonctionnalité

Outre la recherche basique, le mode FULLTEXT permet d’utiliser des opérateurs logiques :

Remarque : ce tableau constitue le contenu de l’aide fournie dans ce plugin par la balise #AIDE_RECHERCHE.

Principe de fonctionnement

Concernant uniquement la partie mettant en œuvre l’indexation FULLTEXT, le plugin utilise ces deux fichiers :

-  inc/rechercher.php est une amélioration du fichier du même nom livré avec SPIP. À chaque recherche sur une table, ce fichier vérifie la présence d’un ou plusieurs index FULLTEXT sur la table en question (ainsi que sur les tables qui lui sont liées par une jointure, voir ci-dessous).

-  exec/fulltext.php vous propose de créer des index FULLTEXT sur la plupart des tables de SPIP. C’est une proposition, qui correspond aux usages les plus « normaux » de SPIP (pour aller plus loin, cf. ci-dessous, configuration avancée).

Jointures

Le moteur natif de SPIP gère les jointures entre les tables. Avec FULLTEXT on les gère aussi, mais à condition qu’il existe au moins un index FULLTEXT sur chacune des tables liées.

Ainsi par exemple, si vous avez un FULLTEXT sur spip_articles, un autre sur spip_mots, mais aucun sur spip_auteurs, une recherche sur les articles avec le terme « Italie » renverra les articles liés au mot-clé « Italie », mais une recherche sur le terme « Robespierre » ne renverra pas les articles signés par cet auteur.

Autrement dit, sauf application particulière, vous avez tout intérêt à passer l’ensemble des tables en mode FULLTEXT.

Indexation du contenu textuel des documents

Ce plugin propose en outre l’indexation (optionnelle) du contenu textuel des documents joints aux articles et/ou rubriques.

Il stocke pour cela dans la table spip_documents une version texte du document, obtenue à l’aide d’un « extracteur ». Cet extracteur peut être un exécutable système lancé depuis le plugin, ou du code purement PHP.

Les formats supportés à partir de la version 0.6.2 du plugin sont :

• Le PDF, à condition que le fichier ne soit pas protégé contre la copie
• Le DOC, PPT, et XLS
• Le DOCX, PPTX et XLSX (nécessite PHP 5.2 au minimum, ainsi que l’option -enable-zip)
• Le ODT (nécessite PHP 5.2 au minimum, ainsi que l’option -enable-zip)

Installation

Mise en place de l’indexation FULLTEXT

Une fois le plugin installé dans le répertoire plugins/ et activé à partir de la page « Gestion des plugins », la recherche fonctionne exactement comme avant. Pour l’installation proprement dite, il faut créer des index FULLTEXT sur les tables ; pour cela, il suffit de se rendre sur la page ecrire/?exec=fulltext, et de valider les opérations proposées.

On peut aussi, alternativement, les créer « à la main » à partir de n’importe quel client MySQL, avec les commandes suivantes :

ALTER TABLE spip_articles ADD FULLTEXT `titre` (`titre`); 
ALTER TABLE spip_articles ADD FULLTEXT `tout`
   (`surtitre`,`titre`,`soustitre`,`chapo`,`texte`,`nom_site`,`url_site`,`descriptif`); 

Le mode FULLTEXT n’étant disponible que sur les tables au format MyISAM, il faut parfois au préalable convertir les tables dans ce format :

ALTER TABLE spip_articles ENGINE=MyISAM;

La page ecrire/?exec=fulltext permet aussi de faire cela.

Indexation du contenu textuel des documents

Pour l’indexation des documents, il faut installer certains logiciels additionnels, et indiquer leur présence au plugin via des constantes à définir dans le fichier mes_options.php ou en utilisant le panneau de configuration de l’indexation des documents sur la page ecrire/?exec=fulltext_document.

Le panneau de configuration de l’indexation des documents permet de gérer la configuration (extracteurs et options éventuels) pour les fichiers PDF, DOC, PPT, XLS, ODT, DOCX, PPTX et XLSX et d’activer ou non l’indexation de ceux. ceci remplace la définition des constantes dans le fichier mes_options.php.

Certaines constantes sont génériques, non liées au type de fichier :

• _FULLTEXT_TAILLE : Taille maximum conservée (en nombre de caractères) pour la version texte des fichiers (50000 par défaut). Cette configuration est également disponible dans panneau de configuration de l’indexation des documents.
• De même, il est possible de définir l’intervalle (en seconde) entre deux passages du Spip-CRON et le nombre de document traités par itération.

Pour indexer un type de document, il est obligatoire de définir une constante non-nulle de type _FULLTEXT_EXT_EXE (où EXT est l’extension de ces documents) ou d’activer l’indexation via le panneau de configuration.
Il faut également qu’un « extracteur » pour ce type de document soit disponible.

Pour les PDF

• Installer Xpdf
  • sur Ubuntu,
  • sur Mac OS X via MacPorts ou avec cette version compilée,
  • ou sur d’autres OS
• Définir ces constantes :
  • _FULLTEXT_PDF_EXE (par exemple /usr/bin/pdftotext) : Chemin vers l’exécutable pdftotext de Xpdf afin de transformer les fichiers PDF en texte brut
  • _FULLTEXT_PDF_CMD_OPTIONS (par exemple -enc UTF-8) : Options d’appel de l’exécutable

Pour les DOC, PPT et XLS

• Installer Catdoc
  • Sur Ubuntu/Linux,
  • Sur Windows
• Définir les constantes correspondantes (_FULLTEXT_DOC_EXE, _FULLTEXT_DOC_CMD_OPTIONS, etc.) ou utiliser le panneau de configuration de la même manière que pour les PDF.
  • Exemples pour les DOC :
    • Exemple pour utilisation en local sous Windows define("_FULLTEXT_DOC_EXE","C:\catdoc\catdoc.exe");
    • Exemple pour utilisation sous Linux : define("_FULLTEXT_DOC_EXE","/usr/bin/catdoc");
    • Exemple d’option pour extraction de DOC au format « Windows » vers format ISO-8859-1 : define("_FULLTEXT_DOC_CMD_OPTIONS","-s cp1252 -d 8859-1 ");
  • Exemples pour les XLS :
    • Exemple pour utilisation en local sous Windows define("_FULLTEXT_XLS_EXE","C:\catdoc\xls2csvt.exe");
    • Exemple pour utilisation sous Linux : define("_FULLTEXT_XLS_EXE","/usr/bin/xls2csvt");
    • Exemple d’option pour extraction de .XLS au format « Windows » vers format ISO-8859-1 : define("_FULLTEXT_XLS_CMD_OPTIONS","-s cp1252 -d 8859-1 ");
  • Exemples pour les PPT :
    • Exemple pour utilisation en local sous Windows define("_FULLTEXT_PPT_EXE","C:\catdoc\catpp.exe");
    • Exemple pour utilisation sous Linux : define("_FULLTEXT_PPT_EXE","/usr/bin/catpp");

Pour les ODT, DOCX, PPTX, XLSX

• Les « extracteurs » utilisent des fonctions et des classes PHP fournit avec le plugin (nécessite PHP 5.2 au minimum, ainsi que l’option -enable-zip).
• Définir les constantes correspondantes (_FULLTEXT_ODT_EXE, _FULLTEXT_DOCX_EXE, etc.) ou utiliser le panneau de configuration pour autoriser l’indexation. Il n’y a pas de binaire ou d’option à définir (mais si vous n’utilisez pas le panneau de configuration, une constante non-nulle doit être définie).

Documents protégés

Les documents PDF et XLS protégés ne seront pas indexé et se verront affecter le statut « ptg » dans la base de données.
Une page ecrire/?exec=fulltext_document_ptg permet d’obtenir la liste de ceux-ci.
Les documents PPT et PPTX protégés ne seront pas indexés et seront renvoyés comme erreur (statut « err »).

Les documents DOC, DOCX, ODT et XLSX protégés semblent être indexés.

Suivi

Analyse des recherches

Le plugin fait un suivi de ses opérations liées à la recherche dans tmp/recherche.log ; on voit les index FULLTEXT utilisés, le temps mis pour chaque recherche et le nombre de résultats, etc.

Exemple de log :

Mar 13 15:28:42 1.2.3.4 (pid 21184) fulltext article: titre, full2
Mar 13 15:28:42 1.2.3.4 (pid 21184) fulltext auteur: nom
Mar 13 15:28:42 1.2.3.4 (pid 21184) fulltext mot: titre
Mar 13 15:28:42 1.2.3.4 (pid 21184) MATCH(t.`titre`) AGAINST ('fluor dans l\'eau \"fluor dans l\'eau\"') * 3.1
   + MATCH(t.`surtitre`,t.`titre`,t.`soustitre`,t.`chapo`,t.`descriptif`) AGAINST ('fluor dans l\'eau \"fluor dans l\'eau\"') * 1.4
   + SUM(MATCH(obj1.`nom`) AGAINST ('fluor dans l\'eau'))
   + SUM(MATCH(obj2.`titre`) AGAINST ('fluor dans l\'eau'))
    AS score
Mar 13 15:28:42 96.21.135.101 (pid 21184) recherche article (fluor dans l'eau) : 500 resultats 1.187s

Ce log indique que la table article a deux index FULLTEXT nommés titre et full2 ; que la recherche portant sur « fluor dans l’eau » donne un poids de 3,1 à la présence de ces mots dans le titre, 1,4 dans l’ensemble des champs, et 1 pour le nom d’un auteur ou d’un mot-clé lié par une jointure.

Analyse des extractions

Le plugin fait aussi le suivi des extractions de version texte des fichiers, dans tmp/extract.log.

La page de configuration du plugin ecrire/?exec=fulltext indique le nombre de documents indexés, en attente d’indexation, protégés ou en erreurs.

Configuration avancée des index FULLTEXT

Avec n’importe quel client MySQL (ou phpMyAdmin) vous pouvez aller modifier la structure des index pour affiner les réponses, en incluant ou en excluant des champs, selon vos usages.

Ceci est notamment à faire si vous utilisez Extras2 pour ajouter de nouveaux champs : il faut alors créer un index incluant ces champs, pour qu’ils soient cherchables.

Notre recommandation : supprimer le précédent index FULLTEXT de tous les champs standards, et recréer un index FULLTEXT intégrant les champs standards et les champs extras pertinents. Seuls les champs de type TEXT (ou LONGTEXT etc) peuvent faire partie d’un index FULLTEXT.

Il est aussi possible d’aller bidouiller à l’intérieur du fichier pour, par exemple :

Ajouter des pondérations aux différents index

Le code consiste en une somme des scores donnés aux articles par les différents index. La pondération par défaut est une fonction décroissante du nombre d’éléments dans l’index. Ainsi, si on a deux index sur une table, l’un portant sur le titre, et l’autre sur l’ensemble des champs texte de la table, les termes de recherche présents dans le titre auront un poids de 4 environ, tandis que les mêmes termes trouvés dans le texte ne vaudront que 1 point.

Si l’on veut modifier ces poids il est possible :
— soit de modifier cette fonction pour qu’elle soit plus (ou moins) fortement décroissante ;
— soit d’ajouter un système encore plus compliqué avec des options de configuration ;
— soit d’ajouter un index. Par exemple, pour survaloriser les champs surtitre, sous-titre et chapo par rapport au champ texte, créer un index FULLTEXT supplémentaire avec la commande ci-dessous :

ALTER TABLE spip_articles ADD FULLTEXT `titrailles`
   (`surtitre`,`titre`,`soustitre`,`chapo`); 

Cela dit, les réglages proposés par défaut marchent très bien pour nous, essayez-les :-)

Éliminer de la recherche tout un ensemble d’éléments

Scénario : notre base de données comporte toutes les archives d’un journal depuis 1920. Si l’on veut faire une recherche qui limite aux seuls articles récents, il n’est pas raisonnable de demander à inc/rechercher.php de ramener suffisamment d’articles pour ensuite en éliminer 90 % avec un critère {date>1980} dans la boucle. On peut alors envisager d’ajouter « en dur » un critère WHERE supplémentaire au niveau de la requête MySQL de inc/rechercher.php.
-  pour ce faire, on pourra, par exemple, réduire le corpus de recherche pour la table spip_articles, en ajoutant dans mes_options.php une ligne :

define('_FULLTEXT_WHERE_article', ' t.date>"1980" ');

bien noter qu’il ne faut pas le ’s’ final dans le nom de la table, ainsi que l’utilisation des 2 types de quotes (’ et ") dans la définition de la clause WHERE.

Permettre à l’utilisateur de déterminer le corpus de recherche

On peut vouloir donner la possibilité à l’utilisateur de fixer la date de départ de sa recherche (lui permettre de ne chercher qu’à partir d’une date qu’il fixe lui-même).
Rien de plus simple.

-  Commençons par ajouter un input dans notre formulaire de recherche (formulaires/recherche.html`) :

<input type="text" class="text" size="5" name="recherche_date" id="recherche_date"[ value="(#ENV{recherche_date})"] />

-  Puis, dans notre fichier recherche_fonctions.php :

if ( _request('recherche_date') && preg_match('/\d{4}/', _request('recherche_date')) ) {
    $limite = _request('recherche_date');
    define('_FULLTEXT_WHERE_article', 't.date>"' . $limite . '"');
    define('_FULLTEXT_WHERE_rubrique', 't.date>"' . $limite . '"');
    define('_FULLTEXT_WHERE_document', 't.date>"' . $limite . '"');
}

Ceci limitera le corpus de recherche (l’ensemble des données dans lequel s’effectuera la recherche) pour les articles, rubriques et documents aux seuls éléments dont la date (en l’occurence l’année de publication) est strictement supérieure à celle fournie par l’utilisateur.

Étendre la recherche aux mots de 3 lettres

Par défaut MySQL FULLTEXT indexe les mots de quatre lettres ou plus. Pour étendre la recherche aux mots de 3 lettres ou plus, il faut modifier la config du serveur (/etc/mysql/my.cnf sous Debian), et ajouter les deux éléments suivants :

[mysqld]
ft_min_word_len=3
[myisamchk]
ft_min_word_len=3

Attention après avoir effectué cette manipulation il est impératif de reconstruire tous les index FULLTEXT de toutes les bases de données présentes sur le serveur, cf. http://dev.mysql.com/doc/refman/5.1....
Une méthode en ligne de commande (il faut être root) :

# /etc/init.d/mysql stop
Stopping MySQL database server: mysqld.
# myisamchk --recover /var/lib/mysql*/*MYI
... (quelques secondes ou minutes) ...
# /etc/init.d/mysql start

Fulltext et le plugin champs extras

Si vous avez crée des champs extras indexés.
Pensez à supprimer les index existants sur les tables où vous avez créés les champs pour ensuite les régénérer en incluant les champs nouvellement crées.

Exemples d’utilisation

Suggérer des réponses aux questions sur discuter.spip.net

Lire l’article « Forum.spip.org comme base de connaissances » sur SPIP Blog

et aussi

... à vous de jouer !