<?xml version="1.0"?>
<!DOCTYPE webpage PUBLIC "-//Norman Walsh//DTD Website V2.1b1//EN" "../../../dtd/website.dtd" [
  <!ENTITY actions_controle SYSTEM "actions_controle.xml" NDATA XML>
  <!ENTITY actions_requetes SYSTEM "actions_requetes.xml" NDATA XML>
  <!ENTITY actions_index SYSTEM "actions_index.xml" NDATA XML>
  <!ENTITY parametres_sdx SYSTEM "parametres_sdx.xml" NDATA XML>
  <!ENTITY thesaurus SYSTEM "actions_thesaurus.xml" NDATA XML>
]>
<webpage id="actions_amander">

  <head>
    <title lang="fr">Amender une requête</title>
    <titleabbrev lang="fr">Amender</titleabbrev>
    <author lang="fr">
      <firstname>Malo</firstname>
      <surname>Pichot</surname>
      <affiliation>
        <orgname>AJLSM</orgname>
      </affiliation>
    </author>
    <revhistory>
      <revision lang="fr">
        <revnumber>1.0</revnumber>
        <date>2005-03-22</date>
      </revision>
    </revhistory>
  </head>

  <itemizedlist>
    <title>Liste des éléments décrits dans cette page : </title>
    <listitem>
      <para>
        <ulink url="#sdx_expandquery">
          <sgmltag class="element">sdx:expandQuery</sgmltag>
        </ulink> ; </para>
    </listitem>
    <listitem>
      <para>
        <ulink url="#sdx_filter">
          <sgmltag class="element">sdx:filter</sgmltag>
        </ulink> ; </para>
    </listitem>
    <listitem>
      <para>
        <ulink url="#sdx_basequery">
          <sgmltag class="element">sdx:baseQuery</sgmltag>
        </ulink>.</para>
    </listitem>
  </itemizedlist>
  <section id="concepts">
    <title>Concepts clés</title>
    <para>Il arrive souvent que la question posée ne coïncide pas exactement à l'attente de celui qui l'a posée. La question est trop imprécise ; les résultats sont trop nombreux. Au contraire, la question est trop fine ; les résultats se comptent sur les doigts de la main. Il est donc récurrent que l'on ai besoin d'amender la requête afin d'améliorer l'ensemble constitué par les résultats. SDX propose plusieurs outils pour <emphasis role="bold">étendre</emphasis>, <emphasis role="bold">filtrer</emphasis> ou <emphasis role="bold">affiner</emphasis> une recherche : </para>
    <informaltable id="tableau">
      <tgroup cols="3">
        <colspec colnum="1" colname="col1" colwidth="1.00*"/>
        <colspec colnum="2" colname="col2" colwidth="3.73*"/>
        <colspec colnum="3" colname="col3" colwidth="1.43*"/>
        <thead>
          <row>
            <entry colname="col1">Méthode</entry>
            <entry colname="col2">Description</entry>
            <entry colname="col3">Elément correspondant</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry colname="col1">
              <emphasis role="italic">Thesaurus</emphasis>
            </entry>
            <entry colname="col2">L'utilisation de <emphasis role="italic">thesauri</emphasis> permet d'étendre une recherche à une langue différente (e.g., trouver les titres contenant le mot <literal>actualités</literal> dans les documents en français et en anglais, SDX se chargeant de retrouver le synonyme en anglais).</entry>
            <entry colname="col3">
              <ulink url="#sdx_expandquery">
                <sgmltag class="element">sdx:expandQuery</sgmltag>
              </ulink>
            </entry>
          </row>
          <row>
            <entry colname="col1">Filtre</entry>
            <entry colname="col2">Un filtre agit <emphasis role="italic">a contrario</emphasis> du <emphasis role="italic">thesaurus</emphasis> : on ne cherche pas à augmenter le groupe des résultats, mais à le réduire.</entry>
            <entry colname="col3">
              <ulink url="#sdx_filter">
                <sgmltag class="element">sdx:filter</sgmltag>
              </ulink>
            </entry>
          </row>
          <row>
            <entry colname="col1">Sur-requête</entry>
            <entry colname="col2">On peut reprendre une ancienne requête (grâce à son identifiant) et ajouter de nouveau items de recherche (e.g., je veux reprendre la requête <literal>q147</literal> et y enlevant les auteurs dont le nom est <literal>Zola</literal>).</entry>
            <entry colname="col3">
              <ulink url="#sdx_basequery">
                <sgmltag class="element">sdx:baseQuery</sgmltag>
              </ulink>
            </entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
    <para>Ces trois éléments (ou leurs attributs) sont utilisables par l'ensemble des actions d'exécution de requête (<sgmltag class="element">sdx:execute*Query</sgmltag>) décrites
      <olink targetdocent="actions_requetes">plus avant</olink>.</para>
  </section>

  <section lang="fr" id="sdx_expandquery">
    <title>
      <sgmltag class="element">sdx:expandQuery</sgmltag>
    </title>
    <section id="sdx_expandquery_description">
      <title>Description</title>
      <para>
        <sgmltag class="element">sdx:expandQuery</sgmltag> ouvre à l'utilisation d'un <emphasis role="italic">thesaurus</emphasis> lors d'une requête. Ce dernier se présente sous la forme d'un fichier XML (voir le fichier <filename>dico.xml</filename> fourni avec l'application de démonstration SDXTest). Il suffit donc de déclarer ce dernier dans la construction d'une requête (voir la section
        <olink targetdocent="actions_requetes"><citetitle>Exécution de requêtes</citetitle>
        </olink>). Il est possible d'affiner l'exploitation du <emphasis role="italic">thesaurus</emphasis> en déclarant la <emphasis role="bold">profondeur</emphasis> maximale autorisée, les <emphasis role="bold">relations</emphasis> à explorer et, enfin, la ou les <emphasis role="bold">langues</emphasis> supportées. Il va sans dire que ces paramètres ne sont exploitables que dans la mesure où le dit <emphasis role="italic">thesaurus</emphasis> contient l'information nécessaire.</para>
      <para>La logique est simple : une requête dans SDX peut se résumer par une recherche d'un ou de plusieurs termes dans un champ. Le thesaurus permet d'augmenter la liste des termes que l'on va rechercher.</para>
      <informaltable lang="fr">
        <tgroup cols="2">
          <colspec colnum="1" colname="col1" colwidth="1.00*"/>
          <colspec colnum="2" colname="col2" colwidth="3.32*"/>
          <tbody>
            <row>
              <entry colname="col1">Code implémentant cette action</entry>
              <entry colname="col2">
                <filename>sdx-queries.xsl</filename>
              </entry>
            </row>
            <row>
              <entry colname="col1">Contexte d'utilisation</entry>
              <entry colname="col2">On peut utiliser l'action <sgmltag class="element">sdx:expandQuery</sgmltag> avec l'ensemble des actions recherche décrites dans cette page.</entry>
            </row>
            <row>
              <entry colname="col1">Contenu éventuel</entry>
              <entry colname="col2">Aucun.</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>
    <section id="sdx_expandquery_parametres">
      <title>Paramètres</title>
      <informaltable>
        <tgroup cols="4">
          <colspec colnum="1" colname="col1" colwidth="1.09*"/>
          <colspec colnum="2" colname="col2" colwidth="3.46*"/>
          <colspec colnum="3" colname="col3" colwidth="2.38*"/>
          <colspec colnum="4" colname="col4" colwidth="1.00*"/>
          <thead>
            <row>
              <entry colname="col1">Nom</entry>
              <entry colname="col2">Description</entry>
              <entry colname="col3">Elément correspondant</entry>
              <entry colname="col4"></entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry colname="col1">
                <sgmltag class="attribute">th</sgmltag>
              </entry>
              <entry colname="col2">Identifiant du <emphasis role="italic">thesaurus</emphasis>.</entry>
              <entry colname="col3">
                <olink localinfo="sdx_thesaurus" targetdocent="thesaurus">
                  <sgmltag class="element">sdx:thesaurus</sgmltag>
                </olink>
              </entry>
              <entry colname="col4">Obligatoire</entry>
            </row>
            <row>
              <entry colname="col1">
                <sgmltag class="attribute">depth</sgmltag>
              </entry>
              <entry colname="col2">Indique la profondeur de recherche autorisée au sein du <emphasis role="italic">thesaurus</emphasis>. Par défaut, SDX utilise les valeurs déclarées dans le fichier <filename>application.xconf</filename>.</entry>
              <entry colname="col3">
                <olink localinfo="sdx_thesaurus" targetdocent="thesaurus">
                  <sgmltag class="element">sdx:thesaurus</sgmltag>
                </olink>
              </entry>
              <entry colname="col4">Facultatif</entry>
            </row>
            <row>
              <entry colname="col1">
                <sgmltag class="attribute">relation</sgmltag>
              </entry>
              <entry colname="col2">Précise le type de relation autorisé. Par défaut, SDX utilise les valeurs déclarées dans le fichier <filename>application.xconf</filename>.</entry>
              <entry colname="col3">
                <olink localinfo="sdx_thesaurus" targetdocent="thesaurus">
                  <sgmltag class="element">sdx:thesaurus</sgmltag>
                </olink>
              </entry>
              <entry colname="col4">Facultatif</entry>
            </row>
            <row>
              <entry colname="col1">
                <sgmltag class="attribute">lang</sgmltag>
              </entry>
              <entry colname="col2">Indique la langue du terme recherché. Par défaut, il s'agit de la langue courante. (FIXME)</entry>
              <entry colname="col3">
                <olink localinfo="sdx_thesaurus" targetdocent="thesaurus">
                  <sgmltag class="element">sdx:thesaurus</sgmltag>
                </olink>
              </entry>
              <entry colname="col4">Facultatif</entry>
            </row>
            <row>
              <entry colname="col1">
                <sgmltag class="element">field</sgmltag>
              </entry>
              <entry colname="col2">Identifie le champ dans lequel on souhaite étendre la requête par l'utilisation d'un thesaurus.
                            Ceci n'est réellement intéressant que lorsque l'on souhaite
                            étendre une requête simple dont la requête fait référence à
                            plusieurs champs (cf. <ulink url="#exemple_sdx_expandquery_02">exemple ci-dessous</ulink>).</entry>
              <entry colname="col3">
                <sgmltag class="element">sdx:field</sgmltag>
              </entry>
              <entry colname="col4">Facultatif</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>
    <section id="sdx_expandquery_exemples">
      <title>Exemples</title>
      <example lang="fr" id="exemple_sdx_expandquery_01">
        <title>Emploi d'un <emphasis role="italic">thesaurus</emphasis>
        </title>
        <para>L'exemple suivant présente une page XSP générant une interrogation simple étendue par le <emphasis role="italic">thesaurus</emphasis>
          <literal>dico</literal>.</para>
        <programlisting>
&lt;sdx:page&gt;
 &lt;sdx:executeSimpleQuery baseParam="b" queryParam="q"&gt;
  &lt;sdx:expandQuery th="dico" depth="1" relation="et" /&gt;
 &lt;/sdx:executeSimpleQuery&gt;
&lt;/sdx:page&gt;
</programlisting>
        <para> Notez que la référence à la base de documents et le(s) terme(s) recherché(s) sont passés en paramètres HTTP. L'application SDX attend une action de l'utilisateur pour donner ces informations. Cela signifie que l'URL <literal>{serveur sdx}/sdxtest/q.xsp?b="docs"&amp;q="mammouths"</literal> seront interprétés : recherche <literal>mammouths</literal> dans les documents indexés dans la base de documents <literal>docs</literal>. Pour peu que le <emphasis role="italic">thesaurus</emphasis>
          <literal>dico</literal> présente des correspondances entre les langues françaises et anglaises, la question <literal>{serveur sdx}/sdxtest/q.xsp?b="docs"&amp;q="mammoths"</literal> donnerait le même résultat.</para>
        <para>Voir le fichier
          <ulink url="../../samples/application.xconf"><filename>application.xconf</filename>
          </ulink> donné en démonstration pour connaître la syntaxe de déclaration d'un <emphasis role="italic">thesaurus</emphasis> dans une application.</para>
      </example>

      <example lang="fr" id="exemple_sdx_expandquery_02">
        <title>Emploi d'un <emphasis role="italic">thesaurus dans une requête simple</emphasis>
        </title>
        <para>L'exemple suivant présente une page XSP générant une requête simple étendue par le <emphasis role="italic">thesaurus</emphasis>
          <literal>dico</literal>. A la différence de l'<ulink url="#exemple_sdx_expandquery_01">exemple ci-dessus</ulink>, on ne souhaite étendre la requête que sur le champ "titre".</para>
        <programlisting>
&lt;sdx:page&gt;
 &lt;sdx:executeSimpleQuery baseParam="b" query="+titre:titre +auteur:verne"&gt;
  &lt;sdx:expandQuery th="dico" depth="1" relation="et" field="titre" /&gt;
 &lt;/sdx:executeSimpleQuery&gt;
&lt;/sdx:page&gt;
</programlisting>
      </example>

    </section>
  </section>
  <section id="sdx_filter">
    <title>
      <sgmltag class="element">sdx:filter</sgmltag>
    </title>
    <section id="sdx_filter_desc">
      <title>Description</title>
      <para>
        <sgmltag class="element">sdx:filter</sgmltag> permet de construire un filtre pour une recherche. Cela signifie que l'on crée une « sous-base de documents » dans laquelle la requête sera exécutée. A ce stade, l'emploi d'un <literal>et</literal> logique dans la question n'apporte rien de moins. Il existe pourtant une différence au niveau du calcul de pertinence (et donc du tri par défaut des résultats). Le filtre n'entre pas en compte dans ce calcul.
      </para>
      <para>
        <sgmltag class="element">sdx:filter</sgmltag> peut être utilisé avec l'ensemble des actions de requêtes, sauf <olink targetdocent="actions_index" localinfo="sdx_terms"><sgmltag class="element">sdx:terms</sgmltag></olink>.
      </para>
    </section>
    <section id="sdx_filter_param">
      <title>Paramètres</title>
      <informaltable>
        <tgroup cols="3">
          <colspec colnum="1" colname="col1" colwidth="1.06*"/>
          <colspec colnum="2" colname="col2" colwidth="4.10*"/>
          <colspec colname="col3" colnum="3" colwidth="1.00*"/>
          <thead>
            <row>
              <entry colname="col1">Nom</entry>
              <entry colname="col2">Description</entry>
              <entry colname="col3"></entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry colname="col1">
                <sgmltag class="attribute">ff</sgmltag>
              </entry>
              <entry colname="col2">Identifiant d'un champ sur lequel on souhaite activer un filtre de requête.</entry>
              <entry colname="col3">Obligatoire</entry>
            </row>
            <row>
              <entry colname="col1">
                <sgmltag class="attribute">fv</sgmltag>
              </entry>
              <entry colname="col2">Identifiant une valeur sur laquelle on souhaite activer le filtre.</entry>
              <entry colname="col3">Obligatoire</entry>
            </row>
            <row>
              <entry colname="col1">
                <sgmltag class="attribute">fop</sgmltag>
              </entry>
              <entry colname="col2">Opérateur de construction du filtre. Par défaut, l'opérateur est <literal>and</literal>.</entry>
              <entry colname="col3">Facultatif</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>
    <section id="sdx_filter_exemples">
      <title>Exemples</title>
      <para>Dans l'exemple suivant, on souhaite retrouver les articles écrits par Dominique Duviard sur les bateaux bretons.</para>
      <programlisting>
&lt;sdx:page&gt;

 &lt;sdx:executeSimpleQuery
  base="sdxworld"
  query="+sujet:bateau +auteur:duviard +region:bretagne" &gt;

  &lt;sdx:filter
   ff="type"
   fv="article" /&gt;

 &lt;/sdx:executeSimpleQuery&gt;

&lt;/sdx:page&gt;
</programlisting>
    </section>
  </section>
  <section lang="fr" id="sdx_basequery">
    <title>
      <sgmltag class="element">sdx:baseQuery</sgmltag>(CHECK)</title>
    <section id="sdx_basequery_description">
      <title>Description</title>
      <para>
        <sgmltag class="element">sdx:baseQuery</sgmltag> permet de reprendre une ancienne requête de manière à la retravailler, quelqu'en soit le but (l'extension ou la réduction du groupe de résultats). On comprendra donc qu'il s'agit bien dans ce cas d'agir <emphasis role="italic">a posteriori</emphasis> de la requête, contrairement aux deux autres outils d'amendement décrits dans cette page.</para>
      <para>Comme il a été dit dans la définition de
        <olink localinfo="sdx_results" targetdocent="actions_controle"><sgmltag class="element">sdx:results</sgmltag>
        </olink> l'identifiant d'une requête demeure dans la mémoire de la session de l'utilisateur courant. Cela signifie, qu'à l'arrêt de la session (i.e., la fermeture du navigateur ou la déconnexion de l'utilisateur), l'identifiant est supprimé de la cache et qu'un identifiant de requête ne peut pas être partagé entre plusieurs utilisateurs. Il n'y a pas encore de mécanisme de mémorisation d'une requête au niveau du serveur, mais ce n'est pas impossible et relativement économe en ligne de code (cf. message de Frédéric Glorieux
        <ulink url="http://mail.gnu.org/archive/html/sdx-users/2003-04/msg00092.html">Mécanisme de cache? (30-04-2003)</ulink> sur la liste <email><ulink url="mailto:sdx-users@liste.ajlsm.com">sdx-users</ulink>
        </email>).</para>
      <informaltable>
        <tgroup cols="2">
          <colspec colnum="1" colname="col1" colwidth="1.00*"/>
          <colspec colnum="2" colname="col2" colwidth="3.19*"/>
          <tbody>
            <row>
              <entry colname="col1">Code implémentant cette action</entry>
              <entry colname="col2">
                <filename>sdx-queries.xsl</filename>
              </entry>
            </row>
            <row>
              <entry colname="col1">Contexte d'utilisation</entry>
              <entry colname="col2">Dans n'importe quelle action de requête <sgmltag class="element">sdx:*Query</sgmltag> décrites dans la
                <olink>section précédente</olink>.</entry>
            </row>
            <row>
              <entry colname="col1">Contenu éventuel</entry>
              <entry colname="col2">Aucun.</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>
    <section id="sdx_basequery_parametres">
      <title>Paramètres</title>
      <informaltable>
        <tgroup cols="3">
          <colspec colnum="1" colname="col1" colwidth="1.13*"/>
          <colspec colnum="2" colname="col2" colwidth="4.26*"/>
          <colspec colname="col3" colnum="3" colwidth="1.00*"/>
          <thead>
            <row>
              <entry colname="col1">Nom</entry>
              <entry colname="col2">Description</entry>
              <entry colname="col3"></entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry colname="col1">
                <sgmltag class="attribute">bqid</sgmltag>
              </entry>
              <entry colname="col2">Identifiant de la requête que l'on souhaite affiner ou étendre.</entry>
              <entry colname="col3">Obligatoire</entry>
            </row>
            <row>
              <entry colname="col1">
                <sgmltag class="attribute">bop</sgmltag>
              </entry>
              <entry colname="col2">Opérateur de requête. Par défaut , l'opérateur est un <literal>ou</literal> logique.</entry>
              <entry colname="col3">Facultatif</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>
    <section id="sdx_basequery_exemples">
      <title>Exemples</title>
      <example lang="fr" id="exemple_sdx_basequery_01">
        <title>Affiner une recherche</title>
        <para>Dans l'exemple suivant, nous verrons qu'une même page XSP peut offrir une action de recherche simple sur deux base de documents et permettre d'affiner le résultat de recherche obtenu.</para>
        <para>Soit la page XSP suivante : </para>
        <programlisting>
&lt;sdx:page&gt;
 &lt;sdx:executeSimpleQuery
   bqidParam="bq"
   bop="and"
   base="sdxworld sdxdoc"
   query="q" /&gt;
&lt;/sdx:page&gt;
</programlisting>
        <para>L'URL <literal>{serveur sdx}/sdxtest/q.xsp?q="france"</literal> donnera le résultat : </para>
        <programlisting>
&lt;sdx:document&gt;
 ...
 &lt;sdx:results qid="q1" nb="45" ...&gt;
  ...
 &lt;/sdx:results&gt;
 ...
&lt;/sdx:document&gt;
</programlisting>
        <para>Lors de la même session, pour le même utilisateur, l'URL <literal>{serveur sdx}/sdxtest/qy.xsp?&amp;bop="and"&amp;bq="q1"&amp;q="rue"</literal> donnera le résultat : </para>
        <programlisting>
&lt;sdx:document&gt;
 ...
 &lt;sdx:results qid="q2" nb="10" ...&gt;
  ...
 &lt;/sdx:results&gt;
 ...
&lt;/sdx:document&gt;
</programlisting>
      </example>
    </section>
  </section>

</webpage>
