À venir dans la version 5 de l’API

Chers utilisateurs et utilisatrices,
Depuis plusieurs semaines, nous avons entamé un processus de mise à jour de notre moteur de recherche Elasticsearch, de la version 1.7 à la version 5.3.
Cette mise à jour étant un grand saut (nous avons « sauté » la version 2.x du logiciel), elle apporte un grand nombre de nouveautés et de changements. Un gain en performance est attendu, mais certaines fonctionnalités sont dépréciées ou grandement modifiées.
Nous faisons de notre mieux pour minimiser les impacts au niveau de l’API et éviter de casser la compatibilité ascendante, mais ça ne sera pas possible à tous les niveaux. L’objectif de ce billet et de vous présenter les changements prévus

Au niveau des facettes

L’API ISTEX propose la création de facette sur la majorité des champs disponibles. Certains champs comme le DOI sont interdits car :

• le nombre d’items renvoyé par cette facette pouvait être immense
• une facette sur un champ qui est censé avoir une valeur unique pour chaque document n’a pas beaucoup d’intérêt en soi

Pour des raisons de performance et de consommation mémoire, Elasticsearch 5 ne permet plus de renvoyer la totalité des valeurs possibles d’une facette.
Par conséquent, l’API ISTEX ne pourra plus répondre à ce besoin, alors que c’était possible avec le paramètre facet=nom_du_champ[*]. Nous avons été obligés de fixer une limite haute à 1000 « buckets » renvoyés au maximum. L’utilisation de l’astérisque est toujours autorisée, mais le nombre de buckets renvoyés sera automatiquement limité à 1000.

Pagination et parcours des résultats

Toujours pour des raisons de performance, la version 5 d’Elasticsearch introduit une limitation à la fonctionnalité de pagination « simple » (utilisation des paramètres from et size). Il n’est désormais plus possibles d’accéder aux résultats au-delà de la 10 000ème réponse (from + size doit obligatoirement être inférieur ou égal à 10 000).
En contrepartie, pour parcourir de très grands ensembles de résultats, Elasticsearch met à disposition une fonctionnalité de scrolling, qui permet un parcours pas à pas, sans possibilité de retour arrière. Cette fonctionnalité étant vraiment faite pour ce type de besoin, nous l’avons implémentée au niveau de l’API, ce qui vous permettra de continuer à extraire des sous-corpus, moyennant une adaptation de vos scripts ou programmes.
Les détails sur cette nouvelle fonctionnalité sont disponibles sur la nouvelle documentation.
De notre côté, nous devrons également adapter le script istex-api-harvester, ainsi que le démonstrateur, car afficher un lien vers la dernière page n’est plus possible⁽¹⁾.

Tri sur les champs textuels analysés

Une troisième limitation est introduite, au niveau du tri des documents.
Pour rappel, il était possible jusqu’à présent d’effectuer des tris sur n’importe quel champ, y compris sur les champs de type texte, qu’ils soient analysés ou non.
Dans le cas des champs analysés, cela aboutissait à des comportements surprenants pour les non-initiés. Par exemple, si on considère les 3 titres suivants :

• « La guerre des étoiles »
• « L’empire contre-attaque »
• « Le retour du Jedi »

Un tri sur le titre, pour les 3 documents correspondant donnait l’ordre suivant :

1. « L’empire contre-attaque« 
2. « La guerre des étoiles »
3. « Le retour du Jedi »

L’explication est qu’il s’agissait d’un tri alphanumérique sur chaque token de ces titres, et qu’il fallait donc raisonner au niveau du token. En général, il était donc plus pertinent de trier sur la version brute du champ titre.
Dorénavant, le tri sur ces champs analysés n’est tout simplement plus possible. Nous envisageons donc de répercuter cette régression au niveau de l’API. C’est pourquoi nous vous invitons à nous signaler si ce changement vous impacte, auquel cas nous essaierons de trouver une solution convenable.
Bien entendu, il sera toujours possible de trier sur les champs « non analysés », qui sont indexés dans leur ensemble.

C’est pour quand ?

L’ensemble de ces changements n’est pas encore disponible en production, mais testable sur https://api-integ.istex.fr. Tout y fonctionne, sauf l’accès aux documents (XML, MODS, TEI, PDF, ZIP, etc).
Étant donné que nous allons casser la rétro-compatibilité sur les points sus-cités, nous pensons vous laisser un délai de 2 semaines environ avant mise en production, ce qui nous amène à la fin du mois d’avril. En fonction de vos retours et de vos besoins, nous pourrons éventuellement rediscuter ce point.
Nous vous souhaitons une bonne consultation. N’hésitez pas à nous faire part de vos retours dans les commentaires, vos remarques nous sont très précieuses !
Claude, pour l’équipe API

(1) Vous constaterez que c’est en fin de compte la manière de procéder de tous les « gros » moteurs de recherche, Google y compris.

• changement de version
• v5