<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (C) 2000-2010  Ministere de la culture et de la communication (France), AJLSM
See LICENCE file
-->
<!DOCTYPE webpage PUBLIC "-//Norman Walsh//DTD Website V2.1b1//EN" "../../../dtd/website.dtd" [
<!ENTITY attached SYSTEM "attaches.xml" NDATA XML>
<!ENTITY champs-sdx SYSTEM "champs-sdx.xml" NDATA XML>
<!ENTITY entrepot SYSTEM "../introduction/entrepots.xml" NDATA XML>
<!ENTITY fragmentation SYSTEM "fragmentation.xml" NDATA XML>
<!ENTITY pipeline SYSTEM "pipeline.xml" NDATA XML>
<!ENTITY schema-index SYSTEM "../../schemas/sdx-document-indexation.xsd" NDATA XML>
<!ENTITY schema-xconf SYSTEM "../../schemas/application-xconf.xsd" NDATA XML>
<!ENTITY thesaurus SYSTEM "thesaurus.xml" NDATA XML>
]>
<webpage id="indexation_format"> 
  <head> 
	 <title>Format de sortie</title> 
	 <titleabbrev>Format de sortie</titleabbrev> 
	 <author> 
		<firstname>Martin</firstname> 
		<surname>Sévigny</surname> 
		<affiliation> 
		  <orgname>AJLSM</orgname> 
		</affiliation> 
	 </author> 
	 <revhistory> 
		<revision> 
		  <revnumber>1.0</revnumber> 
		  <date>2004-08-19</date> 
		</revision> 
	 </revhistory> 
  </head> 
  <para>Peu importe la complexité d'un <olink targetdocent="pipeline"><emphasis>pipeline</emphasis> d'indexation</olink>, avec une ou plusieurs étapes, des transformations simples ou faisant appel à des informations externes, le résultat (c'est-à-dire la sortie de la dernière étape de transformation) devra toujours être le même, c'est-à-dire un document XML qui respecte un <olink targetdocent="schema-index">schéma particulier</olink>. Ce schéma constitue la référence, mais nous allons essayer de présenter les principaux concepts ici.</para><section><title>L'unité documentaire, son identifiant et son stockage</title><para>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 <olink targetdocent="fragmentation">fragmentation des documents</olink>. L'inverse n'est pas vrai toutefois : il n'est pas possible de créer une unité documentaire à partir de plusieurs documents XML.</para><para>Pour identifier une unité documentaire, le format de sortie préconise un élément XML <sgmltag class="element">sdx:document</sgmltag> qui peut avoir différents attributs. Voici un premier exemple simple :</para><programlisting>
  &lt;sdx:document id="doc01"&gt;
  &lt;/sdx:document&gt;
</programlisting><para>Cet exemple définit une unité documentaire dont l'identifiant est <sgmltag class="attvalue">doc01</sgmltag>. 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 <olink targetdocent="champs-sdx">champs internes à SDX</olink>.</para><para>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é :</para><programlisting>
  &lt;sdx:document generateId="true"&gt;
  &lt;/sdx:document&gt;
</programlisting><para>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 <literal>fr.gouv.culture.sdx.documentbase.DefaultIDGenerator</literal>), soit celui qui a été défini dans la configuration de la base de documents (fichier <filename>application.xconf</filename>) à l'aide de l'élément <sgmltag class="element">idGenerator</sgmltag>.</para><para>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 <literal>fr.gouv.culture.sdx.document.IndexableDocument</literal> qui est en cours d'indexation. Voici un exemple d'utilisation :</para><programlisting>
  &lt;sdx:document id="doc01" overrideId="false"&gt;
  &lt;/sdx:document&gt;
</programlisting><para>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 <sgmltag class="attribute">overrideId</sgmltag> peut s'utiliser de pair avec l'attribut <sgmltag class="attribute">generateId</sgmltag>.</para><para>Enfin, il est possible de préciser l'<olink targetdocent="entrepot">entrepôt</olink> 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 <sgmltag class="attribute">repo</sgmltag> et de lui donner comme valeur l'identifiant d'un entrepôt déclaré dans le fichier <filename>application.xconf</filename>. Voici un exemple :</para><programlisting>
  &lt;sdx:document id="doc01" repo="files"&gt;
  &lt;/sdx:document&gt;
