Protocole SRU: Formuler une recherche

Le protocole SRU permet de formuler des recherches via l’opération « SearchRetrieve ».  Le parametrage de l’URL de recherche, tout comme la structure de la réponse répondent à une norme très précise : Norme 1.1 et Norme 1.2. De même la formulation de l’équation de recherche (« query ») est basée sur le langage CQL (Contextual Query Langage).

Paramètres de la requête

 
Liste et description des paramètres
Nom Obligatoire / Facultatif Description
operation
(opération)
Obligatoire
 
Comprend la chaîne de caractères « searchRetrieve ».
version
(version)
Obligatoire
 
Désigne la version de la requête et vaut déclaration par le client qu’il désire une réponse dans cette version ou une version inférieure.
query
(recherche)
Obligatoire
 
L’équation de recherche exprimée en CQL (Code Query Language) que doit traiter le serveur.
startRecord
(premier enregistrement)
Facultatif
 
Désigne la position du premier enregistrement de la réponse au sein de l’ensemble des enregistrements répondant à la recherche. La première position dans l’ensemble est 1. La valeur indiquée doit obligatoirement être supérieure à 0. La valeur par défaut est 1.
maximumRecords
(nombre maximal d’enregistrements)
Facultatif
 
Le nombre d’enregistrements que le serveur doit envoyer en réponse à la requête. La valeur indiquée doit obligatoirement être un entier positif. La valeur par défaut est déterminée par le serveur. Le serveur a le droit d’envoyer un moins grand nombre d’enregistrements, par exemple s’il y en a moins qui réponde à la recherche que spécifié par la requête, mais il ne doit pas envoyer un plus grand nombre d’enregistrements.
recordPacking
(formalisme des enregistrements)
Facultatif
 
Comprend une chaîne de caractères qui indique comment les enregistrements doivent être encodés (document XML ou codage URL). Les valeurs définies sont « string » et « xml ». La valeur par défaut est « xml ».
recordSchema
(schéma des enregistrements)
Facultatif
 
Désigne la version de la requête et vaut déclaration par le client qu’il désire une réponse dans cette version ou une version inférieure.
recordXPath
(inutilisé dans la version 1.2)
 
 
  
resultSetTTL
 
Facultatif
 
Définit la durée (exprimée en secondes) pendant laquelle le client requiert que l’ensemble répondant à la requête soit maintenu. Le serveur a le droit de ne pas respecter ce critère. La valeur par défaut est déterminée par le serveur.
sortKeys
(inutilisé dans la version 1.2)
 
 
  
stylesheet
 
Facultatif
 
Déclare l’URL d’une feuille de style. Le client requiert que cette URL soit incluse dans la réponse.
extraRequestData
 
Facultatif
 
