Format de sortie

L'unité documentaire est un concept important pour SDX. En effet, il s'agit de la plus petite unité d'information XML que SDX peut retourner en résultat de recherche ou afficher. La plupart du temps, une unité documentaire (et une seule) est issue d'un document XML indexé ; toutefois, il est possible de produire plusieurs unités documentaires à partir du même document XML, lorsqu'on fait appel à la fragmentation des documents. L'inverse n'est pas vrai toutefois : il n'est pas possible de créer une unité documentaire à partir de plusieurs documents XML.

Pour identifier une unité documentaire, le format de sortie préconise un élément XML sdx:document qui peut avoir différents attributs. Voici un premier exemple simple :

  <sdx:document id="doc01">
  </sdx:document>

Cet exemple définit une unité documentaire dont l'identifiant est doc01. A noter que cet exemple est parfaitement valide ; SDX va pouvoir indexer le document correspond et lui attribuer un identifiant. Ce document sera cherchable en utilisant les champs internes à SDX.

Cet exemple est suffisant lorsqu'on peut trouver un identifiant aux documents lors de l'exécution du pipeline d'indexation, ce qui n'est pas toujours le cas. Pour parer à cette éventualité, SDX vous permet de préciser qu'un identifiant devra être automatiquement généré lors de l'indexation du document. Voici un exemple qui utilise cette fonctionnalité :

  <sdx:document generateId="true">
  </sdx:document>

Dans cet exemple, l'identifiant du document n'est pas précisé, mais on demande à SDX d'utiliser un générateur d'identifiants pour en attribuer un au document. Ce générateur est soit celui par défaut de SDX (classe fr.gouv.culture.sdx.documentbase.DefaultIDGenerator), soit celui qui a été défini dans la configuration de la base de documents (fichier application.xconf) à l'aide de l'élément idGenerator.

Un troisième exemple va nous permettre d'exprimer le dernier aspect de l'identifiant des unités documentaires, soit la possibilité de surcharger ou pas un identifiant qui aura été fourni extérieurement, en général par un appel à l'API Java sur l'objet fr.gouv.culture.sdx.document.IndexableDocument qui est en cours d'indexation. Voici un exemple d'utilisation :

  <sdx:document id="doc01" overrideId="false">
  </sdx:document>

Dans cet exemple, on spécifie un identifiant, mais si jamais un identitiant a été fourni préalablement au document, il ne sera pas utilisé, l'original sera conservé. A noter que l'attribut overrideId peut s'utiliser de pair avec l'attribut generateId.

Enfin, il est possible de préciser l'entrepôt où SDX placera le document XML. Rappelons que SDX stocke les documents indexés dans des entrepôts, qui sont utilisés par les bases de documents de manière transparente. Lorsqu'on indexe un document ou un lot de documents, on doit spécifier un entrepôt (ou demander d'utiliser l'entrepôt par défaut), mais il est possible de modifier dynamiquement l'entrepôt à utiliser au moment de l'indexation. Pour ce faire, il s'agit simplement d'utiliser un attribut repo et de lui donner comme valeur l'identifiant d'un entrepôt déclaré dans le fichier application.xconf. Voici un exemple :

  <sdx:document id="doc01" repo="files">
  </sdx:document>

Selon cet exemple, l'unité documentaire sera conservée dans l'entrepôt files, peu importe ce qui a été demandé lors de l'indexation.

On peut également fournir un facteur de pondération de la pertinence pour le document. Dans ce cas, le document sera considéré comme étant a priori plus ou moins important que les autres documents lorsque le moteur de recherche Lucene calcule les indices de pertinence par rapport à une requête de recherche. La valeur pivot est de 1.0, une valeur moindre diminue la pertinence alors qu'une valeur supérieure l'augmente.

Pour spécifier un facteur de pondération de la pertinence, il suffit d'ajouter un attribut boost à l'élément sdx:document et à lui donner une valeur qui est un nombre réel, par exemple :

  <sdx:document id="doc01" boost="2.0">
  </sdx:document>

	Note
	Les facteurs de pondération sont disponibles depuis la version 2.3 de SDX. Si vous les spécifiez mais utilisez une version antérieure de SDX, ils sont tout simplement ignorés.