</programlisting><para>Selon cet exemple, l'unité documentaire sera conservée dans l'entrepôt <literal>files</literal>, peu importe ce qui a été demandé lors de l'indexation.</para><para>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.</para><para>Pour spécifier un facteur de pondération de la pertinence, il suffit d'ajouter un attribut <sgmltag class="attribute">boost</sgmltag> à l'élément <sgmltag class="element">sdx:document</sgmltag> et à lui donner une valeur qui est un nombre réel, par exemple :</para><programlisting>
  &lt;sdx:document id="doc01" boost="2.0"&gt;
  &lt;/sdx:document&gt;
</programlisting><note><para>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.</para></note></section><section><title>Les champs</title><para>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 <emphasis>champs</emphasis> 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.</para><para>Le format de sortie prévoit un élément <sgmltag class="element">sdx:field</sgmltag> pour spécifier un champ et son contenu Il doit être utilisé de la sorte :</para><programlisting>
  &lt;sdx:document id="doc01"&gt;
    &lt;sdx:field name="auteur"&gt;Hugo, Victor&lt;/sdx:field&gt;
    &lt;sdx:field name="auteur"&gt;Zola, Emile&lt;/sdx:field&gt;
    &lt;sdx:field name="titre"&gt;Moi, écrivain&lt;/sdx:field&gt;
  &lt;/sdx:document&gt;
</programlisting><para>Dans cet exemple deux <emphasis role="italic">occurrences</emphasis> du champ <literal>auteur</literal> sont définis et une occurrence du champ <literal>titre</literal>. Ces champs doivent être déclarés dans le fichier <filename>application.xconf</filename>. L'ordre des champs n'a pas d'importance mais les éléments doivent être à l'intérieur de l'élément <sgmltag class="element">sdx:document</sgmltag>. L'attribut <sgmltag class="attribute">name</sgmltag> doit être utilisé pour identifier le nom du champ ; l'attribut <sgmltag class="attribute">code</sgmltag> 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.</para><para>Si vous avez déclaré un champ de type <sgmltag class="attvalue">xml</sgmltag>, 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 (<emphasis>namespace</emphasis>) SDX. Par exemple, vous pouvez sortir cette structure :</para><programlisting>
  &lt;sdx:document id="doc01"&gt;
    &lt;sdx:field name="contexte"&gt;
      &lt;parents&gt;
        &lt;parent id="001"/&gt;
        &lt;parent id="003"/&gt;
      &lt;/parents&gt;
    &lt;/sdx:field&gt;
    &lt;sdx:field name="communes"&gt;
      &lt;communes&gt;
        &lt;commune insee="33001" latitude="0" longitude="1"&gt;Bordeaux&lt;/commune&gt;
        &lt;commune insee="24001" latitude="1" longitude="0"&gt;Périgueux&lt;/commune&gt;
      &lt;/communes&gt;
    &lt;/sdx:field&gt;
  &lt;/sdx:document&gt;
</programlisting><para>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 <emphasis>entité XML bien formée</emphasis>, 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.</para><note><para>Les champs de type <sgmltag class="attvalue">xml</sgmltag> sont disponibles depuis la version 2.3 de SDX. Si vous placez du contenu XML dans un champ de type <sgmltag class="attvalue">unindexed</sgmltag> normal, disponible dans les versions antérieures, les balises seront supprimées, mais le texte conservé.</para></note><para>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 <emphasis role="italic">titre</emphasis> devrait être plus important dans le calcul de pertinence, on peut le spécifier en ajoutant un attribut <sgmltag class="attribute">boost</sgmltag> à l'élément <sgmltag class="element">sdx:field</sgmltag> et en lui donnant une valeur de type nombre réel. Par exemple :</para><programlisting>
  &lt;sdx:document id="doc01"&gt;
    &lt;sdx:field name="title" boost="2.0"/&gt;
  &lt;/sdx:document&gt;
</programlisting> <para>Dans cet exemple, le champ <emphasis role="italic">title</emphasis> 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.</para><note><para>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.</para></note></section><section><title>Les documents attachés</title><para>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 <olink targetdocent="attached">autre partie de la documentation</olink>, 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 :</para><programlisting>
  &lt;sdx:document id="doc01"&gt;
    &lt;sdx:field name="titre"&gt;Un essai&lt;/sdx:field&gt;
    &lt;sdx:attachedDocument id="img0002" overrideId="false" repo="atts"  
      url="images/image0002.jpg" mimetype="image/jpeg"/&gt;
    &lt;sdx:attachedDocument generateId="true" 
      url="http://www.images.org/images/image0012.jpg" mimetype="image/jpeg"/&gt;
    &lt;sdx:attachedDocument attid="img0022" 
      url="images/image0022.jpg" mimetype="image/jpeg"/&gt;
  &lt;/sdx:document&gt;