Donne des informations complémentaires au serveur pour procéder
(cf. Extensions).
Exemple : Recherche du mot « dinosaur »
http://z3950.loc.gov:7090/voyager?version=1.1&operation=searchRetrieve&query=dinosaur&maximumRecords=5&recordSchema=dc
 Cet exemple définit la requête adressée au serveur de la Bibliothèque du Congrès (http://z3950.loc.gov:7090/voyager) : la requête suit la version 1.1 (la réponse doit être de la même version) et demande la recherche (opération searchRetrieve) du terme « dinosaur » (query=dinosaur) en précisant que la réponse doit contenir au maximum cinq enregistrements (maximumRecords=5) et que chaque enregistrement (record) soit conforme au  schéma « dc » (ici abréviation de Dublin Core).


Formulation de l’équation de recherche (query) – Index et contextes

La formulation de l’équation de recherche proprement dite associée au paramètre « query », est basée sur le langage CQL (Contextual Query Langage).

Index, clauses de recherche, relations et opérateurs

Le protocole SRU permet à chaque serveur de définir  ses « index » de recherche. Par exemple, un index ‘title’ pour des recherches Titre ou ‘author’ pour des recherches Auteur.
La syntaxe des équations de recherche (query) qui permettent d’interroger ces index est définit par le langage CQL:  
  • Une clause de recherche consiste en un index, une relation (‹all›, ‹any›, ‹adj›, etc.)et un terme cherché. Par exemple : author all «victor hugo».
  • On peut combiner plusieurs clauses de recherche par des and, or, not, etc. . Par exemple : (author all «victor hugo») and (title all « les misérables»).
La syntaxe complète est décrite sur la page CQL Query syntax.

Usage des contextes dans le protocole SRU 

Le protocole SRU permet via le langage CQL de préciser des « contextes » (cf. CQL Context Sets).
Exemple 1 : 
Les formats Marc21 et Dublin Core sont deux formats utilisés par une bibliothèque. Ils vont former deux « ensembles de contexte » (context set) et chacun de ces formats pourra être interrogé selon ses caractéristiques propres selon le protocole CQL.
La requête « rechercher tous les enregistrements dont le champ ‘245$a’ contient le mot ‘France’ » est comparable à la requête « rechercher tous les enregistrements dont l’élément ‘title’ contient le mot ‘France’ » ; ces deux requêtes doivent préciser dans quel « contexte » elles interrogent les index Marc21 ‘245$a’ ou Dublin Core ‘title’.
Un index SRU nommé ‘title’, préfixé par le contexte ‘marc21’ (‘marc21.title’) ou par le contexte ‘dc’ (‘dc.title’), permettra de préciser dans quel « contexte » doit s’exécuter la requête.
Exemple 2 :
La BnF, dans son implémentation du protocole SRU, utilise deux contextes : bib et aut qui lui permettent de préciser l’usage des index.dans  le contexte des notices bibliographiques ou d’autorité. Ainsi, l’index SRU de la BnF ‘anywhere’ préfixé par le contexte ‘bib’  (bib.anywhere) effectuera une recherche n’importe où dans les notices bibliographiques, alors que préfixé par le contexte ‘aut’ (aut.anywhere), il effectuera une recherche n’importe où dans les notices d’autorité.

Structure globale de la réponse

La réponse à une requête SRU searchRetrieve request est un document XML.
La colonne « Type » du tableau ci-dessous indique soit un type XML Schema (« xsd: ») [types définis dans les recommandations XML Schema du W3C (version originale en anglais)], soit un type défini à l’intérieur du schéma.
 
Liste et description des éléments fournis par le document xml
nom type Obligatoire / Facultatif description
version
(version)
xsd:string
 
Obligatoire
Version de la réponse. Celle ci doit obligatoirement être inférieure ou égale à la version demandée par le client.
numberORecords
(nombre d’enregistrements)
xsd:integer
 
Obligatoire
Nombre d’enregistrements répondant à la recherche. Si la recherche échoue, ce nombre doit obligatoirement être 0.
resultSetld
(identifiant de l’ensemble de résultats)
xsd:string
 
Facultatif
Identifiant de l’ensemble de résultats qui a été créé par l’exécution de la recherche.
resultSetldleTime
(durée de maintenance de l’ensemble de résultats)
xsd:integer
 
Facultatif
Intervalle de temps (exprimé en secondes) après lequel l’ensemble de résultats créé par l’exécution de la recherche est détruit. L’ensemble de résultats peut aussi cesser d’être disponible avant le temps écoulé.
records
(enregistrements)
xsd:liste d’éléments record
 
Facultatif
Liste d’enregistrements correspondant à la recherche, ou diagnostics remplaçant les enregistrements.
nextRecordPosition
(position de l’enregistrement suivant)
xsd:integer
 
Facultatif
Position dans l’ensemble des résultats qui suit celle du dernier enregistrement de la réponse. S’il n’y a pas d’enregistrement suivant, ce champ doit obligatoirement être omis.
diagnostics
(diagnostics)
xsd:liste d’éléments diagnostic
 
Facultatif
Liste de diagnostics d’erreurs générés pendant l’exécution d’une recherche.
extraReponseData
(données hors réponse)
xmlfragment
 
Facultatif
Information supplémentaire dans la réponse du serveur.
echoedSearch
RetrieveRequest
(répétition de la requête searchRetrieve)
echoedSearch
RetrieveRequest
 
Facultatif
Paramètres de la requête répétés par le serveur dans un formalisme XML [ce paramètre facultatif dans SRU correspond à un principe de base dans le protocole OAI PMH].

Structure des enregistrements (« records ») de la réponse

Dans la réponse SRU, tous les enregistrements (records) sont communiqués dans un formalisme XML (Il n’est pas spécifié que les enregistrements sont stockés en XML. Les enregistrements qui ne sont pas nativement en XML doivent être transformés en XML avant d’être communiqués). Il est possible d’exprimer les enregistrements dans la réponse comme une chaîne de caractères simple ou comme du XML embarqué. Si un enregistrement est communiqué dans un formalisme XML, il doit obligatoirement être bien formé et il doit être valide selon le schéma d’enregistrement déclaré.


Le paramètre « records » dans une réponse est une liste d’éléments « record », dont chacun contient soit un enregistrement, soit un diagnostic de remplacement, expliquant pourquoi tel enregistrement n’a pas pu être communiqué. Si le schéma d’enregistrement est inconnu ou si l’enregistrement ne peut être mis en forme selon ce schéma, alors le serveur doit obligatoirement répondre avec un diagnostic.

 

Structure d’un enregistrement
Nom type Obligatoire / Facultatif Description
recordSchema
(schéma de l’enregistrement
xsd:string
 
Obligatoire
L’identifiant URI du schéma XML dans lequel l’enregistrement est encodé. Même si la requête peut utiliser l’abréviation déclarée par le serveur [ndt: par exemple « dc » à la place de « info:srw/schema/1/dc-v1.1 » pour le serveur de la Bibliothèque du Congrès], la réponse doit toujours indiquer l’URI complet. (cf. Record Schemas sur le site de la Bibliothèque du Congrès).
recordPacking
(formalisme de l’enregistrement)
xsd:string
 
Obligatoire
Le formalisme de l’enregistrement utilisé dans la section recordData (données de l’enregistrement), tel que spécifié par le client ou la valeur par défaut.
recordData
(données de l’enregistrement)
stringOrXmlFragment
 
Obligatoire
L’enregistrement lui-même, soit comme chaîne de caractère, soit comme fichier XML inclus.
recordIdentifier
(identifiant de l’enregistrement)
uniquement dans la version 1.2
xsd:string
 
Facultatif en version 1.2
Interdit en version 1.1
Un identifiant attribué à l’enregistrement, par lequel celui-ci pourra être désigné sans ambiguité et récupéré lors d’une opération ultérieure. Par exemple par l’index « rec.identifier » du CQL.
recordPosition
(position de l’enregistrement)
xsd:positiveInteger
 
Facultatif
La position de l’enregistrement au sein de l’ensemble des résultats (cf Result Sets sur le site de la Bibliothèque du Congrès).
extraRecordData
(données hors enregistrement)
xmlfragment
 
Facultatif
Toute information supplémentaire que le serveur doit transmettre avec l’enregistrement (cf. Extensions sur le site de la Bibliothèque du Congrès).

 

Exemple d’enregistrement (record) au format Dublin Core (recordSchema) exprimé dans le formalisme XML (recordPacking)
 

Précision sur le paramêtre recordPacking :
Pour que les enregistrements qui ne sont pas bien formatés ne créent pas d’erreur sur l’ensemble de la réponse [ndt : le message de réponse doit obligatoirement être un document XML bien formé et valide], il est possible de demander qu’ils soient transformés en une simple chaîne de caractères avec les signes « < », « > » et « & » en caractères d’échappement, sous la forme des entités HTML. De plus, il se peut que certains outils soient incapables de faire la distinction entre le XML des enregistrements et le document XML qui constitue la réponse.
Pourtant, il se peut que certains clients préfèrent que les enregistrements soient communiqués en XML de façon à les traiter directement avec une feuille de style qui mette en forme les enregistrements et, éventuellement aussi, l’interface pour l’utilisateur.
La distinction est faite par le paramètre « recordPacking » :

  • si la valeur est « string », le serveur doit utiliser les caractères d’échappement avant de communiquer les enregistrements ;
  • si la valeur est « xml », il doit insérer les données en XML directement dans la réponse.

Dans les deux cas, les données sont communiquées à l’intérieur du champ « recordData ».
Si le serveur ne peut pas répondre à la requête conformément au formalisme spécifié, alors il doit renvoyer un « diagnostic ».


Exemple de réponse avec recordPacking=string  : http://z3950.loc.gov:7090/voyager?version=1.1&operation=searchRetrieve&query=dinosaur&recordPacking=string&maximumRecords=10&recordSchema=dc