Le modèle de recherche implanté par SDX (pour l'instant il s'agit du seul modèle, d'autres pourraient être ajoutés ultérieurement) utilise des champs dans lesquels s'effectue la recherche. La principale tâche du processus d'indexation (et donc de sa sortie) est de préciser les champs utilisés et leur contenu.

Le format de sortie prévoit un élément sdx:field pour spécifier un champ et son contenu Il doit être utilisé de la sorte :

  <sdx:document id="doc01">
    <sdx:field name="auteur">Hugo, Victor</sdx:field>
    <sdx:field name="auteur">Zola, Emile</sdx:field>
    <sdx:field name="titre">Moi, écrivain</sdx:field>
  </sdx:document>

Dans cet exemple deux occurrences du champ auteur sont définis et une occurrence du champ titre. Ces champs doivent être déclarés dans le fichier application.xconf. L'ordre des champs n'a pas d'importance mais les éléments doivent être à l'intérieur de l'élément sdx:document. L'attribut name doit être utilisé pour identifier le nom du champ ; l'attribut code peut également être employé, mais cet usage est à déconseillé et le support de cet attribut pourrait être supprimé dans une version ultérieure de SDX.

Si vous avez déclaré un champ de type xml, alors vous pouvez donner comme valeur à ce champ une structure XML quelconque, en autant qu'elle ne contienne aucun élément qui soit dans l'espace de nom (namespace) SDX. Par exemple, vous pouvez sortir cette structure :

  <sdx:document id="doc01">
    <sdx:field name="contexte">
      <parents>
        <parent id="001"/>
        <parent id="003"/>
      </parents>
    </sdx:field>
    <sdx:field name="communes">
      <communes>
        <commune insee="33001" latitude="0" longitude="1">Bordeaux</commune>
        <commune insee="24001" latitude="1" longitude="0">Périgueux</commune>
      </communes>
    </sdx:field>
  </sdx:document>

L'intérêt d'un tel champ est bien sûr de pouvoir récupérer ces données structurées lors de la présentation des résultats de recherche, et donc de permettre une mise en forme ou une exploitation plus souple de ces données. Nous rappelons que pour un tel type de champ, les données ne sont pas indexées, seulement stockées, alors elles ne sont pas cherchables, et encore moins cherchables en fonction de leur structure. Le contenu XML que vous spécifiez peut être quelconque, en autant que ça corresponde à une entité XML bien formée, c'est-à-dire que tout balise ouverte est également fermée. Mais vous pouvez avoir plus d'un élément racine, avoir du texte à la racine, etc.

	Note
	Les champs de type xml sont disponibles depuis la version 2.3 de SDX. Si vous placez du contenu XML dans un champ de type unindexed normal, disponible dans les versions antérieures, les balises seront supprimées, mais le texte conservé.

On peut également ajouter un facteur de pondération de la pertinence pour un champ. Lors du calcul de pertinence d'un document par rapport à une requête de recherche, le moteur de recherche Lucene considère que les champs ont, a priori, une même pondération, par défaut égale à 1.0. Si jamais au moment de l'indexation on souhaite pondérer la pertinence d'un champ, par exemple pour indiquer que le champ titre devrait être plus important dans le calcul de pertinence, on peut le spécifier en ajoutant un attribut boost à l'élément sdx:field et en lui donnant une valeur de type nombre réel. Par exemple :

  <sdx:document id="doc01">
    <sdx:field name="title" boost="2.0"/>
  </sdx:document>

Dans cet exemple, le champ title est pondéré de manière positive (la valeur est plus grande que 1.0), ce qui signifie qu'on indique que ce champ est plus important que la moyenne.

	Note
	Les facteurs de pondération sont disponibles depuis la version 2.3 de SDX. Si vous les spécifiez mais utilisez une version antérieure de SDX, ils sont tout simplement ignorés.

Les documents attachés doivent également être spécifiés dans le processus d'indexation et ont donc une représentation dans le format de sortie. D'autres informations à ce sujet sont également fournies dans une autre partie de la documentation, nous allons simplement ici mentionner l'ensemble des éléments d'information qui peuvent être spécifiés, et ce à l'aide de l'exemple suivant :

  <sdx:document id="doc01">
    <sdx:field name="titre">Un essai</sdx:field>
    <sdx:attachedDocument id="img0002" overrideId="false" repo="atts"  
      url="images/image0002.jpg" mimetype="image/jpeg"/>
    <sdx:attachedDocument generateId="true" 
      url="http://www.images.org/images/image0012.jpg" mimetype="image/jpeg"/>
    <sdx:attachedDocument attid="img0022" 
      url="images/image0022.jpg" mimetype="image/jpeg"/>
  </sdx:document>

De ces exemples, il faut retenir ceci :

Dans le cas où un document XML est fragmenté en plusieurs unités documentaires, il est possible de spécifier le contenu d'un fragment dans le format de sortie du processus d'indexation. En fait, SDX va considérer que tout le XML à l'intérieur d'un sdx:document et qui n'appartient pas à l'espace de nom sdx sera le contenu du fragment ; le développeur de l'application doit faire en sorte que ce contenu soit un document XML bien formé, en prenant garde notamment de n'avoir qu'un seul élément hiérarchique supérieur.

Les fragments de documents sont expliqués ailleurs, mais nous montrons ici un exemple de leur déclaration à l'issue du processus d'indexation :

  <sdx:document id="doc01">
    <sdx:field name="titre">Introduction à XML</sdx:field>
    <sdx:field name="auteur">Michard, Alain</sdx:field>
    <sdx:document id="doc01-ch01">
      <sdx:field name="titre">Qu'est-ce que XML</sdx:field>
      <section id="ch01">
        <para>Comment définir XML ? Ce n'est pas facile...</para>
      </section>
    </sdx:document>
  </sdx:document>

Dans cet exemple, nous avons un document principal (dont le contenu est déterminé à l'extérieur, comme entrée au processus d'indexation) avec deux champs, de même qu'au fragment de document avec un champ et un contenu XML dont l'élément hiérarchique supérieur est section. On voit que pour créer des fragments de documents, il suffit simplement d'imbriquer des éléments sdx:document les uns à l'intérieur des autres (y compris sur plusieurs niveaux) et dans le cas des fragments il faut aussi ajouter leur contenu.

Le rôle de la fragmentation et ce qu'en fait SDX est expliqué ailleurs.

L'utilisation d'un thésaurus lors de l'indexation est expliquée ailleurs, mais nous allons ici donner un exemple du format de sortie à utiliser lorsqu'on veut faire appel à cette fonctionnalité. Si l'on veut que SDX ajoute des termes génériques et spécifiques d'un terme spécifié dans un champ, nous pouvons procéder ainsi :

  <sdx:document id="doc01">
    <sdx:field name="lieu">
      Gironde
      <sdx:expandField>
        <sdx:relation type="bt" depth="10" th="thes"/>
        <sdx:relation type="nt" depth="1" th="thes"/>
      </sdx:expandField>
    </sdx:field>
  </sdx:document>

Le thésaurus utilisé sera celui dont l'identifiant est thes, et les termes génériques (jusqu'à 10 niveaux au-dessus du terme Gironde seront ajoutés, de même que les termes spécifiques mais à un seul niveau.