</programlisting><para>De ces exemples, il faut retenir ceci :</para><itemizedlist><listitem><para>L'identifiant du document attaché se fait généralement à l'aide des mêmes attributs <sgmltag class="attribute">id</sgmltag>, <sgmltag class="attribute">generateId</sgmltag> et <sgmltag class="attribute">overrideId</sgmltag> expliqués pour l'unité documentaire ci-dessus, et ces derniers jouent exactement le même rôle ;</para></listitem><listitem><para>Il est possible de préciser l'entrepôt où stocker le document à l'aide de l'attribut <sgmltag class="attribute">repo</sgmltag> ;</para></listitem><listitem><para>L'attribut <sgmltag class="attribute">url</sgmltag> est obligatoire et doit contenir l'adresse URL du document attaché, soit relative à l'adresse du document indexé soit absolue ;</para></listitem><listitem><para>L'attribut <sgmltag class="attribute">mimetype</sgmltag> est obligatoire et il doit indiquer le type de fichier (au sens de la spécification des types MIME) dont il s'agit, pour que SDX puisse le restituer correctement ;</para></listitem><listitem><para>Pour des raisons de compatibilité avec la version 1 de SDX, il est possible de spécifier un identifiant qui n'est pas unique dans la base de documents pour le document attaché, mais seulement unique dans le document auquel il est attaché. Pour ce faire, il faut utiliser l'attribut <sgmltag class="attribute">attid</sgmltag> au lieu de l'attribut <sgmltag class="attribute">id</sgmltag>, et dans ce cas, en interne, SDX va concaténer les identifiants du document XML et du document attaché pour sa gestion interne. Cet usage est toutefois déconseillé et pourrait être retiré de SDX dans une version ultérieure ; nous vous conseillons d'utiliser des identifiants uniques pour les documents attachés, ce qui permet notamment de partager des documents attachés entre plusieurs bases de documents.</para></listitem></itemizedlist></section><section><title>Les fragments de documents</title><para>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 <sgmltag class="element">sdx:document</sgmltag> et qui n'appartient pas à l'espace de nom <literal>sdx</literal> 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.</para><para>Les fragments de documents sont expliqués <olink targetdocent="fragmentation">ailleurs</olink>, mais nous montrons ici un exemple de leur déclaration à l'issue du processus d'indexation :</para><programlisting>
  &lt;sdx:document id="doc01"&gt;
    &lt;sdx:field name="titre"&gt;Introduction à XML&lt;/sdx:field&gt;
    &lt;sdx:field name="auteur"&gt;Michard, Alain&lt;/sdx:field&gt;
    &lt;sdx:document id="doc01-ch01"&gt;
      &lt;sdx:field name="titre"&gt;Qu'est-ce que XML&lt;/sdx:field&gt;
      &lt;section id="ch01"&gt;
        &lt;para&gt;Comment définir XML ? Ce n'est pas facile...&lt;/para&gt;
      &lt;/section&gt;
    &lt;/sdx:document&gt;
  &lt;/sdx:document&gt;
</programlisting><para>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 <sgmltag class="element">section</sgmltag>. On voit que pour créer des fragments de documents, il suffit simplement d'imbriquer des éléments <sgmltag class="element">sdx:document</sgmltag> les uns à l'intérieur des autres (y compris sur plusieurs niveaux) et dans le cas des fragments il faut aussi ajouter leur contenu.</para><para>Le rôle de la fragmentation et ce qu'en fait SDX est expliqué <olink targetdocent="fragmentation">ailleurs</olink>.</para></section><section><title>L'ajout de termes depuis un thésaurus</title><para>L'utilisation d'un thésaurus lors de l'indexation est expliquée <olink targetdocent="thesaurus">ailleurs</olink>, 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 :</para><programlisting>
  &lt;sdx:document id="doc01"&gt;
    &lt;sdx:field name="lieu"&gt;
      Gironde
      &lt;sdx:expandField&gt;
        &lt;sdx:relation type="bt" depth="10" th="thes"/&gt;
        &lt;sdx:relation type="nt" depth="1" th="thes"/&gt;
      &lt;/sdx:expandField&gt;
    &lt;/sdx:field&gt;
  &lt;/sdx:document&gt;
</programlisting><para>Le thésaurus utilisé sera celui dont l'identifiant est <literal>thes</literal>, et les termes génériques (jusqu'à 10 niveaux au-dessus du terme <literal>Gironde</literal> seront ajoutés, de même que les termes spécifiques mais à un seul niveau.</para></section></webpage> 
