textsearch.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Dernière modification
     le       $Date$
     par      $Author$
     révision $Revision$ -->

<chapter id="textsearch">
 <title id="textsearch-title">Recherche plein texte</title>

  <indexterm zone="textsearch">
   <primary>recherche plein texte</primary>
  </indexterm>

  <indexterm zone="textsearch">
   <primary>recherche de texte</primary>
  </indexterm>

 <sect1 id="textsearch-intro">
  <title>Introduction</title>

  <para>
   La recherche plein texte (ou plus simplement la <firstterm>recherche de
   texte</firstterm>) permet de sélectionner des
   <firstterm>documents</firstterm> en langage naturel qui satisfont une
   <firstterm>requête</firstterm> et, en option, de les trier par intérêt
   suivant cette requête.  Le type le plus fréquent de recherche concerne la
   récupération de tous les documents contenant les <firstterm>termes de
   recherche</firstterm> indiqués et de les renvoyer dans un ordre dépendant
   de leur <firstterm>similarité</firstterm> par rapport à la requête. Les
   notions de
   <varname>requête</varname> et de <varname>similarité</varname> peuvent
   beaucoup varier et dépendent de l'application réelle. La recherche
   la plus simple considère une <varname>requête</varname> comme un
   ensemble de mots et la <varname>similarité</varname> comme la fréquence
   des mots de la requête dans le document.
  </para>

  <para>
   Les opérateurs de recherche plein texte existent depuis longtemps dans
   les bases de données. <productname>PostgreSQL</productname> dispose des
   opérateurs <literal>~</literal>, <literal>~*</literal>,
   <literal>LIKE</literal> et <literal>ILIKE</literal> pour les types de
   données texte, mais il lui manque un grand nombre de propriétés essentielles
   requises par les systèmes d'information modernes&nbsp;:
  </para>

  <itemizedlist  spacing="compact" mark="bullet">
   <listitem>
    <para>
     Aucun support linguistique, même pour l'anglais. Les expressions
     rationnelles ne sont pas suffisantes car elles ne peuvent pas gérer
     facilement les mots dérivées, par exemple <literal>satisfait</literal> et
     <literal>satisfaire</literal>. Vous pouvez laisser passer des documents
     qui contiennent <literal>satisfait</literal> bien que vous souhaiteriez
     quand même les trouver avec une recherche sur
     <literal>satisfaire</literal>.
     Il est possible d'utiliser <literal>OR</literal> pour rechercher plusieurs
     formes dérivées mais cela devient complexe et augmente le risque d'erreur
     (certains mots peuvent avoir des centaines de variantes).
    </para>
   </listitem>

   <listitem>
    <para>
     Ils ne fournissent aucun classement (score) des résultats de la recherche,
     ce qui les rend inefficaces quand des centaines de documents correspondants
     sont trouvés.
    </para>
   </listitem>

   <listitem>
    <para>
     Ils ont tendance à être lent car les index sont peu supportés, donc ils
     doivent traiter tous les documents à chaque recherche.
    </para>
   </listitem>
  </itemizedlist>

  <para>
   L'indexage pour la recherche plein texte permet au document d'être
   <emphasis>pré-traité</emphasis> et qu'un index de ce pré-traitement soit
   sauvegardé pour une recherche ultérieure plus rapide. Le pré-traitement
   inclut&nbsp;:
  </para>

  <itemizedlist  mark="none">
   <listitem>
    <para>
     <emphasis>Analyse des documents en <firstterm>jetons</firstterm></emphasis>.
     Il est utile d'identifier les différentes classes de jetons, c'est-à-dire
     nombres, mots, mots complexes, adresses email, pour qu'ils puissent être
     traités différemment. En principe, les classes de jeton dépendent de
     l'application mais, dans la plupart des cas, utiliser un ensemble prédéfinie
     de classes est adéquat.
     <productname>PostgreSQL</productname> utilise un
     <firstterm>analyseur</firstterm> pour réaliser cette étape. Un analyseur
     standard est fourni, mais des analyseurs personnalisés peuvent être écrits
     pour des besoins spécifiques.
    </para>
   </listitem>

   <listitem>
    <para>
     <emphasis>Conversion des jetons en <firstterm>lexemes</firstterm></emphasis>.
     Un lexeme est une chaîne, identique à un jeton, mais elle a été
     <firstterm>normalisée</firstterm> pour que différentes formes du même mot
     soient découvertes. Par exemple, la normalisation inclut pratiquement toujours
     le remplacement des majuscules par des minuscules, ainsi que la suppression
     des suffixes (comme <literal>s</literal> ou <literal>es</literal> en anglais).
     Ceci permet aux recherches de trouver les variantes du même mot, sans avoir
     besoin de saisir toutes les variantes possibles. De plus, cette étape
     élimine typiquement les <firstterm>termes courants</firstterm>, qui sont
     des mots si courants qu'il est inutile de les rechercher. Donc, les
     jetons sont des fragments bruts du document alors que les lexemes sont des
     mots supposés utiles pour l'indexage et la recherche.
     <productname>PostgreSQL</productname> utilise des
     <firstterm>dictionnaires</firstterm> pour réaliser cette étape.
     Différents dictionnaires standards sont fournis et des dictionnaires
     personnalisés peuvent être créés pour des besoins spécifiques.
    </para>
   </listitem>

   <listitem>
    <para>
     <emphasis>Stockage des documents pré-traités pour optimiser la recherche
     </emphasis>. Chaque document peut être représenté comme un
     tableau trié de lexemes normalisés. Avec ces lexemes, il est souvent
     souhaitable de stocker des informations de position à utiliser pour
     obtenir un <firstterm>score de proximité</firstterm>, pour qu'un document
     qui contient une région plus <quote>dense</quote> des mots de la requête
     se voit affecté un score plus important qu'un document qui en a moins.
    </para>
   </listitem>
  </itemizedlist>

  <para>
   Les dictionnaires autorisent un contrôle fin de la normalisation des jetons.
   Avec des dictionnaires appropriés, vous pouvez&nbsp;:
  </para>

  <itemizedlist  spacing="compact" mark="bullet">
   <listitem>
    <para>
     Définir les termes courants qui ne doivent pas être indexés.
    </para>
   </listitem>

   <listitem>
    <para>
     Établir une liste des synonymes pour un simple mot en utilisant 
     <application>Ispell</application>.
    </para>
   </listitem>

   <listitem>
    <para>
     Établir une correspondance entre des phrases et un simple mot en utilisant
     un thésaurus.
    </para>
   </listitem>

   <listitem>
    <para>
     Établir une correspondance entre différentes variations d'un mot et une
     forme canonique en utilisant un dictionnaire <application>Ispell</application>.
    </para>
   </listitem>

   <listitem>
    <para>
     Établir une correspondance entre différentes variations d'un mot et une
     forme canonique en utilisant les règles du stemmer
     <application>Snowball</application>.
    </para>
   </listitem>
  </itemizedlist>

  <para>
   Un type de données <type>tsvector</type> est fourni pour stocker les documents
   pré-traités, avec un type <type>tsquery</type> pour représenter les requêtes
   traitées (<xref linkend="datatype-textsearch"/>). Il existe beaucoup de
   fonctions et d'opérateurs disponibles pour ces types de données
   (<xref linkend="functions-textsearch"/>), le plus important étant l'opérateur
   de correspondance <literal>@@</literal>, dont nous parlons dans la
   <xref linkend="textsearch-matching"/>. Les recherches plein texte peuvent
   être accélérées en utilisant des index (<xref
   linkend="textsearch-indexes"/>).
  </para>


  <sect2 id="textsearch-document">
   <title>Qu'est-ce qu'un document&nbsp;?</title>

   <indexterm zone="textsearch-document">
    <primary>document</primary>
    <secondary>recherche de texte</secondary>
   </indexterm>

   <para>
    Un <firstterm>document</firstterm> est l'unité de recherche dans un système
    de recherche plein texte, par exemple un article de magazine ou un
    message email. Le moteur de recherche plein texte doit être capable
    d'analyser des documents et de stocker les associations de lexemes (mots
    clés) avec les documents parents. Ensuite, ces associations seront utilisées
    pour rechercher les documents contenant des mots de la requête.
   </para>

   <para>
    Pour les recherches dans <productname>PostgreSQL</productname>, un
    document est habituellement un champ texte à l'intérieur d'une ligne d'une
    table de la base ou une combinaison (concaténation) de champs, parfois
    stockés dans différentes tables ou obtenus dynamiquement. En d'autres
    termes, un document peut être construit à partir de différentes parties
    pour l'indexage et il peut ne pas être stocké quelque part. Par
    exemple&nbsp;:

<programlisting>
SELECT titre || ' ' ||  auteur || ' ' ||  resume || ' ' || corps AS document
FROM messages
WHERE mid = 12;

SELECT m.titre || ' ' || m.auteur || ' ' || m.resume || ' ' || d.corps AS document
FROM messages m, docs d
WHERE mid = did AND mid = 12;
</programlisting>
   </para>

   <note>
    <para>
     En fait, dans ces exemples de requêtes, <function>coalesce</function>
     devrait être utilisé pour empêcher un résultat <literal>NULL</literal> pour
     le document entier à cause d'une seule colonne <literal>NULL</literal>.
    </para>
   </note>

   <para>
    Une autre possibilité est de stocker les documents dans de simples fichiers
    texte du système de fichiers. Dans ce cas, la base est utilisée pour
    stocker l'index de recherche plein texte et pour exécuter les recherches, et
    un identifiant unique est utilisé pour retrouver le document sur le
    système de fichiers. Néanmoins, retrouver les fichiers en dehors de la base
    demande les droits d'un superutilisateur ou le support de fonctions spéciales,
    donc c'est habituellement moins facile que de conserver les données dans
    <productname>PostgreSQL</productname>. De plus, tout conserver dans la base
    permet un accès simple aux méta-données du document pour aider l'indexage
    et l'affichage.
   </para>

   <para>
    Dans le but de la recherche plein texte, chaque document doit être réduit
    au format de pré-traitement, <type>tsvector</type>. La recherche et le
    calcul du score sont réalisés entièrement à partir de la représentation
    <type>tsvector</type>
    d'un document &mdash; le texte original n'a besoin d'être retrouvé que
    lorsque le document a été sélectionné pour être montré à l'utilisateur.
    Nous utilisons souvent <type>tsvector</type> pour le document mais, bien
    sûr, il ne s'agit que d'une représentation compacte du document complet.
   </para>
  </sect2>

  <sect2 id="textsearch-matching">
   <title>Correspondance de base d'un texte</title>

   <para>
    La recherche plein texte dans <productname>PostgreSQL</productname> est
    basée sur l'opérateur de correspondance <literal>@@</literal>, qui renvoie
    <literal>true</literal> si un <type>tsvector</type> (document) correspond
    à un <type>tsquery</type> (requête). Peu importe le type de données indiqué
    en premier&nbsp;:

<programlisting>
SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector @@ 'cat &amp; rat'::tsquery;
 ?column?
----------
 t

SELECT 'fat &amp; cow'::tsquery @@ 'a fat cat sat on a mat and ate a fat rat'::tsvector;
 ?column?
----------
 f
</programlisting>
   </para>

   <para>
    Comme le suggère l'exemple ci-dessus, un <type>tsquery</type> n'est pas un
    simple texte brut, pas plus qu'un <type>tsvector</type> ne l'est. Un
    <type>tsquery</type> contient des termes de recherche qui doivent déjà être
    des lexemes normalisés, et peut combiner plusieurs termes en utilisant les
    opérateurs AND, OR et NOT. (Pour les détails, voir la <xref
    linkend="datatype-textsearch"/>.)  Les fonctions <function>to_tsquery</function>
    et <function>plainto_tsquery</function> sont utiles pour convertir un texte
    écrit par un utilisateur dans un <type>tsquery</type> correct, par exemple
    en normalisant les mots apparaissant dans le texte. De façon similaire,
    <function>to_tsvector</function> est utilisé pour analyser et normaliser un
    document. Donc, en pratique, une correspondance de recherche ressemblerait
    plutôt à ceci&nbsp;:

<programlisting>
SELECT to_tsvector('fat cats ate fat rats') @@ to_tsquery('fat &amp; rat');
 ?column? 
----------
 t
</programlisting>

    Observez que cette correspondance ne réussit pas si elle est écrite
    ainsi&nbsp;:

<programlisting>
SELECT 'fat cats ate fat rats'::tsvector @@ to_tsquery('fat &amp; rat');
 ?column? 
----------
 f
</programlisting>

    car ici aucune normalisation du mot <literal>rats</literal> n'interviendra.
    Les éléments d'un <type>tsvector</type> sont des lexemes, qui sont
    supposés déjà normalisés, donc <literal>rats</literal> ne correspond pas à
    <literal>rat</literal>.
   </para>

   <para>
    L'opérateur <literal>@@</literal> supporte aussi une entrée de type
    <type>text</type>, permettant l'oubli de conversions explicites de text vers
    <type>tsvector</type> ou <type>tsquery</type> dans les cas simples. Les
    variantes disponibles sont&nbsp;:

<programlisting>
tsvector @@ tsquery
tsquery  @@ tsvector
text @@ tsquery
text @@ text
</programlisting>
   </para>

   <para>
    Nous avons déjà vu les deux premières. La forme
    <type>text</type> <literal>@@</literal> <type>tsquery</type> est
    équivalent à <literal>to_tsvector(x) @@ y</literal>.
    La forme <type>text</type> <literal>@@</literal> <type>text</type>
    est équivalente à <literal>to_tsvector(x) @@ plainto_tsquery(y)</literal>.
   </para>
  </sect2>

  <sect2 id="textsearch-intro-configurations">
   <title>Configurations</title>

   <para>
    Les exemples ci-dessus ne sont que des exemples simples de recherche plein
    texte. Comme mentionné précédemment, la recherche plein texte permet de
    faire beaucoup plus&nbsp;: ignorer  l'indexation de certains mots (termes
    courants), traiter les synonymes et utiliser une analyse sophistiquée,
    c'est-à-dire une analyse basée sur plus qu'un espace blanc. Ces
    fonctionnalités sont contrôlées par les <firstterm>configurations de
    recherche plein texte</firstterm>. <productname>PostgreSQL</productname>
    arrive avec des configurations prédéfinies pour de nombreux langages et
    vous pouvez facilement créer vos propres configurations (la commande
    <command>\dF</command> de <application>psql</application> affiche toutes
    les configurations disponibles).
   </para>

   <para>
    Lors de l'installation, une configuration appropriée est sélectionnée et
    <xref linkend="guc-default-text-search-config"/> est configuré dans
    <filename>postgresql.conf</filename> pour qu'elle soit utilisée par défaut.
    Si vous utilisez la même configuration de recherche plein texte pour le
    cluster entier, vous pouvez utiliser la valeur de
    <filename>postgresql.conf</filename>. Pour utiliser différentes configurations
    dans le cluster mais avec la même configuration pour une base, utilisez
    <command>ALTER DATABASE ... SET</command>. Sinon, vous pouvez configurer
    <varname>default_text_search_config</varname> dans chaque session.
   </para>

   <para>
    Chaque fonction de recherche plein texte qui dépend d'une configuration a
    un argument <type>regconfig</type> en option, pour que la configuration
    utilisée puisse être précisée explicitement.
    <varname>default_text_search_config</varname> est seulement utilisé quand
    cet argument est omis.
   </para>

   <para>
    Pour rendre plus facile la construction de configurations de recherche
    plein texte, une configuration est construite à partir d'objets de la
    base de données. La recherche plein texte de
    <productname>PostgreSQL</productname> fournit quatre types d'objets
    relatifs à la configuration&nbsp;:
   </para>

  <itemizedlist  spacing="compact" mark="bullet">
   <listitem>
    <para>
     Les <firstterm>analyseurs de recherche plein texte</firstterm> cassent les
     documents en jetons et classifient chaque jeton (par exemple, un mot ou
     un nombre).
    </para>
   </listitem>

   <listitem>
    <para>
     Les <firstterm>dictionnaires de recherche plein texte</firstterm>
     convertissent les jetons en une forme normalisée et rejettent les termes
     courants.
    </para>
   </listitem>

   <listitem>
    <para>
     Les <firstterm>modèles de recherche plein texte</firstterm> fournissent
     les fonctions nécessaires aux dictionnaires. (Un dictionnaire spécifie
     uniquement un modèle et un ensemble de paramètres pour ce modèle.)
    </para>
   </listitem>

   <listitem>
    <para>
     Les <firstterm>configurations de recherche plein texte</firstterm>
     sélectionnent un analyseur et un ensemble de dictionnaires à utiliser
     pour normaliser les jetons produit par l'analyseur.
    </para>
   </listitem>
  </itemizedlist>

   <para>
    Les analyseurs de recherche plein texte et les modèles sont construits à
    partir de fonctions bas niveau écrites en C&nbsp;; du coup, le
    développement de nouveaux analyseurs ou modèles nécessite des connaissances
    en langage C, et les droits superutilisateur pour les installer dans une
    base de données. (Il y a des exemples d'analyseurs et de modèles en addon
    dans la partie <filename>contrib/</filename> de la distribution
    <productname>PostgreSQL</productname>.) Comme les dictionnaires et les
    configurations utilisent des paramètres et se connectent aux analyseurs et
    modèles, aucun droit spécial n'est nécessaire pour créer un nouveau
    dictionnaire ou une nouvelle configuration. Les exemples de création de
    dictionnaires et de configurations personnalisés seront présentés plus tard
    dans ce chapitre.
   </para>

  </sect2>

 </sect1>

 <sect1 id="textsearch-tables">
  <title>Tables et index</title>

  <para>
   Les exemples de la section précédente illustrent la correspondance plein
   texte en utilisant des chaînes simples. Cette section montre comment
   rechercher les données de la table, parfois en utilisant des index.
  </para>

  <sect2 id="textsearch-tables-search">
   <title>Rechercher dans une table</title>

   <para>
    Il est possible de faire des recherches plein texte sans index. Une requête
    qui ne fait qu'afficher le champ <structname>title</structname> de chaque
    ligne contenant le mot <literal>friend</literal> dans son champ
    <structfield>body</structfield> ressemble à ceci&nbsp;:

<programlisting>
SELECT title
FROM pgweb
WHERE to_tsvector('english', body) @@ to_tsquery('english', 'friend');
</programlisting>

    Ceci trouve aussi les mots relatifs comme <literal>friends</literal>
    et <literal>friendly</literal> car ils ont tous la même racine, le même
    lexeme normalisé.
   </para>

   <para>
    La requête ci-dessus spécifie que la configuration
    <literal>english</literal> doit être utilisée pour analyser et normaliser
    les chaînes. Nous pouvons aussi omettre les paramètres de
    configuration&nbsp;:

<programlisting>
SELECT title
FROM pgweb
WHERE to_tsvector(body) @@ to_tsquery('friend');
</programlisting>

    Cette requête utilisera l'ensemble de configuration indiqué par <xref
    linkend="guc-default-text-search-config"/>.
   </para>

   <para>
    Un exemple plus complexe est de sélectionner les dix documents les plus
    récents qui contiennent les mots <literal>create</literal> et
    <literal>table</literal> dans les champs <structname>title</structname> ou
    <structname>body</structname>&nbsp;:

<programlisting>
SELECT title
FROM pgweb
WHERE to_tsvector(title || ' ' || body) @@ to_tsquery('create &amp; table')
ORDER BY last_mod_date DESC LIMIT 10;
</programlisting>

    Pour plus de clareté, nous omettons la fonction <function>coalesce</function>
    qui est nécessaire pour trouver les lignes contenant <literal>NULL</literal>
    dans un des deux champs.
   </para>

   <para>
    Bien que ces requêtes fonctionnent sans index, la plupart des applications
    trouvent cette approche trop lente, sauf peut-être pour des recherches
    occasionnelles. Une utilisation pratique de la recherche plein texte réclame
    habituellement la création d'un index.
   </para>

  </sect2>

  <sect2 id="textsearch-tables-index">
   <title>Créer des index</title>

   <para>
    Nous pouvons créer un index <acronym>GIN</acronym> (<xref
    linkend="textsearch-indexes"/>) pour accélérer les recherches plein
    texte&nbsp;:

<programlisting>
CREATE INDEX pgweb_idx ON pgweb USING gin(to_tsvector('english', body));
</programlisting>

    Notez que la version à deux arguments de <function>to_tsvector</function>
    est utilisée. Seules les fonctions de recherche plein texte qui spécifient
    un nom de configuration peuvent être utilisées dans les index sur des
    expressions
    (<xref linkend="indexes-expressional"/>). Ceci est dû au fait que le contenu
    de l'index ne doit pas être affecté par <xref
    linkend="guc-default-text-search-config"/>. Dans le cas contraire, le
    contenu de l'index peut devenir incohérent parce que différentes entrées
    pourraient contenir des <type>tsvector</type> créés avec différentes
    configurations de recherche plein texte et qu'il ne serait plus possible de
    deviner à quelle configuration fait référence une entrée. Il serait
    impossible de sauvegarder et restaurer correctement un tel index.
   </para>

   <para>
    Comme la version à deux arguments de <function>to_tsvector</function> a
    été utilisée dans l'index ci-dessus, seule une référence de la requête
    qui utilise la version à deux arguments de <function>to_tsvector</function>
    avec le même nom de configuration utilise cet index. C'est-à-dire que
    <literal>WHERE to_tsvector('english', body) @@ 'a &amp; b'</literal> peut
    utiliser l'index, mais <literal>WHERE to_tsvector(body) @@ 'a &amp; b'</literal>
    ne le peut pas. Ceci nous assure qu'un index est seulement utilisé avec la
    même configuration que celle utilisée pour créer les entrées de l'index.
   </para>

  <para>
    Il est possible de configurer des index avec des expressions plus complexes
    où le nom de la configuration est indiqué dans une autre colonne. Par
    exemple&nbsp;:

<programlisting>
CREATE INDEX pgweb_idx ON pgweb USING gin(to_tsvector(config_name, body));
</programlisting>

    où <literal>config_name</literal> est une colonne de la table
    <literal>pgweb</literal>. Ceci permet l'utilisation de configuration
    mixe dans le même index tout en enregistrant la configuration utilisée
    pour chaque entrée d'index. Ceci est utile dans le cas d'une bibliothèque
    de documents dans différentes langues. Encore une fois, les requêtes
    voulant utiliser l'index doivent être écrites pour correspondre à
    l'index, donc
    <literal>WHERE to_tsvector(config_name, body) @@ 'a &amp; b'</literal>.
   </para>

   <para>
    Les index peuvent même concaténer des colonnes&nbsp;:

<programlisting>
CREATE INDEX pgweb_idx ON pgweb USING gin(to_tsvector('english', title || ' ' || body));
</programlisting>
   </para>

   <para>
    Une autre approche revient à créer une colonne <type>tsvector</type>
    séparée pour contenir le résultat de <function>to_tsvector</function>. Cet
    exemple est une concaténation de <literal>title</literal> et
    <literal>body</literal>, en utilisant <function>coalesce</function> pour
    s'assurer qu'un champ est toujours indexé même si l'autre vaut
    <literal>NULL</literal>&nbsp;:

<programlisting>
ALTER TABLE pgweb ADD COLUMN textsearchable_index_col tsvector;
UPDATE pgweb SET textsearchable_index_col =
     to_tsvector('english', coalesce(title,'') || ' ' || coalesce(body,''));
</programlisting>

    Puis nous créons un index <acronym>GIN</acronym> pour accélérer la
    recherche&nbsp;:

<programlisting>
CREATE INDEX textsearch_idx ON pgweb USING gin(textsearchable_index_col);
</programlisting>

    Maintenant, nous sommes prêt pour des recherches plein texte rapides&nbsp;:

<programlisting>
SELECT title
FROM pgweb
WHERE textsearchable_index_col @@ to_tsquery('create &amp; table')
ORDER BY last_mod_date DESC LIMIT 10;
</programlisting>
   </para>

   <para>
    Lors de l'utilisation d'une colonne séparée pour stocker la représentation
    <type>tsvector</type>, il est nécessaire d'ajouter un trigger pour
    obtenir une colonne <type>tsvector</type> à jour à tout moment suivant les
    modifications de <literal>title</literal> et <literal>body</literal>. La
    <xref linkend="textsearch-update-triggers"/> explique comment le faire.
   </para>

   <para>
    Un avantage de l'approche de la colonne séparée sur un index par
    expression est qu'il n'est pas nécessaire de spécifier explicitement la
    configuration de recherche plein texte dans les requêtes pour utiliser
    l'index. Comme indiqué dans l'exemple ci-dessus, la requête peut dépendre
    de <varname>default_text_search_config</varname>. Un autre avantage est que
    les recherches seront plus rapides car il n'est plus nécessaire de refaire
    des appels à <function>to_tsvector</function> pour vérifier la
    correspondance de l'index. (Ceci est plus important lors de l'utilisation
    d'un index GiST par rapport à un index GIN&nbsp;; voir la <xref
    linkend="textsearch-indexes"/>.)
    Néanmoins, l'approche de l'index par expression est plus simple à
    configurer et elle réclame moins d'espace disque car la représentation
    <type>tsvector</type> n'est pas réellement stockée.
   </para>

  </sect2>

 </sect1>

 <sect1 id="textsearch-controls">
  <title>Contrôler la recherche plein texte</title>

  <para>
   Pour implémenter la recherche plein texte, une fonction doit permettre la
   création d'un <type>tsvector</type> à partir d'un document et la création
   d'un <type>tsquery</type> à partir de la requête d'un utilisateur. De plus,
   nous avons besoin de renvoyer les résultats dans un ordre utile, donc nous
   avons besoin d'une fonction de comparaison des documents suivant leur
   adéquation à la recherche. Il est aussi important de pouvoir afficher
   joliment les résultats. <productname>PostgreSQL</productname> fournit un
   support pour toutes ces fonctions.
  </para>

  <sect2 id="textsearch-parsing-documents">
   <title>Analyser des documents</title>

   <para>
    <productname>PostgreSQL</productname> fournit la fonction
    <function>to_tsvector</function> pour convertir un document vers le type de
    données <type>tsvector</type>.
   </para>

   <indexterm>
    <primary>to_tsvector</primary>
   </indexterm>

   <synopsis>
    to_tsvector(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type>, </optional> <replaceable class="parameter">document</replaceable> <type>text</type>) returns <type>tsvector</type>
   </synopsis>

   <para>
    <function>to_tsvector</function> analyse un document texte et le convertit
    en jetons, réduit les jetons en des lexemes et renvoie un
    <type>tsvector</type> qui liste les lexemes avec leur position dans le
    document. Ce dernier est traité suivant la configuration de recherche
    plein texte spécifiée ou celle par défaut. Voici un exemple simple&nbsp;:

<programlisting>
SELECT to_tsvector('english', 'a fat  cat sat on a mat - it ate a fat rats');
                  to_tsvector
-----------------------------------------------------
 'ate':9 'cat':3 'fat':2,11 'mat':7 'rat':12 'sat':4
</programlisting>
   </para>

   <para>
    Dans l'exemple ci-dessus, nous voyons que le <type>tsvector</type>
    résultant ne contient pas les mots <literal>a</literal>, <literal>on</literal>
    et <literal>it</literal>, le mot <literal>rats</literal> est devenu
    <literal>rat</literal> et le signe de ponctuation <literal>-</literal> a
    été ignoré.
   </para>

   <para>
    En interne, la fonction <function>to_tsvector</function> appelle un analyseur
    qui casse le texte en jetons et affecte un type à chaque jeton. Pour chaque
    jeton, une liste de dictionnaires (<xref linkend="textsearch-dictionaries"/>)
    est consultée, liste pouvant varier suivant le type de jeton. Le premier
    dictionnaire qui <firstterm>reconnaît</firstterm> le jeton émet un ou
    plusieurs <firstterm>lexemes</firstterm> pour représenter le jeton. Par
    exemple, <literal>rats</literal> devient <literal>rat</literal> car un des
    dictionnaires sait que le mot <literal>rats</literal> est la forme pluriel
    de <literal>rat</literal>. Certains mots sont reconnus comme des
    <firstterm>termes courants</firstterm> (<xref linkend="textsearch-stopwords"/>),
    ce qui fait qu'ils sont ignorés car ils surviennent trop fréquemment pour
    être utile dans une recherche. Dans notre exemple, il s'agissait de
    <literal>a</literal>, <literal>on</literal> et <literal>it</literal>. Si
    aucun dictionnaire de la liste ne reconnaît le jeton, il est aussi ignoré.
    Dans cet exemple, il s'agit du signe de ponctuation <literal>-</literal>
    car il n'existe aucun dictionnaire affecté à ce type de jeton
    (<literal>Space symbols</literal>), ce qui signifie que les jetons espace
    ne seront jamais indexés. Le choix de l'analyseur, des dictionnaires et des
    types de jetons à indexer est déterminé par la configuration de recherche
    plein texte sélectionné (<xref linkend="textsearch-configuration"/>). Il est
    possible d'avoir plusieurs configurations pour la même base, et des
    configurations prédéfinies sont disponibles pour différentes langues. Dans
    notre exemple, nous avons utilisé la configuration par défaut, à savoir
    <literal>english</literal> pour l'anglais.
   </para>

   <para>
    La fonction <function>setweight</function> peut être utilisé pour ajouter
    un label aux entrées d'un <type>tsvector</type> avec un
    <firstterm>poids</firstterm> donné. Ce poids consiste en une lettre&nbsp;:
    <literal>A</literal>, <literal>B</literal>, <literal>C</literal> ou
    <literal>D</literal>. Elle est utilisée typiquement pour marquer les entrées
    provenant de différentes parties d'un document, comme le titre et le corps.
    Plus tard, cette information peut être utilisée pour modifier le score des
    résultats.
   </para>

   <para>
    Comme <function>to_tsvector</function>(<literal>NULL</literal>) renvoie
    <literal>NULL</literal>, il est recommandé d'utiliser
    <function>coalesce</function> quand un champ peut être NULL. Voici la
    méthode recommandée pour créer un <type>tsvector</type> à partir d'un
    document structuré&nbsp;:

<programlisting>
UPDATE tt SET ti =
    setweight(to_tsvector(coalesce(title,'')), 'A')    ||
    setweight(to_tsvector(coalesce(keyword,'')), 'B')  ||
    setweight(to_tsvector(coalesce(abstract,'')), 'C') ||
    setweight(to_tsvector(coalesce(body,'')), 'D');
</programlisting>

    Ici nous avons utilisé <function>setweight</function> pour ajouter un label
    au source de chaque lexeme dans le <type>tsvector</type> final, puis
    assemblé les valeurs <type>tsvector</type> en utilisant l'opérateur de
    concaténation des <type>tsvector</type>, <literal>||</literal>.  (La <xref
    linkend="textsearch-manipulate-tsvector"/> donne des détails sur ces
    opérations.)
   </para>

  </sect2>

  <sect2 id="textsearch-parsing-queries">
   <title>Analyser des requêtes</title>

   <para>
    <productname>PostgreSQL</productname> fournit les fonctions
    <function>to_tsquery</function> et <function>plainto_tsquery</function> pour
    convertir une requête dans le type de données <type>tsquery</type>.
    <function>to_tsquery</function> offre un accès à d'autres fonctionnalités
    que <function>plainto_tsquery</function> mais est moins indulgent sur ses
    arguments.
   </para>

   <indexterm>
    <primary>to_tsquery</primary>
   </indexterm>

   <synopsis>
    to_tsquery(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type>, </optional> <replaceable class="parameter">querytext</replaceable> <type>text</type>) returns <type>tsquery</type>
   </synopsis>

   <para>
    <function>to_tsquery</function> crée une valeur <type>tsquery</type> à
    partir de <replaceable>querytext</replaceable> qui doit contenir un
    ensemble de jetons
    individuels séparés par les opérateurs booléens <literal>&amp;</literal>
    (AND), <literal>|</literal> (OR) et <literal>!</literal> (NOT). Ces
    opérateurs peuvent être groupés en utilisant des parenthèses. En d'autres
    termes, les arguments de <function>to_tsquery</function> doivent déjà suivre
    les règles générales pour un <type>tsquery</type> comme décrit dans la <xref
    linkend="datatype-textsearch"/>. La différence est que, alors qu'un
    <type>tsquery</type> basique prend les jetons bruts,
    <function>to_tsquery</function> normalise chaque jeton en un lexeme en
    utilisant la configuration spécifiée ou par défaut, et annule tout jeton qui
    est un terme courant d'après la configuration. Par exemple&nbsp;:

<programlisting>
SELECT to_tsquery('english', 'The &amp; Fat &amp; Rats');
  to_tsquery   
---------------
 'fat' &amp; 'rat'
</programlisting>

    Comme une entrée <type>tsquery</type> basique, des poids peuvent être
    attachés à chaque lexeme à restreindre pour établir une correspondance
    avec seulement des lexemes <type>tsvector</type> de ces poids. Par
    exemple&nbsp;:

<programlisting>
SELECT to_tsquery('english', 'Fat | Rats:AB');
    to_tsquery    
------------------
 'fat' | 'rat':AB
</programlisting>

    <function>to_tsquery</function> peut aussi accepter des phrases avec des
    guillemets simples. C'est utile quand la configuration inclut un
    dictionnaire
    thésaurus qui peut se déclencher sur de telles phrases. Dans l'exemple
    ci-dessous, un thésaurus contient la règle <literal>supernovae
    stars : sn</literal>&nbsp;:

<programlisting>
SELECT to_tsquery('''supernovae stars'' &amp; !crab');
  to_tsquery
---------------
 'sn' &amp; !'crab'
</programlisting>

    sans guillemets, <function>to_tsquery</function> génère une erreur de
    syntaxe pour les jetons qui ne sont pas séparés par un opérateur AND ou OR.
   </para>

   <indexterm>
    <primary>plainto_tsquery</primary>
   </indexterm>

   <synopsis>
    plainto_tsquery(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type>, </optional> <replaceable class="parameter">querytext</replaceable> <type>text</type>) returns <type>tsquery</type>
   </synopsis>

   <para>
    <function>plainto_tsquery</function> transforme le texte non formaté
    <replaceable>querytext</replaceable> en <type>tsquery</type>. Le texte est
    analysé et normalisé un peu comme pour <function>to_tsvector</function>,
    ensuite l'opérateur booléen <literal>&amp;</literal> (AND) est inséré entre
    les mots restants.
   </para>

   <para>
    Exemple&nbsp;:

<programlisting>
 SELECT plainto_tsquery('english', 'The Fat Rats');
 plainto_tsquery 
-----------------
 'fat' &amp; 'rat'
</programlisting>

    Notez que <function>plainto_tsquery</function> ne peut pas reconnaître un
    opérateur booléen ou des labels de poids en entrée&nbsp;:

<programlisting>
SELECT plainto_tsquery('english', 'The Fat &amp; Rats:C');
   plainto_tsquery   
---------------------
 'fat' &amp; 'rat' &amp; 'c'
</programlisting>

    Ici, tous les symboles de ponctuation ont été annulés car ce sont des
    symboles espace.
   </para>

  </sect2>

  <sect2 id="textsearch-ranking">
   <title>Ajouter un score aux résultats d'une recherche</title>

   <para>
    Les tentatives de score pour mesurer l'adéquation des documents se font
    par rapport à une certaine requête. Donc, quand il y a beaucoup de
    correspondances, les meilleurs doivent être montrés en premier.
    <productname>PostgreSQL</productname> fournit deux fonctions prédéfinies de
    score, prennant en compte l'information lexicale, la proximité et la
    structure&nbsp;; en fait, elles considèrent le nombre de fois où les termes
    de la requête apparaissent dans le document, la proximité des termes de la
    recherche avec ceux de la requête et l'importance du passage du document
    où se trouvent les termes du document. Néanmoins, le concept d'adéquation
    pourrait demander plus d'informations pour calculer le score, par exemple
    la date et l'heure de modification du document. Les fonctions internes de
    calcul de score sont seulement des exemples. Vous pouvez écrire vos propres
    fonctions de score et/ou combiner leur résultats avec des facteurs
    supplémentaires pour remplir un besoin spécifique.
   </para>

   <para>
    Les deux fonctions de score actuellement disponibles sont&nbsp;:

    <variablelist>

     <varlistentry>

      <term>

       <indexterm>
        <primary>ts_rank</primary>
       </indexterm>
      
       <synopsis>
        ts_rank(<optional> <replaceable class="parameter">weights</replaceable> <type>float4[]</type>, </optional> <replaceable class="parameter">vector</replaceable> <type>tsvector</type>, <replaceable class="parameter">query</replaceable> <type>tsquery</type> <optional>, <replaceable class="parameter">normalization</replaceable> <type>integer</type> </optional>) returns <type>float4</type>
       </synopsis>
      </term>

      <listitem>
       <para>
        Fonction de score standard.<!-- TODO document this better -->
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>

      <term>

       <indexterm>
        <primary>ts_rank_cd</primary>
       </indexterm>

       <synopsis>
        ts_rank_cd(<optional> <replaceable class="parameter">weights</replaceable> <type>float4[]</type>, </optional> <replaceable class="parameter">vector</replaceable> <type>tsvector</type>, <replaceable class="parameter">query</replaceable> <type>tsquery</type> <optional>, <replaceable class="parameter">normalization</replaceable> <type>integer</type> </optional>) returns <type>float4</type>
       </synopsis>
      </term>

      <listitem>
       <para>
        Cette fonction calcule le score de la <firstterm>densité de
        couverture</firstterm> pour le vecteur du document et la requête donnés,
        comme décrit dans l'article de Clarke, Cormack et Tudhope,
	<quote>Relevance Ranking for One to Three Term Queries</quote>, article
	paru dans le journal <quote>Information Processing and
	Management</quote> en 1999.
       </para>

       <para>
        Cette fonction nécessite des informations de position. Du coup, elle
        ne fonctionne pas sur des valeurs <type>tsvector</type>
        <quote>strippées</quote> &mdash; elle renvoie toujours zéro.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>

   </para>

   <para>
    Pour ces deux fonctions, l'argument optionnel des <replaceable
    class="parameter">poids</replaceable> offre la possibilité d'impacter
    certains mots plus ou moins suivant la façon dont ils sont marqués. Le
    tableau de poids indique à quel point chaque catégorie de mots est marquée.
    Dans l'ordre&nbsp;:

<programlisting>
{poids-D, poids-C, poids-B, poids-A}
</programlisting>

    Si aucun <replaceable class="parameter">poids</replaceable> n'est fourni,
    alors ces valeurs par défaut sont utilisées&nbsp;:

<programlisting>
{0.1, 0.2, 0.4, 1.0}
</programlisting>

    Typiquement, les poids sont utilisés pour marquer les mots compris dans
    des aires spéciales du document, comme le titre ou le résumé initial, pour
    qu'ils puissent être traités avec plus ou moins d'importance que les mots
    dans le corps du document.
   </para>

   <para>
    Comme un document plus long a plus de chance de contenir un terme de la
    requête, il est raisonnable de prendre en compte la taille du document,
    par exemple un document de cent mots contenant cinq fois un mot de la
    requête est probablement plus intéressant qu'un document de mille mots
    contenant lui-aussi cinq fois un mot de la requête. Les deux fonctions de
    score prennent une option <replaceable>normalization</replaceable>, de type
    integer, qui précise si la longueur du document doit impacter son score.
    L'option contrôle plusieurs comportements, donc il s'agit d'un masque de
    bits&nbsp;: vous pouvez spécifier un ou plusieurs comportements en utilisant
    <literal>|</literal> (par exemple, <literal>2|4</literal>).

    <itemizedlist  spacing="compact" mark="bullet">
     <listitem>
      <para>
       0 (valeur par défaut) ignore la longueur du document
      </para>
     </listitem>
     <listitem>
      <para>
       1 divise le score par 1 + le logarithme de la longueur du document
      </para>
     </listitem>
     <listitem>
      <para>
       2 divise le score par la longueur du document
      </para>
     </listitem>
     <listitem>
      <para>
       4 divise le score par "mean harmonic distance between extents"
       (ceci est implémenté seulement par <function>ts_rank_cd</function>)
      </para>
     </listitem>
     <listitem>
      <para>
       8 divise le score par le nombre de mots uniques dans le document
      </para>
     </listitem>
     <listitem>
      <para>
       16 divise le score par 1 + le logarithme du nombre de mots uniques dans
       le document
      </para>
     </listitem>
     <listitem>
      <para>
       32 divise le score par lui-même + 1
      </para>
     </listitem>
    </itemizedlist>

    Si plus d'un bit de drapeau est indiqué, les transformations sont appliquées
    dans l'ordre indiqué.
   </para>

   <para>
    Il est important de noter que les fonctions de score n'utilisent aucune
    information globale donc il est impossible de produire une normalisation de
    1% ou 100%, comme c'est parfois demandé. L'option de normalisation 32
    (<literal>score/(score+1)</literal>) peut s'appliquer pour échelonner
    tous les scores dans une échelle de zéro à un mais, bien sûr, c'est
    une petite modification cosmétique, donc l'ordre des résultats ne changera
    pas.
   </para>

   <para>
    Voici un exemple qui sélectionne seulement les dix correspondances de
    meilleur score&nbsp;:

<programlisting>
SELECT title, ts_rank_cd(textsearch, query) AS rank
FROM apod, to_tsquery('neutrino|(dark &amp; matter)') query
WHERE query @@ textsearch
ORDER BY rank DESC LIMIT 10;
                     title                     |   rank
-----------------------------------------------+----------
 Neutrinos in the Sun                          |      3.1
 The Sudbury Neutrino Detector                 |      2.4
 A MACHO View of Galactic Dark Matter          |  2.01317
 Hot Gas and Dark Matter                       |  1.91171
 The Virgo Cluster: Hot Plasma and Dark Matter |  1.90953
 Rafting for Solar Neutrinos                   |      1.9
 NGC 4650A: Strange Galaxy and Dark Matter     |  1.85774
 Hot Gas and Dark Matter                       |   1.6123
 Ice Fishing for Cosmic Neutrinos              |      1.6
 Weak Lensing Distorts the Universe            | 0.818218
</programlisting>

    Voici le même exemple en utilisant un score normalisé&nbsp;:

<programlisting>
SELECT title, ts_rank_cd(textsearch, query, 32 /* rank/(rank+1) */ ) AS rank
FROM apod, to_tsquery('neutrino|(dark &amp; matter)') query
WHERE  query @@ textsearch
ORDER BY rank DESC LIMIT 10;
                     title                     |        rank
-----------------------------------------------+-------------------
 Neutrinos in the Sun                          | 0.756097569485493
 The Sudbury Neutrino Detector                 | 0.705882361190954
 A MACHO View of Galactic Dark Matter          | 0.668123210574724
 Hot Gas and Dark Matter                       |  0.65655958650282
 The Virgo Cluster: Hot Plasma and Dark Matter | 0.656301290640973
 Rafting for Solar Neutrinos                   | 0.655172410958162
 NGC 4650A: Strange Galaxy and Dark Matter     | 0.650072921219637
 Hot Gas and Dark Matter                       | 0.617195790024749
 Ice Fishing for Cosmic Neutrinos              | 0.615384618911517
 Weak Lensing Distorts the Universe            | 0.450010798361481
</programlisting>
   </para>

   <para>
    Le calcul du score peut consommer beaucoup de ressources car il demande
    de consulter le <type>tsvector</type> de chaque document correspondant, ce
    qui est très consommateur en entrées/sorties et du coup lent. Malheureusement,
    c'est presque impossible à éviter car les requêtes intéressantes ont un
    grand nombre de correspondances.
   </para>

  </sect2>

  <sect2 id="textsearch-headline">
   <title>Surligner les résultats</title>

   <para>
    Pour présenter les résultats d'une recherche, il est préférable d'afficher
    une partie de chaque document et en quoi cette partie concerne la requête.
    Habituellement, les moteurs de recherche affichent des fragments du document
    avec des marques pour les termes recherchés.
    <productname>PostgreSQL</productname> fournit une fonction
    <function>ts_headline</function> qui implémente cette fonctionnalité.
   </para>

   <indexterm>
    <primary>ts_headline</primary>
   </indexterm>

   <synopsis>
    ts_headline(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type>, </optional> <replaceable class="parameter">document</replaceable> <type>text</type>, <replaceable class="parameter">query</replaceable> <type>tsquery</type> <optional>, <replaceable class="parameter">options</replaceable> <type>text</type> </optional>) returns <type>text</type>
   </synopsis>

   <para>
    <function>ts_headline</function> accepte un document avec une requête et
    renvoie un résumé du document.
    Les termes de la requête sont surlignés dans les extractions. La
    configuration à utiliser pour analyser le document peut être précisée par
    <replaceable>config</replaceable>&nbsp;; si <replaceable>config</replaceable>
    est omis, le paramètre <varname>default_text_search_config</varname> est
    utilisé.
   </para>

   <para>
    Si une chaîne <replaceable>options</replaceable> est spécifiée, elle doit
    consister en une liste de une ou plusieurs paires
    <replaceable>option</replaceable><literal>=</literal><replaceable>valeur</replaceable>
    séparées par des virgules. Les options disponibles sont&nbsp;:

    <itemizedlist  spacing="compact" mark="bullet">
     <listitem>
      <para>
       <literal>StartSel</literal>, <literal>StopSel</literal>&nbsp;: les chaînes
       qui permettent de délimiter les mots de la requête parmi le reste des
       mots.
      </para>
     </listitem>
     <listitem >
      <para>
       <literal>MaxWords</literal>, <literal>MinWords</literal>&nbsp;: ces
       nombres déterminent les limites minimum et maximum des résumés à
       afficher.
      </para>
     </listitem>
     <listitem>
      <para>
       <literal>ShortWord</literal>&nbsp;: les mots de cette longueur et les mots
       plus petits seront supprimés au début et à la fin d'un résumé. La valeur
       par défaut est de trois pour éliminer les articles anglais.
      </para>
     </listitem>
     <listitem>
      <para>
       <literal>HighlightAll</literal>&nbsp;: booléen&nbsp;; si
       <literal>true</literal>, le document complet sera surligné.
      </para>
     </listitem>
    </itemizedlist>

    Toute option omise recevra une valeur par défaut&nbsp;:

<programlisting>
StartSel=&lt;b&gt;, StopSel=&lt;/b&gt;, MaxWords=35, MinWords=15, ShortWord=3, HighlightAll=FALSE
</programlisting>
   </para>

   <para>
    Par exemple&nbsp;:

<programlisting>
SELECT ts_headline('english', 'The most common type of search
is to find all documents containing given query terms 
and return them in order of their similarity to the
query.', to_tsquery('query &amp; similarity'));
                        ts_headline                         
------------------------------------------------------------
 given &lt;b&gt;query&lt;/b&gt; terms
 and return them in order of their &lt;b&gt;similarity&lt;/b&gt; to the
 &lt;b&gt;query&lt;/b&gt;.

SELECT ts_headline('english', 'The most common type of search
is to find all documents containing given query terms
and return them in order of their similarity to the
query.',
  to_tsquery('query &amp; similarity'), 
  'StartSel = &lt;, StopSel = &gt;');
                      ts_headline                      
-------------------------------------------------------
 given &lt;query&gt; terms
 and return them in order of their &lt;similarity&gt; to the
 &lt;query&gt;.
</programlisting>
   </para>

   <para>
    <function>ts_headline</function> utilise le document original, pas un résumé
    <type>tsvector</type>, donc elle peut être lente et doit être utilisée
    avec parcimonie et attention. Une erreur typique est d'appeler
    <function>ts_headline</function> pour <emphasis>chaque</emphasis> document
    correspondant quand seuls dix documents sont à afficher. Les sous-requêtes
    <acronym>SQL</acronym> peuvent aider&nbsp;; voici un exemple&nbsp;:

<programlisting>
SELECT id, ts_headline(body, q), rank
FROM (SELECT id, body, q, ts_rank_cd(ti, q) AS rank
      FROM apod, to_tsquery('stars') q
      WHERE ti @@ q
      ORDER BY rank DESC LIMIT 10) AS foo;
</programlisting>
   </para>

  </sect2>

 </sect1>

 <sect1 id="textsearch-features">
  <title>Fonctionnalités supplémentaires</title>

  <para>
   Cette section décrit des fonctions et opérateurs supplémentaires qui sont
   utiles en relation avec la recherche plein texte.
  </para>

  <sect2 id="textsearch-manipulate-tsvector">
   <title>Manipuler des documents</title>

   <para>
    La <xref linkend="textsearch-parsing-documents"/> a montré comment des
    documents
    en texte brut peuvent être convertis en valeurs <type>tsvector</type>.
    <productname>PostgreSQL</productname> fournit aussi des fonctions et des
    opérateurs pouvant être utilisés pour manipuler des documents qui sont déjà
    au format <type>tsvector</type>.
   </para>

   <variablelist>

    <varlistentry>

     <term>
      <indexterm>
       <primary>concaténation de tsvector</primary>
      </indexterm>

      <synopsis>
       <type>tsvector</type> || <type>tsvector</type>
      </synopsis>
     </term>

     <listitem>
      <para>
       L'opérateur de concaténation <type>tsvector</type> renvoie un vecteur
       qui combine les lexemes et des informations de position pour les deux
       vecteurs donnés en argument. Les positions et les labels de poids sont
       conservés lors de la concaténation. Les positions apparaissant dans le
       vecteur droit sont décalés par la position la plus large mentionnée dans
       le vecteur gauche, pour que le résultat soit pratiquement équivalent au
       résultat du traitement de <function>to_tsvector</function> sur la
       concaténation des deux documents originaux. (L'équivalence n'est pas
       exacte car tout terme courant supprimé de la fin de l'argument gauche
       n'affectera pas le résultat alors qu'ils auraient affecté les positions
       des lexemes dans l'argument droit si la concaténation de texte avait été
       utilisée.)
      </para>

      <para>
       Un avantage de l'utilisation de la concaténation au format vecteur,
       plutôt que la concaténation de texte avant d'appliquer
       <function>to_tsvector</function>, est que vous pouvez utiliser
       différentes configurations pour analyser les différentes sections du
       document. De plus, comme la fonction <function>setweight</function> marque
       tous les lexemes du secteur donné de la même façon, il est nécessaire
       d'analyser le texte et de lancer <function>setweight</function> avant la
       concaténation si vous voulez des labels de poids différents sur les
       différentes parties du document.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>

      <indexterm>
       <primary>setweight</primary>
      </indexterm>
     
      <synopsis>
       setweight(<replaceable class="parameter">vector</replaceable> <type>tsvector</type>, <replaceable class="parameter">weight</replaceable> <type>"char"</type>) returns <type>tsvector</type>
      </synopsis>
     </term>

     <listitem>
      <para>
       Cette fonction renvoie une copie du vecteur en entrée pour chaque
       position de poids <replaceable>weight</replaceable>, soit
       <literal>A</literal>, soit <literal>B</literal>, soit <literal>C</literal>
       soit <literal>D</literal>.  (<literal>D</literal> est la valeur par
       défaut pour les nouveaux vecteurs et, du coup, n'est pas affiché en
       sortie.) Ces labels sont conservés quand les vecteurs sont concaténés,
       permettant aux mots des différentes parties d'un document de se voir
       attribuer un poids différent par les fonctions de score.
      </para>

      <para>
       Notez que les labels de poids s'appliquent seulement aux
       <emphasis>positions</emphasis>, pas aux <emphasis>lexemes</emphasis>. Si
       le vecteur en entrée se voit supprimer les positions, alors
       <function>setweight</function> ne pourra rien faire.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>

     <term>
      <indexterm>
       <primary>length(tsvector)</primary>
      </indexterm>
          
      <synopsis>
       length(<replaceable class="parameter">vector</replaceable> <type>tsvector</type>) returns <type>integer</type>
      </synopsis>
     </term>

     <listitem>
      <para>
       Renvoie le nombre de lexemes enregistrés dans le vecteur.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>

     <term>
      <indexterm>
       <primary>strip</primary>
      </indexterm>
      
      <synopsis>
       strip(<replaceable class="parameter">vector</replaceable> <type>tsvector</type>) returns <type>tsvector</type>
      </synopsis>
     </term>

     <listitem>
      <para>
       Renvoie un vecteur qui liste les mêmes lexemes que le vecteur donné mais
       il manquera les informations de position et de poids. Alors que le vecteur
       renvoyé est bien moins utile qu'un vecteur normal pour calculer le score,
       il est habituellement bien plus petit.
      </para>
     </listitem>

    </varlistentry>

   </variablelist>

  </sect2>

  <sect2 id="textsearch-manipulate-tsquery">
   <title>Manipuler des requêtes</title>

   <para>
    La <xref linkend="textsearch-parsing-queries"/> a montré comment des
    requêtes
    texte peuvent être converties en valeurs de type <type>tsquery</type>.
    <productname>PostgreSQL</productname> fournit aussi des fonctions et des
    opérateurs pouvant être utilisés pour manipuler des requêtes qui sont déjà
    de la forme <type>tsquery</type>.
   </para>

   <variablelist>

    <varlistentry>

     <term>
      <synopsis>
       <type>tsquery</type> &amp;&amp; <type>tsquery</type>
      </synopsis>
     </term>

     <listitem>
      <para>
       Renvoie une combinaison AND des deux requêtes données.
      </para>
     </listitem>

    </varlistentry>

    <varlistentry>

     <term>
      <synopsis>
       <type>tsquery</type> || <type>tsquery</type>
      </synopsis>
     </term>

     <listitem>
      <para>
       Renvoie une combinaison OR des deux requêtes données.
      </para>
     </listitem>

    </varlistentry>

    <varlistentry>

     <term>
      <synopsis>
       !! <type>tsquery</type>
      </synopsis>
     </term>

     <listitem>
      <para>
       Renvoie la négation (NOT) de la requête donnée.
      </para>
     </listitem>

    </varlistentry>

    <varlistentry>

     <term>

      <indexterm>
       <primary>numnode</primary>
      </indexterm>

      <synopsis>
       numnode(<replaceable class="parameter">query</replaceable> <type>tsquery</type>) returns <type>integer</type>
      </synopsis>
     </term>

     <listitem>
      <para>
       Renvoie le nombre de nœuds (lexemes et opérateurs) dans un
       <type>tsquery</type>. Cette fonction est utile pour déterminer si la
       requête (<replaceable>query</replaceable>) a un sens
       (auquel cas elle renvoie &gt; 0) ou s'il ne contient que des termes
       courants (auquel cas elle renvoie 0).
       Exemples&nbsp;:

<programlisting>
SELECT numnode(plainto_tsquery('the any'));
NOTICE:  query contains only stopword(s) or doesn't contain lexeme(s), ignored
 numnode
---------
       0

SELECT numnode('foo &amp; bar'::tsquery);
 numnode
---------
       3
</programlisting>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>

     <term>

      <indexterm>
       <primary>querytree</primary>
      </indexterm>

      <synopsis>
       querytree(<replaceable class="parameter">query</replaceable> <type>tsquery</type>) returns <type>text</type>
      </synopsis>
     </term>

     <listitem>
      <para>
       Renvoie la portion d'un <type>tsquery</type> qui peut être utilisé pour
       rechercher dans un index.Cette fonction est utile pour détecter les
       requêtes qui ne peuvent pas utiliser un index, par exemple celles qui
       contiennent des termes courants ou seulement des négations de termes. Par
       exemple&nbsp;:

<programlisting>
SELECT querytree(to_tsquery('!defined'));
 querytree
-----------

</programlisting>
      </para>
     </listitem>
    </varlistentry>

   </variablelist>

   <sect3 id="textsearch-query-rewriting">
    <title>Ré-écriture des requêtes</title>

    <indexterm zone="textsearch-query-rewriting">
     <primary>ts_rewrite</primary>
    </indexterm>

    <para>
     La famille de fonctions <function>ts_rewrite</function> cherche dans un
     <type>tsquery</type> donné les occurrences d'une sous-requête cible et
     remplace chaque occurrence avec une autre sous-requête de substitution.
     En fait, cette opération est une version spécifique à
     <type>tsquery</type> d'un remplacement de sous-chaîne. Une combinaison
     cible
     et substitut peut être vu comme une <firstterm>règle de ré-écriture de la
     requête</firstterm>. Un ensemble de règles de ré-écriture peut être une
     aide puissante à la recherche. Par exemple, vous pouvez étendre la
     recherche en utilisant des synonymes (<literal>new york</literal>,
     <literal>big apple</literal>, <literal>nyc</literal>,
     <literal>gotham</literal>) ou restreindre la recherche pour diriger
     l'utilisateur vers des thèmes en vogue. Cette fonctionnalité n'est pas
     sans rapport avec les thésaurus (<xref linkend="textsearch-thesaurus"/>).
     Néanmoins, vous pouvez modifier un ensemble de règles de ré-écriture
     directement, sans ré-indexer, alors que la mise à jour d'un thésaurus
     nécessite un ré-indexage pour être pris en compte.
    </para>

    <variablelist>

     <varlistentry>

      <term>
       <synopsis>
        ts_rewrite (<replaceable class="parameter">query</replaceable> <type>tsquery</type>, <replaceable class="parameter">target</replaceable> <type>tsquery</type>, <replaceable class="parameter">substitute</replaceable> <type>tsquery</type>) returns <type>tsquery</type>
       </synopsis>
      </term>

      <listitem>
       <para>
        Cette forme de <function>ts_rewrite</function> applique simplement une
	seule règle de ré-écriture&nbsp;: <replaceable
        class="parameter">target</replaceable> est remplacé par
	<replaceable class="parameter">substitute</replaceable>
        partout où il apparaît dans <replaceable
        class="parameter">query</replaceable>. Par exemple&nbsp;:

<programlisting>
SELECT ts_rewrite('a &amp; b'::tsquery, 'a'::tsquery, 'c'::tsquery);
 ts_rewrite
------------
 'b' &amp; 'c'
</programlisting>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>

      <term>
       <synopsis>
        ts_rewrite (<replaceable class="parameter">query</replaceable> <type>tsquery</type>, <replaceable class="parameter">select</replaceable> <type>text</type>) returns <type>tsquery</type>
       </synopsis>
      </term>

      <listitem>
       <para>
        Cette forme de <function>ts_rewrite</function> accepte une
        <replaceable>query</replaceable> de début et une commande SQL
	<replaceable>select</replaceable>, qui est fournie comme une chaîne de
	caractères. <replaceable>select</replaceable> doit renvoyer deux colonnes
	de type <type>tsquery</type>. Pour chaque ligne de résultats du
        <replaceable>select</replaceable>, les occurrences de la valeur de la
	première colonne (la cible) sont remplacées par la valeur de la
	deuxième colonne (le substitut) dans la valeur actuelle de
        <replaceable>query</replaceable>. Par exemple&nbsp;:

<programlisting>
CREATE TABLE aliases (t tsquery PRIMARY KEY, s tsquery);
INSERT INTO aliases VALUES('a', 'c');

SELECT ts_rewrite('a &amp; b'::tsquery, 'SELECT t,s FROM aliases');
 ts_rewrite
------------
 'b' &amp; 'c'
</programlisting>
       </para>

       <para>
        Notez que, quand plusieurs règles de ré-écriture sont appliquées de cette
	façon, l'ordre d'application peut être important&nbsp;; donc, en
	pratique, vous voudrez que la requête source utilise <literal>ORDER
	BY</literal> avec un ordre précis.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>

    <para>
     Considérons un exemple réel pour l'astronomie. Nous étendons la requête
     <literal>supernovae</literal> en utilisant les règles de ré-écriture par
     la table&nbsp;:

<programlisting>
CREATE TABLE aliases (t tsquery primary key, s tsquery);
INSERT INTO aliases VALUES(to_tsquery('supernovae'), to_tsquery('supernovae|sn'));

SELECT ts_rewrite(to_tsquery('supernovae &amp; crab'), 'SELECT * FROM aliases');
           ts_rewrite            
---------------------------------
 'crab' &amp; ( 'supernova' | 'sn' )
</programlisting>

     Nous pouvons modifier les règles de ré-écriture simplement en mettant à
     jour la table&nbsp;:

<programlisting>
UPDATE aliases SET s = to_tsquery('supernovae|sn &amp; !nebulae') WHERE t = to_tsquery('supernovae');

SELECT ts_rewrite(to_tsquery('supernovae &amp; crab'), 'SELECT * FROM aliases');
                 ts_rewrite                  
---------------------------------------------
 'crab' &amp; ( 'supernova' | 'sn' &amp; !'nebula' )
</programlisting>
    </para>

    <para>
     La ré-écriture peut être lente quand il y a beaucoup de règles de
     ré-écriture car elle vérifie l'intérêt de chaque règle. Pour filtrer les
     règles qui ne sont pas candidates de façon évidente, nous pouvons utiliser
     les opérateurs de contenant pour le type <type>tsquery</type>. Dans
     l'exemple ci-dessous, nous sélectionnons seulement les règles qui
     peuvent correspondre avec la requête originale&nbsp;:

<programlisting>
SELECT ts_rewrite('a &amp; b'::tsquery,
                  'SELECT t,s FROM aliases WHERE ''a &amp; b''::tsquery @&gt; t');
 ts_rewrite
------------
 'b' &amp; 'c'
</programlisting>
    </para>

   </sect3>

  </sect2>

  <sect2 id="textsearch-update-triggers">
   <title>Triggers pour les mises à jour automatiques</title>

   <indexterm>
    <primary>trigger</primary>
    <secondary>pour mettre à jour une colonne tsvector dérivée</secondary>
   </indexterm>

   <para>
    Lors de l'utilisation d'une colonne séparée pour stocker la représentation
    <type>tsvector</type> de vos documents, il est nécessaire de créer un
    trigger pour mettre à jour la colonne <type>tsvector</type> quand le
    contenu des colonnes document change. Deux fonctions trigger intégrées
    sont disponibles pour cela, mais vous pouvez aussi écrire la vôtre.
   </para>

   <synopsis>
    tsvector_update_trigger(<replaceable class="parameter">tsvector_column_name</replaceable>, <replaceable class="parameter">config_name</replaceable>, <replaceable class="parameter">text_column_name</replaceable> <optional>, ... </optional>)
    tsvector_update_trigger_column(<replaceable class="parameter">tsvector_column_name</replaceable>, <replaceable class="parameter">config_column_name</replaceable>, <replaceable class="parameter">text_column_name</replaceable> <optional>, ... </optional>)
   </synopsis>

   <para>
    Ces fonctions trigger calculent automatiquement une colonne
    <type>tsvector</type> à partir d'une ou plusieurs colonnes texte sous le
    contrôle des paramètres spécifiés dans la commande
    <command>CREATE TRIGGER</command>. Voici un exemple de leur
    utilisation&nbsp;:

<programlisting>
CREATE TABLE messages (
    title       text,
    body        text,
    tsv         tsvector
);

CREATE TRIGGER tsvectorupdate BEFORE INSERT OR UPDATE
ON messages FOR EACH ROW EXECUTE PROCEDURE
tsvector_update_trigger(tsv, 'pg_catalog.english', title, body);

INSERT INTO messages VALUES('title here', 'the body text is here');

SELECT * FROM messages;
   title    |         body          |            tsv             
------------+-----------------------+----------------------------
 title here | the body text is here | 'bodi':4 'text':5 'titl':1

SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title &amp; body');
   title    |         body          
------------+-----------------------
 title here | the body text is here
</programlisting>

    Après avoir créé ce trigger, toute modification dans
    <structfield>title</structfield> ou <structfield>body</structfield> sera
    automatiquement reflétée dans <structfield>tsv</structfield>, sans que
    l'application n'ait à s'en soucier.
   </para>

   <para>
    Le premier argument du trigger doit être le nom de la colonne
    <type>tsvector</type> à mettre à jour. Le second argument spécifie la
    configuration de recherche plein texte à utiliser pour réaliser la
    conversion. Pour <function>tsvector_update_trigger</function>, le nom de
    la configuration est donné en deuxième argument du trigger. Il doit être
    qualifié du nom du schéma comme indiqué ci-dessus pour que le comportement
    du trigger ne change pas avec les modifications de
    <varname>search_path</varname>. Pour
    <function>tsvector_update_trigger_column</function>, le deuxième argument du
    trigger est le nom d'une autre colonne de table qui doit être du type
    <type>regconfig</type>. Ceci permet une sélection par ligne de la
    configuration à faire. Les arguments restant sont les noms des colonnes
    texte (de type <type>text</type>, <type>varchar</type> ou
    <type>char</type>). Elles sont inclus dans le document suivant l'ordre
    donné. Les valeurs NULL sont ignorées (mais les autres colonnes sont
    toujours indexées).
   </para>

   <para>
    Une limitation des triggers internes est qu'ils traitent les colonnes de
    façon identique. Pour traiter les colonnes différemment &mdash; par
    exemple pour donner un poids plus important au titre qu'au corps &mdash;
    il est nécessaire d'écrire un trigger personnalisé. Voici un exemple
    utilisant <application>PL/pgSQL</application> comme langage du trigger&nbsp;:

<programlisting>
CREATE FUNCTION messages_trigger() RETURNS trigger AS $$
begin
  new.tsv :=
     setweight(to_tsvector('pg_catalog.english', coalesce(new.title,'')), 'A') ||
     setweight(to_tsvector('pg_catalog.english', coalesce(new.body,'')), 'D');
  return new;
end
$$ LANGUAGE plpgsql;

CREATE TRIGGER tsvectorupdate BEFORE INSERT OR UPDATE
ON messages FOR EACH ROW EXECUTE PROCEDURE messages_trigger();
</programlisting>
   </para>

   <para>
    Gardez en tête qu'il est important de spécifier explicitement le nom de la
    configuration lors de la création de valeurs <type>tsvector</type> dans des
    triggers, pour que le contenu de la colonne ne soit pas affecté par des
    modifications de <varname>default_text_search_config</varname>. Dans le cas
    contraire, des problèmes surviendront comme des résultats de recherche
    changeant après une sauvegarde/restauration.
   </para>

  </sect2>

  <sect2 id="textsearch-statistics">
   <title>Récupérer des statistiques sur les documents</title>

   <indexterm>
    <primary>ts_stat</primary>
   </indexterm>

   <para>
    La fonction <function>ts_stat</function> est utile pour vérifier votre
    configuration et pour trouver des candidats pour les termes courants.
   </para>

   <synopsis>
    ts_stat(<replaceable class="parameter">sqlquery</replaceable> <type>text</type>, <optional> <replaceable class="parameter">weights</replaceable> <type>text</type>, </optional> OUT <replaceable class="parameter">word</replaceable> <type>text</type>, OUT <replaceable class="parameter">ndoc</replaceable> <type>integer</type>, OUT <replaceable class="parameter">nentry</replaceable> <type>integer</type>) returns <type>setof record</type>
   </synopsis>

   <para>
    <replaceable>sqlquery</replaceable> est une valeur de type texte contenant
    une requête SQL qui doit renvoyer une seule colonne <type>tsvector</type>.
    <function>ts_stat</function> exécute la requête et renvoie des statistiques
    sur chaque lexeme (mot) contenu dans les données <type>tsvector</type>.
    Les colonnes renvoyées sont&nbsp;:

    <itemizedlist  spacing="compact" mark="bullet">
     <listitem>
      <para>
       <replaceable>word</replaceable> <type>text</type> &mdash; la valeur d'un
       lexeme
      </para>
     </listitem>
     <listitem>
      <para>
       <replaceable>ndoc</replaceable> <type>integer</type> &mdash; le nombre
       de documents (<type>tsvector</type>) où le mot se trouve
      </para>
     </listitem>
     <listitem>
      <para>
       <replaceable>nentry</replaceable> <type>integer</type> &mdash; le nombre
       total d'occurrences du mot
      </para>
     </listitem>
    </itemizedlist>

    Si <replaceable>weights</replaceable> est précisé, seules les occurrences
    d'un de ces poids sont comptabilisées.
   </para>

   <para>
    Par exemple, pour trouver les dix mots les plus fréquents dans un ensemble
    de document&nbsp;:

<programlisting>
SELECT * FROM ts_stat('SELECT vector FROM apod')
ORDER BY nentry DESC, ndoc DESC, word
LIMIT 10;
</programlisting>

    De la même façon, mais en ne comptant que les occurrences de poids
    <literal>A</literal> ou <literal>B</literal>&nbsp;:

<programlisting>
SELECT * FROM ts_stat('SELECT vector FROM apod', 'ab')
ORDER BY nentry DESC, ndoc DESC, word
LIMIT 10;
</programlisting>
   </para>

  </sect2>

 </sect1>

 <sect1 id="textsearch-parsers">
  <title>Analyseurs</title>

  <para>
   Les analyseurs de recherche plein texte sont responsable du découpage d'un
   document brut en <firstterm>jetons</firstterm> et d'identifier le type des
   jetons. L'ensemble des types possibles est défini par l'analyseur lui-même.
   Notez qu'un analyseur ne modifie pas le texte &mdash; il identifie les
   limites plausibles des mots. Comme son domaine est limité, il est moins
   important de pouvoir construire des analyseurs personnalisés pour une
   application. Actuellement, <productname>PostgreSQL</productname> fournit
   un seul analyseur interne qui s'est révélé utile pour un ensemble varié
   d'applications.
  </para>

  <para>
   L'analyseur interne est nommé <literal>pg_catalog.default</literal>.
   Il reconnait 23 types de jeton&nbsp;:
  </para>

  <table id="textsearch-default-parser">
   <title>Types de jeton de l'analyseur par défaut</title>
   <tgroup cols="3">
    <thead>
     <row>
      <entry>Alias</entry>
      <entry>Description</entry>
      <entry>Exemple</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry><literal>asciiword</literal></entry>
      <entry>Mot, toute lettre ASCII</entry>
      <entry><literal>elephant</literal></entry>
     </row>
     <row>
      <entry><literal>word</literal></entry>
      <entry>Mot, toute lettre</entry>
      <entry><literal>ma&ntilde;ana</literal></entry>
     </row>
     <row>
      <entry><literal>numword</literal></entry>
      <entry>Mot, lettres et chiffres</entry>
      <entry><literal>beta1</literal></entry>
     </row>
     <row>
      <entry><literal>asciihword</literal></entry>
      <entry>Mot composé, en ASCII</entry>
      <entry><literal>up-to-date</literal></entry>
     </row>
     <row>
      <entry><literal>hword</literal></entry>
      <entry>Mot composé, toutes les lettres</entry>
      <entry><literal>l&oacute;gico-matem&aacute;tica</literal></entry>
     </row>
     <row>
      <entry><literal>numhword</literal></entry>
      <entry>Mot composé, lettre et chiffre</entry>
      <entry><literal>postgresql-beta1</literal></entry>
     </row>
     <row>
      <entry><literal>hword_asciipart</literal></entry>
      <entry>Partie d'un mot composé, en ASCII</entry>
      <entry><literal>postgresql</literal> dans le contexte <literal>postgresql-beta1</literal></entry>
     </row>
     <row>
      <entry><literal>hword_part</literal></entry>
      <entry>Partie d'un mot composé, toutes les lettres</entry>
      <entry><literal>l&oacute;gico</literal> ou <literal>matem&aacute;tica</literal>
       dans le contexte <literal>l&oacute;gico-matem&aacute;tica</literal></entry>
     </row>
     <row>
      <entry><literal>hword_numpart</literal></entry>
      <entry>Partie d'un mot composé, lettres et chiffres</entry>
      <entry><literal>beta1</literal> dans le contexte
       <literal>postgresql-beta1</literal></entry>
     </row>
     <row>
      <entry><literal>email</literal></entry>
      <entry>Adresse email</entry>
      <entry><literal>foo@example.com</literal></entry>
     </row>
     <row>
      <entry><literal>protocol</literal></entry>
      <entry>En-tête de protocole</entry>
      <entry><literal>http://</literal></entry>
     </row>
     <row>
      <entry><literal>url</literal></entry>
      <entry>URL</entry>
      <entry><literal>example.com/stuff/index.html</literal></entry>
     </row>
     <row>
      <entry><literal>host</literal></entry>
      <entry>Hôte</entry>
      <entry><literal>example.com</literal></entry>
     </row>
     <row>
      <entry><literal>url_path</literal></entry>
      <entry>Chemin URL</entry>
      <entry><literal>/stuff/index.html</literal>, in the context of a URL</entry>
     </row>
     <row>
      <entry><literal>file</literal></entry>
      <entry>Fichier ou chemin</entry>
      <entry><literal>/usr/local/foo.txt</literal>, if not within a URL</entry>
     </row>
     <row>
      <entry><literal>sfloat</literal></entry>
      <entry>Notation scientifique</entry>
      <entry><literal>-1.234e56</literal></entry>
     </row>
     <row>
      <entry><literal>float</literal></entry>
      <entry>Notation décimale</entry>
      <entry><literal>-1.234</literal></entry>
     </row>
     <row>
      <entry><literal>int</literal></entry>
      <entry>Entier signé</entry>
      <entry><literal>-1234</literal></entry>
     </row>
     <row>
      <entry><literal>uint</literal></entry>
      <entry>Entier non signé</entry>
      <entry><literal>1234</literal></entry>
     </row>
     <row>
      <entry><literal>version</literal></entry>
      <entry>Numéro de version</entry>
      <entry><literal>8.3.0</literal></entry>
     </row>
     <row>
      <entry><literal>tag</literal></entry>
      <entry>Balise XML</entry>
      <entry><literal>&lt;a href="dictionaries.html"&gt;</literal></entry>
     </row>
     <row>
      <entry><literal>entity</literal></entry>
      <entry>Entité XML</entry>
      <entry><literal>&amp;amp;</literal></entry>
     </row>
     <row>
      <entry><literal>blank</literal></entry>
      <entry>Symboles espaces</entry>
      <entry>(tout espace blanc, ou signe de ponctuation non reconnu autrement)
       </entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <note>
   <para>
    La notion de l'analyseur d'une <quote>lettre</quote> est déterminée par la
    configuration de la locale sur le serveur, spécifiquement par
    <varname>lc_ctype</varname>. Les mots contenant seulement des lettres ASCII
    basiques sont reportés comme un type de jeton séparé car il est parfois
    utile de les distinguer. Dans la plupart des langues européennes, les types
    de jeton <literal>word</literal> et <literal>asciiword</literal> doivent
    toujours être traités de la même façon.
   </para>
  </note>

  <para>
   Il est possible que l'analyseur produise des jetons qui coïncident à partir
   du même texte. Comme exemple, un mot composé peut être reporté à la fois
   comme un mot entier et pour chaque composante&nbsp;:

<programlisting>
SELECT alias, description, token FROM ts_debug('foo-bar-beta1');
      alias      |               description                |     token     
-----------------+------------------------------------------+---------------
 numhword        | Hyphenated word, letters and digits      | foo-bar-beta1
 hword_asciipart | Hyphenated word part, all ASCII          | foo
 blank           | Space symbols                            | -
 hword_asciipart | Hyphenated word part, all ASCII          | bar
 blank           | Space symbols                            | -
 hword_numpart   | Hyphenated word part, letters and digits | beta1
</programlisting>

   Ce comportement est souhaitable car il autorise le bon fonctionnement de la
   recherche sur le mot composé et sur les composants. Voici un autre exemple
   instructif&nbsp;:

<programlisting>
SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.html');
  alias   |  description  |            token             
----------+---------------+------------------------------
 protocol | Protocol head | http://
 url      | URL           | example.com/stuff/index.html
 host     | Host          | example.com
 url_path | URL path      | /stuff/index.html
</programlisting>
  </para>

 </sect1>

 <sect1 id="textsearch-dictionaries">
  <title>Dictionnaires</title>

  <para>
   Les dictionnaires sont utilisés pour éliminer des mots qui ne devraient pas
   être considérés dans une recherche (<firstterm>termes courants</firstterm>),
   et pour <firstterm>normaliser</firstterm> des mots pour que des formes
   dérivées de ce même mot établissent une correspondance. Un mot normalisé avec
   succès est appelé un <firstterm>lexeme</firstterm>. En dehors d'améliorer
   la qualité de la recherche, la normalisation et la suppression des termes
   courants réduisent la taille de la représentation d'un document en
   <type>tsvector</type>, et donc améliorent les performances. La
   normalisation n'a pas toujours une signification linguistique et dépend
   habituellement de la sémantique de l'application.
  </para>

  <para>
   Quelques exemples de normalisation&nbsp;:

   <itemizedlist  spacing="compact" mark="bullet">

    <listitem>
     <para>
      Linguistique - les dictionnaires ispell tentent de réduire les mots en
      entrée en une forme normalisée&nbsp;; les dictionnaires stemmer suppriment
      la fin des mots
     </para>
    </listitem>
    <listitem>
     <para>
      Les <acronym>URL</acronym> peuvent être réduites pour établir certaines
      correspondance&nbsp;:

      <itemizedlist  spacing="compact" mark="bullet">
       <listitem>
        <para>
         http://www.pgsql.ru/db/mw/index.html
        </para>
       </listitem>
       <listitem>
        <para>
         http://www.pgsql.ru/db/mw/
        </para>
       </listitem>
       <listitem>
        <para>
         http://www.pgsql.ru/db/../db/mw/index.html
        </para>
       </listitem>
      </itemizedlist>
     </para>
    </listitem>
    <listitem>
     <para>
      Les noms de couleur peuvent être remplacés par leur valeur hexadécimale,
      par exemple
      <literal>red, green, blue, magenta -> FF0000, 00FF00, 0000FF, FF00FF</literal>
     </para>
    </listitem>
    <listitem>
     <para>
      En cas d'indexation de nombre, nous pouvons supprimer certains chiffres à
      fraction pour réduire les nombres possibles, donc par exemple
      <emphasis>3.14</emphasis>159265359, <emphasis>3.14</emphasis>15926,
      <emphasis>3.14</emphasis> seront identiques après normalisation si seuls
      deux chiffres sont conservés après le point décimal.
     </para>
    </listitem>
   </itemizedlist>

  </para>

  <para>
   Un dictionnaire est un programme qui accepte un jeton en entrée et
   renvoie&nbsp;:
   <itemizedlist  spacing="compact" mark="bullet">
    <listitem>
     <para>
      un tableau de lexemes si le jeton en entrée est connu dans le
      dictionnaire (notez qu'un jeton peut produire plusieurs lexemes)
     </para>
    </listitem>
    <listitem>
     <para>
      un tableau vide si le dictionnaire connaît le jeton mais que ce dernier
      est un terme courant
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>NULL</literal> si le dictionnaire n'a pas reconnu le jeton en
      entrée
     </para>
    </listitem>
   </itemizedlist>
  </para>

  <para>
   <productname>PostgreSQL</productname> fournit des dictionnaires prédéfinis
   pour de nombreuses langues. Il existe aussi plusieurs modèles prédéfinis qui
   peuvent être utilisés pour créer de nouveaux dictionnaires avec des paramètres
   personnalisés. Chaque modèle prédéfini de dictionnaire est décrit ci-dessous.
   Si aucun modèle ne convient, il est possible d'en créer de nouveaux&nbsp;;
   voir le répertoire <filename>contrib/</filename> de
   <productname>PostgreSQL</productname> pour des exemples.
  </para>

  <para>
   Une configuration de recherche plein texte lie un analyseur avec un ensemble
   de dictionnaires pour traiter les jetons en sortie de l'analyseur. Pour
   chaque type de jeton que l'analyseur peut renvoyer, une liste séparée de
   dictionnaires est indiquée par la configuration. Quand un jeton de ce type
   est trouvée par l'analyseur, chaque dictionnaire de la liste est consulté
   jusqu'à ce qu'un dictionnaire le reconnaisse comme un mot connu. S'il est
   identifié comme un terme courant ou si aucun dictionnaire ne le reconnait,
   il sera ignoré et non indexé. La règle générale pour la configuration de la
   liste des dictionnaires est de placer en premier les dictionnaires les plus
   précis, les plus spécifiques, puis les dictionnaires généralistes, en
   finissant avec un dictionnaire le plus général possible, comme par exemple
   un stemmer <application>Snowball</application> ou <literal>simple</literal>,
   qui reconnait tout. Par exemple, pour une recherche en astronomie
   (configuration <literal>astro_en</literal>), vous pouvez lier le type de
   jeton <type>asciiword</type> (mot ASCII) vers un dictionnaire des synonymes
   des termes de l'astronomie, un dictionnaire anglais généraliste et un stemmer
   <application>Snowball</application> anglais&nbsp;:

<programlisting>
ALTER TEXT SEARCH CONFIGURATION astro_en
    ADD MAPPING FOR asciiword WITH astrosyn, english_ispell, english_stem;
</programlisting>
  </para>

  <sect2 id="textsearch-stopwords">
   <title>Termes courants</title>

   <para>
    Les termes courants sont des mots très courants, apparaissant dans
    pratiquement chaque document et n'ont donc pas de valeur discriminatoire.
    Du coup, ils peuvent être ignorés dans le contexte de la recherche plein
    texte. Par exemple, tous les textes anglais contiennent des mots comme
    <literal>a</literal> et <literal>the</literal>, donc il est inutile de les
    stocker dans un index. Néanmoins, les termes courants n'affectent pas les
    positions dans <type>tsvector</type>, ce qui affecte le score&nbsp;:

<programlisting>
SELECT to_tsvector('english','in the list of stop words');
        to_tsvector
----------------------------
 'list':3 'stop':5 'word':6
</programlisting>

    Les positions 1, 2, 4 manquantes sont dûes aux termes courants. Les scores
    calculés pour les documents avec et sans termes courants sont vraiment
    différents&nbsp;:

<programlisting>
SELECT ts_rank_cd (to_tsvector('english','in the list of stop words'), to_tsquery('list &amp; stop'));
 ts_rank_cd
------------
       0.05

SELECT ts_rank_cd (to_tsvector('english','list stop words'), to_tsquery('list &amp; stop'));
 ts_rank_cd
------------
        0.1
</programlisting>

   </para>

   <para>
    C'est au dictionnaire de savoir comment traiter les mots courants. Par
    exemple, les dictionnaires <literal>Ispell</literal> normalisent tout
    d'abord les mots puis cherchent les termes courants alors que les
    stemmers <literal>Snowball</literal> vérifient d'abord leur liste de termes
    courants. La raison de leur comportement différent est qu'ils tentent de
    réduire le bruit.
   </para>

  </sect2>

  <sect2 id="textsearch-simple-dictionary">
   <title>Dictionnaire simple</title>

   <para>
    Le modèle du dictionnaire <literal>simple</literal> opère en convertissant
    le jeton en entrée en minuscule puis en vérifiant s'il fait partie de la
    liste des mots courants qu'il a sur fichier. S'il est trouvé dans ce
    fichier, un tableau vide est renvoyé. Le jeton sera alors ignoré.
    Dans le cas contraire, la forme minuscule du mot est renvoyé en tant que
    lexeme normalisé. Autrement, le dictionnaire peut être configuré pour
    rapporter les termes courants comme étant non reconnus, ce qui permet de
    les passer au prochain dictionnaire de la liste.
   </para>

   <para>
    Voici un exemple d'une définition de dictionnaire utilisant le modèle
    <literal>simple</literal>&nbsp;:

<programlisting>
CREATE TEXT SEARCH DICTIONARY public.simple_dict (
    TEMPLATE = pg_catalog.simple,
    STOPWORDS = english
);
</programlisting>

    Dans ce cas, <literal>english</literal> est le nom de base du fichier
    contenant les termes courants. Le nom complet du fichier sera donc
    <filename>$SHAREDIR/tsearch_data/english.stop</filename>, où
    <literal>$SHAREDIR</literal> est le répertoire des données partagées de
    l'installation de <productname>PostgreSQL</productname> (souvent
    <filename>/usr/local/share/postgresql</filename> mais utilisez
    <command>pg_config --sharedir</command> pour vous en assurer). Le format
    du fichier est une simple liste de mots, un mot par ligne. Les lignes
    vides et les espaces en fin de mot sont ignorés. Les mots en majuscule
    sont basculés en minuscule, mais aucun autre traitement n'est réalisé sur
    le contenu de ce fichier.
   </para>

   <para>
    Maintenant, nous pouvons tester notre dictionnaire&nbsp;:

<programlisting>
SELECT ts_lexize('public.simple_dict','YeS');
 ts_lexize
-----------
 {yes}

SELECT ts_lexize('public.simple_dict','The');
 ts_lexize
-----------
 {}
</programlisting>
   </para>

   <para>
    Nous pouvons aussi choisir de renvoyer <literal>NULL</literal> à la place
    du mot en minuscule s'il n'est pas trouvé dans le fichier des termes
    courants. Ce comportement est sélectionné en configurant le paramètre
    <literal>Accept</literal> du dictionnaire à <literal>false</literal>.
    En continuant l'exemple&nbsp;:

<programlisting>
ALTER TEXT SEARCH DICTIONARY public.simple_dict ( Accept = false );

SELECT ts_lexize('public.simple_dict','YeS');
 ts_lexize
-----------


SELECT ts_lexize('public.simple_dict','The');
 ts_lexize
-----------
 {}
</programlisting>
   </para>

   <para>
    Avec le paramètrage par défaut d'<literal>Accept</literal> (à savoir,
    <literal>true</literal>), il est préférable de placer un dictionnaire
    <literal>simple</literal> à la fin de la liste des dictionnaires.
    <literal>Accept</literal> = <literal>false</literal> est seulement utile
    quand il y a au moins un dictionnaire après celui-ci.
   </para>

   <caution>
    <para>
     La plupart des types de dictionnaires se basent sur des fichiers de
     configuration, comme les fichiers de termes courants. Ces fichiers
     <emphasis>doivent</emphasis> être dans l'encodage UTF-8. Ils seront traduit
     vers l'encodage actuelle de la base de données, si elle est différente,
     quand ils seront lus.
    </para>
   </caution>

   <caution>
    <para>
     Habituellement, une session lira un fichier de configuration du dictionnaire
     une seule fois, lors de la première utilisation. Si vous modifiez un fichier
     de configuration et que vous voulez forcer la prise en compte des
     modifications par les sessions en cours, exécutez une commande
     <command>ALTER TEXT SEARCH DICTIONARY</command> sur le dictionnaire. Cela
     peut être une mise à jour <quote>à vide</quote>, donc sans réellement
     modifier des valeurs.
    </para>
   </caution>

  </sect2>

  <sect2 id="textsearch-synonym-dictionary">
   <title>Dictionnaire des synonymes</title>

   <para>
    Ce modèle de dictionnaire est utilisé pour créer des dictionnaires qui
    remplacent un mot par un synonyme. Les phrases ne sont pas supportées
    (utilisez le modèle thésaurus pour cela, <xref
    linkend="textsearch-thesaurus"/>).
    Un dictionnaire des synonyme peut être utilisé pour contourner des problèmes
    linguistiques, par exemple pour empêcher un dictionnaire stemmer anglais de
    réduire le mot «&nbsp;Paris&nbsp;» en 'pari'. Il suffit d'avoir une ligne
    <literal>Paris paris</literal> dans le dictionnaire des synonymes et de le
    placer avant le dictionnaire <literal>english_stem</literal>&nbsp;:

<programlisting>
SELECT * FROM ts_debug('english', 'Paris');
   alias   |   description   | token |  dictionaries  |  dictionary  | lexemes 
-----------+-----------------+-------+----------------+--------------+---------
 asciiword | Word, all ASCII | Paris | {english_stem} | english_stem | {pari}

CREATE TEXT SEARCH DICTIONARY my_synonym (
    TEMPLATE = synonym,
    SYNONYMS = my_synonyms
);

ALTER TEXT SEARCH CONFIGURATION english
    ALTER MAPPING FOR asciiword WITH my_synonym, english_stem;

SELECT * FROM ts_debug('english', 'Paris');
   alias   |   description   | token |       dictionaries        | dictionary | lexemes 
-----------+-----------------+-------+---------------------------+------------+---------
 asciiword | Word, all ASCII | Paris | {my_synonym,english_stem} | my_synonym | {paris}
</programlisting>
   </para>

   <para>
    Le seul paramètre requis par le modèle <literal>synonym</literal> est
    <literal>SYNONYMS</literal>, qui est le nom de base de son fichier de
    configuration &mdash; <literal>my_synonyms</literal> dans l'exemple ci-dessus.
    Le nom complet du fichier sera 
    <filename>$SHAREDIR/tsearch_data/my_synonyms.syn</filename>
    (où <literal>$SHAREDIR</literal> correspond au répertoire des données
    partagées de l'installation de <productname>PostgreSQL</productname>).
    Le format du fichier est une ligne par mot à substituer, avec le mot suivi
    par son synonyme séparé par un espace blanc. Les lignes vierges et les
    espaces après les mots sont ignorés, les lettres majuscules sont mises
    en minuscules.
   </para>

  </sect2>

  <sect2 id="textsearch-thesaurus">
   <title>Dictionnaire thésaurus</title>

   <para>
    Un dictionnaire thésaurus (parfois abrévié en <acronym>TZ</acronym>) est
    un ensemble de mots qui incluent des informations sur les relations des
    mots et des phrases, par exemple des termes plus lointains
    (<acronym>BT</acronym>), plus proches (<acronym>NT</acronym>), des termes
    préférés, des termes non aimés, des termes en relation, etc.
   </para>

   <para>
    De façon simple, un dictionnaire thésaurus remplace tous les termes par des
    termes préférés et, en option, conserve les termes originaux pour l'indexage.
    L'implémentation actuelle du dictionnaire thésaurus par
    <productname>PostgreSQL</productname> est une extension du dictionnaire des
    synonymes avec un support additionnel des <firstterm>phrases</firstterm>. Un
    dictionnaire thésaurus nécessite un fichier de configuration au format
    suivant&nbsp;:

<programlisting>
# ceci est un commentaire
mots(s) : mot(s) indexé(s)
d'autre(s) mot(s) : d'autre(s) mot(s) indexé(s)
...
</programlisting>

    où le deux-points (<symbol>:</symbol>) agit comme un délimiteur entre
    une phrase et son remplacement.
   </para>

   <para>
    Un dictionnaire thésaurus utilise un <firstterm>sous-dictionnaire</firstterm>
    (qui est spécifié dans la configuration du dictionnaire) pour normaliser le
    texte en entrée avant la vérification des correspondances de phrases. Un
    seul sous-dictionnaire est sélectionnable. Une erreur est renvoyée si le
    sous-dictionnaire échoue dans la reconnaissance d'un mot. Dans ce cas, vous
    devez
    supprimer l'utilisation du mot ou le faire connaître au sous-dictionnaire.
    Vous pouvez placer une astérisque (<symbol>*</symbol>) devant un mot indexé
    pour ignorer l'utilisation du sous-dictionnaire mais tous les mots
    <emphasis>doivent</emphasis> être connus du sous-dictionnaire.
   </para>

   <para>
    Le dictionnaire thésaurus choisit la plus grande correspondance s'il existe
    plusieurs phrases correspondant à l'entrée.
   </para>

   <para>
    Les mots spécifiques reconnus par le sous-dictionnaire ne peuvent pas être
    précisés&nbsp;; à la place, utilisez <literal>?</literal> pour marquer tout
    emplacement où un terme courant peut apparaître. Par exemple, en supposant
    que <literal>a</literal> et <literal>the</literal> sont des termes courants
    d'après le sous-dictionnaire&nbsp;:

<programlisting>
? one ? two : swsw
</programlisting>

    correspond à <literal>a one the two</literal> et à <literal>the one a
    two</literal>. Les deux pourraient être remplacés par
    <literal>swsw</literal>.
   </para>

   <para>
    Comme un dictionnaire thésaurus a la possibilité de reconnaître des phrases,
    il doit se rappeler son état et interagir avec l'analyseur. Un dictionnaire
    thésaurus utilise ces assignements pour vérifier s'il doit gérer le mot
    suivant ou arrêter l'accumulation. Le dictionnaire thésaurus doit être
    configuré avec attention. Par exemple, si le dictionnaire thésaurus s'occupe
    seulement du type de jeton <literal>asciiword</literal>, alors une définition
    du dictionnaire thésaurus comme <literal>one 7</literal> ne fonctionnera pas
    car le type de jeton <literal>uint</literal> n'est pas affecté au dictionnaire
    thésaurus.
   </para>

   <caution>
    <para>
     Les thésaurus sont utilisés lors des indexages pour que toute modification
     dans les paramètres du dictionnaire thésaurus <emphasis>nécessite</emphasis>
     un réindexage. Pour la plupart des autres types de dictionnaire, de petites
     modifications comme l'ajout ou la suppression de termes courants ne demandent
     pas un réindexage.
    </para>
   </caution>

  <sect3 id="textsearch-thesaurus-config">
   <title>Configuration du thésaurus</title>

   <para>
    Pour définir un nouveau dictionnaire thésaurus, utilisez le modèle
    <literal>thesaurus</literal>. Par exemple&nbsp;:

<programlisting>
CREATE TEXT SEARCH DICTIONARY thesaurus_simple (
    TEMPLATE = thesaurus,
    DictFile = mythesaurus,
    Dictionary = pg_catalog.english_stem
);
</programlisting>

    Dans ce cas&nbsp;:
    <itemizedlist  spacing="compact" mark="bullet">
     <listitem>
      <para>
       <literal>thesaurus_simple</literal> est le nom du nouveau dictionnaire
      </para>
     </listitem>
     <listitem>
      <para>
       <literal>mythesaurus</literal> est le nom de base du fichier de
       configuration du thésaurus. (Son nom complet est
       <filename>$SHAREDIR/tsearch_data/mythesaurus.ths</filename>,
       où <literal>$SHAREDIR</literal> est remplacé par le répertoire des
       données partagées de l'installation.)
      </para>
     </listitem>
     <listitem>
      <para>
       <literal>pg_catalog.english_stem</literal> est le sous-dictionnaire (ici
       un stemmer Snowball anglais) à utiliser pour la normalisation du
       thésaurus. Notez que le sous-dictionnaire aura sa propre configuration
       (par exemple, les termes courants) qui n'est pas affichée ici.
      </para>
     </listitem>
    </itemizedlist>

    Maintenant, il est possible de lier le dictionnaire du thésaurus
    <literal>thesaurus_simple</literal> aux types de jeton désirés dans une
    configuration, par exemple&nbsp;:

<programlisting>
ALTER TEXT SEARCH CONFIGURATION russian
    ALTER MAPPING FOR asciiword, asciihword, hword_asciipart WITH thesaurus_simple;
</programlisting>
   </para>

  </sect3>

  <sect3 id="textsearch-thesaurus-examples">
   <title>Exemple de thésaurus</title>

   <para>
    Considérez un thésaurus d'astronomie <literal>thesaurus_astro</literal>,
    contenant quelques combinaisons de mots d'astronomie&nbsp;:

<programlisting>
supernovae stars : sn
crab nebulae : crab
</programlisting>

    Ci-dessous, nous créons un dictionnaire et lions certains types de jeton
    à un thésaurus d'astronomie et à un stemmer anglais&nbsp;:

<programlisting>
CREATE TEXT SEARCH DICTIONARY thesaurus_astro (
    TEMPLATE = thesaurus,
    DictFile = thesaurus_astro,
    Dictionary = english_stem
);

ALTER TEXT SEARCH CONFIGURATION russian
    ALTER MAPPING FOR asciiword, asciihword, hword_asciipart WITH thesaurus_astro, english_stem;
</programlisting>

    Maintenant, nous pouvons voir comment cela fonctionne.
    <function>ts_lexize</function> n'est pas très utile pour tester un thésaurus
    car elle traite l'entrée en tant que simple jeton. À la place, nous pouvons
    utiliser <function>plainto_tsquery</function> et
    <function>to_tsvector</function> qui cassera les chaînes en entrée en
    plusieurs jetons&nbsp;:

<programlisting>
SELECT plainto_tsquery('supernova star');
 plainto_tsquery
-----------------
 'sn'

SELECT to_tsvector('supernova star');
 to_tsvector
-------------
 'sn':1
</programlisting>

    En principe, il es possible d'utiliser <function>to_tsquery</function> si
    vous placez l'argument entre guillemets&nbsp;:

<programlisting>
SELECT to_tsquery('''supernova star''');
 to_tsquery
------------
 'sn'
</programlisting>

    Notez que <literal>supernova star</literal> établit une correspondance avec
    <literal>supernovae stars</literal> dans <literal>thesaurus_astro</literal>
    car nous avions indiqué le stemmer <literal>english_stem</literal> dans la
    définition du thésaurus. Le stemmer a supprimé <literal>e</literal> et
    <literal>s</literal>.
   </para>

   <para>
    Pour indexer la phrase originale ainsi que son substitut, incluez-le dans
    la partie droite de la définition&nbsp;:

<programlisting>
supernovae stars : sn supernovae stars

SELECT plainto_tsquery('supernova star');
       plainto_tsquery
-----------------------------
 'sn' &amp; 'supernova' &amp; 'star'
</programlisting>
   </para>

  </sect3>

  </sect2>

  <sect2 id="textsearch-ispell-dictionary">
   <title>Dictionnaire <application>Ispell</application></title>

   <para>
    Le modèle de dictionnaire <application>Ispell</application> ajoute le
    support
    des <firstterm>dictionnaires morphologiques</firstterm> qui peuvent
    normaliser plusieurs formes linguisitiques différentes d'un mot en un même
    lexeme. Par exemple, un dictionnaire <application>Ispell</application>
    anglais peut établir une correspondance avec toutes les déclinaisons et
    conjugaisons du terme <literal>bank</literal>, c'est-à-dire
    <literal>banking</literal>, <literal>banked</literal>,
    <literal>banks</literal>,
    <literal>banks'</literal> et <literal>bank's</literal>.
   </para>

   <para>
    La distribution standard de <productname>PostgreSQL</productname> n'inclut
    aucun des fichiers de configuration <application>Ispell</application>. Les
    dictionnaires sont disponibles pour un grand nombre de langues à partir
    du <ulink
    url="http://ficus-www.cs.ucla.edu/geoff/ispell.html">site web Ispell</ulink>.
    De plus, certains formats de fichiers dictionnaires plus modernes sont
    supportés &mdash; <ulink
    url="http://en.wikipedia.org/wiki/MySpell">MySpell</ulink> (OO &lt; 2.0.1)
    et <ulink url="http://sourceforge.net/projects/hunspell">Hunspell</ulink>
    (OO &gt;= 2.0.2). Une large liste de dictionnaires est disponible sur le
    <ulink
    url="http://wiki.services.openoffice.org/wiki/Dictionaries">Wiki d'OpenOffice
    </ulink>.
   </para>

   <para>
    Pour créer un dictionnaire <application>Ispell</application>, utilisez le
    modèle interne <literal>Ispell</literal> et précisez plusieurs
    paramètres&nbsp;:
   </para>

<programlisting>
CREATE TEXT SEARCH DICTIONARY english_ispell (
    TEMPLATE = ispell,
    DictFile = english,
    AffFile = english,
    StopWords = english
);
</programlisting>

   <para>
    Ici, <literal>DictFile</literal>, <literal>AffFile</literal> et
    <literal>StopWords</literal> indiquent les noms de base des fichiers
    dictionnaire, affixes et termes courants. Le fichier des termes courants
    a le même format qu'indiqué ci-dessus pour le type de dictionnaire
    <literal>simple</literal>. Le format des autres fichiers n'est pas indiqué
    ici mais est disponible sur les sites web mentionnés ci-dessus.
   </para>

   <para>
    Les dictionnaires Ispell reconnaissent habituellement un ensemble limité de
    mots, pour qu'ils puissent être suivis par un dictionnaire encore plus
    généraliste&nbsp;; par exemple un dictionnaire Snowball qui reconnaît tout.
   </para>

   <para>
    Les dictionnaires Ispell supportent la séparation des mots composés. C'est
    une fonctionnaité intéressante et <productname>PostgreSQL</productname> la
    supporte. Notez que le fichier d'affixes doit indiquer une option spéciale
    qui marque les mots du dictionnaire qui peuvent participer à une formation
    composée&nbsp;:

<programlisting>
compoundwords  controlled z
</programlisting>

    Voici quelques exemples en norvégien&nbsp;:

<programlisting>
SELECT ts_lexize('norwegian_ispell', 'overbuljongterningpakkmesterassistent');
   {over,buljong,terning,pakk,mester,assistent}
SELECT ts_lexize('norwegian_ispell', 'sjokoladefabrikk');
   {sjokoladefabrikk,sjokolade,fabrikk}
</programlisting>
   </para>

   <note>
    <para>
     <application>MySpell</application> ne supporte pas les mots composés.
     <application>Hunspell</application> a un support sophistiqué des mots
     composés. Actuellement, <productname>PostgreSQL</productname> implémente
     seulement les opérations basiques de Hunspell pour les mots composés.
    </para>
   </note>

  </sect2>

  <sect2 id="textsearch-snowball-dictionary">
   <title>Dictionnaire <application>Snowball</application></title>

   <para>
    Le modèle de dictionnaire <application>Snowball</application> est basé sur
    le projet de Martin Porter, inventeur du populaire algorithme stemming de
    Porter pour l'anglais. Snowball propose maintenant des algorithmes stemming
    pour un grand nombre de langues (voir le <ulink
    url="http://snowball.tartarus.org">site Snowball</ulink> pour plus
    d'informations). Chaque algorithme sait comment réduire les variantes
    standard d'un mot vers une base, ou stem, en rapport avec la langue. Un
    dictionnaire Snowball réclame un paramètre <literal>langue</literal> pour
    identifier le stemmer à utiliser et, en option, un nom de fichier des
    <literal>termes courants</literal> donnant une liste de mots à éliminer.
    (Les listes de termes courants au standard
    <productname>PostgreSQL</productname>
    sont aussi fournies par le projet Snowball.) Par exemple, il existe un
    équivalent de la définition interne en

<programlisting>
CREATE TEXT SEARCH DICTIONARY english_stem (
    TEMPLATE = snowball,
    Language = english,
    StopWords = english
);
</programlisting>

    Le format du fichier des termes courants est identique à celui déjà expliqué.
   </para>

   <para>
    Un dictionnaire <application>Snowball</application> reconnaît tout, qu'il
    soit ou non capable de simplifier le mot, donc il doit être placé en fin de
    la liste des dictionnaires. Il est inutile de l'avoir avant tout autre
    dictionnaire car un jeton ne passera jamais au prochain dictionnaire.
   </para>

  </sect2>

 </sect1>

 <sect1 id="textsearch-configuration">
  <title>Exemple de configuration</title>

   <para>
    Une configuration de recherche plein texte précise toutes les options
    nécessaires pour transformer un document en un <type>tsvector</type>&nbsp;:
    le planificateur à utiliser pour diviser le texte en jetons, et les
    dictionnaires à utiliser pour transformer chaque jeton en un lexeme.
    Chaque appel à <function>to_tsvector</function> ou <function>to_tsquery</function>
    a besoin d'une configuration de recherche plein texte pour réaliser le
    traitement. Le paramètre de configuration
    <xref linkend="guc-default-text-search-config"/> indique le nom de la
    configuration par défaut, celle utilisée par les fonctions de recherche
    plein texte si un paramètre explicite de configuration est oublié.
    Il se configure soit dans <filename>postgresql.conf</filename> soit dans
    une session individuelle en utilisant la commande <command>SET</command>.
   </para>

   <para>
    Plusieurs configurations de recherche plein texte prédéfinies sont
    disponibles et vous pouvez créer des versions personnalisées facilement.
    Pour faciliter la gestion des objets de recherche plein texte, un ensemble
    de commandes <acronym>SQL</acronym> est disponible, et il existe plusieurs
    commandes <application>psql</application> affichant des informations sur
	les objets de la recherche plein texte (<xref linkend="textsearch-psql"/>).
   </para>

   <para>
    Comme exemple, nous allons créer une configuration <literal>pg</literal>
    en commençant à partir d'une duplication de la configuration
    <literal>english</literal>.

<programlisting>
CREATE TEXT SEARCH CONFIGURATION public.pg ( COPY = pg_catalog.english );
</programlisting>
   </para>

   <para>
    Nous allons utiliser une liste de synonymes spécifique à PostgreSQL et nous
    allons la stocker dans <filename>$SHAREDIR/tsearch_data/pg_dict.syn</filename>.
    Le contenu du fichier ressemble à ceci&nbsp;:

<programlisting>
postgres    pg
pgsql       pg
postgresql  pg
</programlisting>

    Nous définissons le dictionnaire des synonymes ainsi&nbsp;:

<programlisting>
CREATE TEXT SEARCH DICTIONARY pg_dict (
    TEMPLATE = synonym,
    SYNONYMS = pg_dict
);
</programlisting>

    Ensuite, nous enregistrons le dictionnaire <productname>Ispell</productname>
    <literal>english_ispell</literal> qui a ses propres fichiers de
    configuration&nbsp;:

<programlisting>
CREATE TEXT SEARCH DICTIONARY english_ispell (
    TEMPLATE = ispell,
    DictFile = english,
    AffFile = english,
    StopWords = english
);
</programlisting>

    Maintenant, nous configurons la correspondance des mots dans la
    configuration <literal>pg</literal>&nbsp;:

<programlisting>
ALTER TEXT SEARCH CONFIGURATION pg
    ALTER MAPPING FOR asciiword, asciihword, hword_asciipart,
                      word, hword, hword_part
    WITH pg_dict, english_ispell, english_stem;
</programlisting>

    Nous choisissons de ne pas indexer certains types de jeton que la
    configuration par défaut peut gérer&nbsp;:

<programlisting>
ALTER TEXT SEARCH CONFIGURATION pg
    DROP MAPPING FOR email, url, url_path, sfloat, float;
</programlisting>
   </para>

   <para>
    Maintenant, nous pouvons tester notre configuration&nbsp;:

<programlisting>
SELECT * FROM ts_debug('public.pg', '
PostgreSQL, the highly scalable, SQL compliant, open source object-relational
database management system, is now undergoing beta testing of the next
version of our software.
');
</programlisting>
   </para>

   <para>
    La prochaine étape est d'initialiser la session pour utiliser la
    nouvelle configuration qui était créée dans le schéma
    <literal>public</literal>&nbsp;:

<programlisting>
=&gt; \dF
   List of text search configurations
 Schema  | Name | Description
---------+------+-------------
 public  | pg   |

SET default_text_search_config = 'public.pg';
SET

SHOW default_text_search_config;
 default_text_search_config
----------------------------
 public.pg
</programlisting>
  </para>

 </sect1>

 <sect1 id="textsearch-debugging">
  <title>Tester et déboguer la recherche plein texte</title>

  <para>
   Le comportement d'une configuration personnalisée de recherche plein texte
   peut facilement devenir suffisamment compliqué pour être confuse ou
   indésirable. Les fonctions décrites dans cette section sont utiles pour
   tester les objets de recherche plein texte. Vous pouvez tester une
   configuration complète ou tester séparément analyseurs et dictionnaires.
  </para>

  <sect2 id="textsearch-configuration-testing">
   <title>Test d'une configuration</title>

  <para>
   La fonction <function>ts_debug</function> permet un test facile d'une
   configuration de recherche plein texte.
  </para>

  <indexterm>
   <primary>ts_debug</primary>
  </indexterm>

  <synopsis>
   ts_debug(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type>, </optional> <replaceable class="parameter">document</replaceable> <type>text</type>,
            OUT <replaceable class="parameter">alias</replaceable> <type>text</type>,
            OUT <replaceable class="parameter">description</replaceable> <type>text</type>,
            OUT <replaceable class="parameter">token</replaceable> <type>text</type>,
            OUT <replaceable class="parameter">dictionaries</replaceable> <type>regdictionary[]</type>,
            OUT <replaceable class="parameter">dictionary</replaceable> <type>regdictionary</type>,
            OUT <replaceable class="parameter">lexemes</replaceable> <type>text[]</type>)
            returns setof record
  </synopsis>

  <para>
   <function>ts_debug</function> affiche des informations sur chaque jeton d'un
   <replaceable class="parameter">document</replaceable> tel qu'il est produit
   par l'analyseur et traité par les dictionnaires configurés. Elle utilise la
   configuration indiquée par <replaceable class="parameter">config</replaceable>,
   ou <varname>default_text_search_config</varname> si cet argument est omis.
  </para>

  <para>
   <function>ts_debug</function> renvoie une ligne pour chaque jeton identifié
   dans le texte par l'analyseur. Les colonnes renvoyées sont&nbsp;:

    <itemizedlist  spacing="compact" mark="bullet">
     <listitem>
      <para>
       <replaceable>alias</replaceable> <type>text</type> &mdash; nom court
       du type de jeton
      </para>
     </listitem>
     <listitem>
      <para>
       <replaceable>description</replaceable> <type>text</type> &mdash;
       description du type de jeton
      </para>
     </listitem>
     <listitem>
      <para>
       <replaceable>token</replaceable> <type>text</type> &mdash; texte du jeton
      </para>
     </listitem>
     <listitem>
      <para>
       <replaceable>dictionaries</replaceable> <type>regdictionary[]</type> &mdash;
       les dictionnaires sélectionnés par la configuration pour ce type de jeton
      </para>
     </listitem>
     <listitem>
      <para>
       <replaceable>dictionary</replaceable> <type>regdictionary</type> &mdash;
       le dictionnaire qui a reconnu le jeton, ou <literal>NULL</literal> dans
       le cas contraire
      </para>
     </listitem>
     <listitem>
      <para>
       <replaceable>lexemes</replaceable> <type>text[]</type> &mdash; le ou les
       lexemes produit par le dictionnaire qui a reconnu le jeton, ou
       <literal>NULL</literal> dans le cas contraire&nbsp;; un tableau vide
       (<literal>{}</literal>) signifie qu'il a été reconnu comme un terme
       courant
      </para>
     </listitem>
    </itemizedlist>
  </para>

  <para>
   Voici un exemple simple&nbsp;:

<programlisting>
SELECT * FROM ts_debug('english','a fat  cat sat on a mat - it ate a fat rats');
   alias   |   description   | token |  dictionaries  |  dictionary  | lexemes 
-----------+-----------------+-------+----------------+--------------+---------
 asciiword | Word, all ASCII | a     | {english_stem} | english_stem | {}
 blank     | Space symbols   |       | {}             |              | 
 asciiword | Word, all ASCII | fat   | {english_stem} | english_stem | {fat}
 blank     | Space symbols   |       | {}             |              | 
 asciiword | Word, all ASCII | cat   | {english_stem} | english_stem | {cat}
 blank     | Space symbols   |       | {}             |              | 
 asciiword | Word, all ASCII | sat   | {english_stem} | english_stem | {sat}
 blank     | Space symbols   |       | {}             |              | 
 asciiword | Word, all ASCII | on    | {english_stem} | english_stem | {}
 blank     | Space symbols   |       | {}             |              | 
 asciiword | Word, all ASCII | a     | {english_stem} | english_stem | {}
 blank     | Space symbols   |       | {}             |              | 
 asciiword | Word, all ASCII | mat   | {english_stem} | english_stem | {mat}
 blank     | Space symbols   |       | {}             |              | 
 blank     | Space symbols   | -     | {}             |              | 
 asciiword | Word, all ASCII | it    | {english_stem} | english_stem | {}
 blank     | Space symbols   |       | {}             |              | 
 asciiword | Word, all ASCII | ate   | {english_stem} | english_stem | {ate}
 blank     | Space symbols   |       | {}             |              | 
 asciiword | Word, all ASCII | a     | {english_stem} | english_stem | {}
 blank     | Space symbols   |       | {}             |              | 
 asciiword | Word, all ASCII | fat   | {english_stem} | english_stem | {fat}
 blank     | Space symbols   |       | {}             |              | 
 asciiword | Word, all ASCII | rats  | {english_stem} | english_stem | {rat}
</programlisting>
  </para>

  <para>
   Pour une démonstration plus importante, nous créons tout d'abord une
   configuration <literal>public.english</literal> et un dictionnaire
   ispell pour l'anglais&nbsp;:
  </para>

<programlisting>
CREATE TEXT SEARCH CONFIGURATION public.english ( COPY = pg_catalog.english );

CREATE TEXT SEARCH DICTIONARY english_ispell (
    TEMPLATE = ispell,
    DictFile = english,
    AffFile = english,
    StopWords = english
);

ALTER TEXT SEARCH CONFIGURATION public.english
   ALTER MAPPING FOR asciiword WITH english_ispell, english_stem;
</programlisting>

<programlisting>
SELECT * FROM ts_debug('public.english','The Brightest supernovaes');
   alias   |   description   |    token    |         dictionaries          |   dictionary   |   lexemes   
-----------+-----------------+-------------+-------------------------------+----------------+-------------
 asciiword | Word, all ASCII | The         | {english_ispell,english_stem} | english_ispell | {}
 blank     | Space symbols   |             | {}                            |                | 
 asciiword | Word, all ASCII | Brightest   | {english_ispell,english_stem} | english_ispell | {bright}
 blank     | Space symbols   |             | {}                            |                | 
 asciiword | Word, all ASCII | supernovaes | {english_ispell,english_stem} | english_stem   | {supernova}
</programlisting>

  <para>
   Dans cet exemple, le mot <literal>Brightest</literal> a été reconnu par
   l'analyseur comme un <literal>mot ASCII</literal> (alias
   <literal>asciiword</literal>). Pour ce type de jeton, la liste de dictionnaire
   est <literal>english_ispell</literal> et <literal>english_stem</literal>. Le
   mot a été reconnu par <literal>english_ispell</literal>, qui l'a réduit avec
   le mot <literal>bright</literal>. Le mot <literal>supernovaes</literal> est
   inconnu dans le dictionnaire <literal>english_ispell</literal> donc il
   est passé au dictionnaire suivant et, heureusement, est reconnu (en fait,
   <literal>english_stem</literal> est un dictionnaire Snowball qui reconnaît
   tout&nbsp;; c'est pourquoi il est placé en dernier dans la liste des
   dictionnaires).
  </para>

  <para>
   Le mot <literal>The</literal> est reconnu par le dictionnaire
   <literal>english_ispell</literal> comme étant un terme courant (<xref
   linkend="textsearch-stopwords"/>) et n'est donc pas indexé. Les espaces
   sont aussi ignorés car la configuration ne fournit aucun dictionnaire
   pour eux.
  </para>

  <para>
   Vous pouvez réduire le volume en sortie en spécifiant explicitement les
   colonnes que vous voulez voir&nbsp;:

<programlisting>
SELECT alias, token, dictionary, lexemes
FROM ts_debug('public.english','The Brightest supernovaes');
   alias   |    token    |   dictionary   |   lexemes   
-----------+-------------+----------------+-------------
 asciiword | The         | english_ispell | {}
 blank     |             |                | 
 asciiword | Brightest   | english_ispell | {bright}
 blank     |             |                | 
 asciiword | supernovaes | english_stem   | {supernova}
</programlisting>
  </para>

  </sect2>

  <sect2 id="textsearch-parser-testing">
   <title>Test de l'analyseur</title>

  <para>
   Les fonctions suivantes permettent un test direct d'un analyseur de recherche
   plein texte.
  </para>

  <indexterm>
   <primary>ts_parse</primary>
  </indexterm>

  <synopsis>
   ts_parse(<replaceable class="parameter">parser_name</replaceable> <type>text</type>, <replaceable class="parameter">document</replaceable> <type>text</type>, OUT <replaceable class="parameter">tokid</replaceable> <type>integer</type>, OUT <replaceable class="parameter">token</replaceable> <type>text</type>) returns <type>setof record</type>
   ts_parse(<replaceable class="parameter">parser_oid</replaceable> <type>oid</type>, <replaceable class="parameter">document</replaceable> <type>text</type>, OUT <replaceable class="parameter">tokid</replaceable> <type>integer</type>, OUT <replaceable class="parameter">token</replaceable> <type>text</type>) returns <type>setof record</type>
  </synopsis>

  <para>
   <function>ts_parse</function> analyse le <replaceable>document</replaceable>
   indiqué et renvoie une série d'enregistrements, un pour chaque jeton produit
   par l'analyse. Chaque enregistrement inclut un <varname>tokid</varname>
   montrant le type de jeton affecté et un jeton (<varname>token</varname>) qui
   est le texte dudit jeton. Par exemple&nbsp;:

<programlisting>
SELECT * FROM ts_parse('default', '123 - a number');
 tokid | token
-------+--------
    22 | 123
    12 |
    12 | -
     1 | a
    12 |
     1 | number
</programlisting>
  </para>

  <indexterm>
   <primary>ts_token_type</primary>
  </indexterm>

  <synopsis>
   ts_token_type(<replaceable class="parameter">parser_name</replaceable> <type>text</type>, OUT <replaceable class="parameter">tokid</replaceable> <type>integer</type>, OUT <replaceable class="parameter">alias</replaceable> <type>text</type>, OUT <replaceable class="parameter">description</replaceable> <type>text</type>) returns <type>setof record</type>
   ts_token_type(<replaceable class="parameter">parser_oid</replaceable> <type>oid</type>, OUT <replaceable class="parameter">tokid</replaceable> <type>integer</type>, OUT <replaceable class="parameter">alias</replaceable> <type>text</type>, OUT <replaceable class="parameter">description</replaceable> <type>text</type>) returns <type>setof record</type>
  </synopsis>

  <para>
   <function>ts_token_type</function> renvoie une table qui décrit chaque type
   de jeton que l'analyseur indiqué peut reconnaître. Pour chaque type de jeton,
   la table donne l'entier <varname>tokid</varname> que l'analyseur utilise pour
   labeliser un jeton de ce type, l'<varname>alias</varname> qui nomme le type
   de jeton dans les commandes de configuration et une courte
   <varname>description</varname>. Par exemple&nbsp;:

<programlisting>
SELECT * FROM ts_token_type('default');
 tokid |      alias      |               description                
-------+-----------------+------------------------------------------
     1 | asciiword       | Word, all ASCII
     2 | word            | Word, all letters
     3 | numword         | Word, letters and digits
     4 | email           | Email address
     5 | url             | URL
     6 | host            | Host
     7 | sfloat          | Scientific notation
     8 | version         | Version number
     9 | hword_numpart   | Hyphenated word part, letters and digits
    10 | hword_part      | Hyphenated word part, all letters
    11 | hword_asciipart | Hyphenated word part, all ASCII
    12 | blank           | Space symbols
    13 | tag             | XML tag
    14 | protocol        | Protocol head
    15 | numhword        | Hyphenated word, letters and digits
    16 | asciihword      | Hyphenated word, all ASCII
    17 | hword           | Hyphenated word, all letters
    18 | url_path        | URL path
    19 | file            | File or path name
    20 | float           | Decimal notation
    21 | int             | Signed integer
    22 | uint            | Unsigned integer
    23 | entity          | XML entity
</programlisting>
   </para>

  </sect2>

  <sect2 id="textsearch-dictionary-testing">
   <title>Test des dictionnaires</title>

   <para>
    La fonction <function>ts_lexize</function> facilite le test des
    dictionnaires.
   </para>

   <indexterm>
    <primary>ts_lexize</primary>
   </indexterm>

   <synopsis>
    ts_lexize(<replaceable class="parameter">dict</replaceable> <type>regdictionary</type>, <replaceable class="parameter">token</replaceable> <type>text</type>) returns <type>text[]</type>
   </synopsis>

   <para>
    <function>ts_lexize</function> renvoie un tableau de lexemes si le jeton
    (<replaceable>token</replaceable>) en entrée est connu du dictionnaire ou
    un tableau vide si le jeton est connu du dictionnaire en tant que terme
    courant, ou enfin <literal>NULL</literal> si le mot n'est pas connu.
   </para>

   <para>
    Exemples&nbsp;:

<programlisting>
SELECT ts_lexize('english_stem', 'stars');
 ts_lexize
-----------
 {star}

SELECT ts_lexize('english_stem', 'a');
 ts_lexize
-----------
 {}
</programlisting>
   </para>

   <note>
    <para>
     La fonction <function>ts_lexize</function> attend un seul jeton, pas du
     texte. Voici un cas où cela peut devenir source de confusion&nbsp;:

<programlisting>
SELECT ts_lexize('thesaurus_astro','supernovae stars') is null;
 ?column?
----------
 t
</programlisting>

     Le dictionnaire thésaurus <literal>thesaurus_astro</literal> connaît la
     phrase <literal>supernovae stars</literal> mais
     <function>ts_lexize</function> échoue car il ne peut pas analyser le texte
     en entrée mais le traite bien en tant
     que simple jeton. Utilisez <function>plainto_tsquery</function> ou
     <function>to_tsvector</function> pour tester les dictionnaires thésaurus.
     Par exemple&nbsp;:

<programlisting>
SELECT plainto_tsquery('supernovae stars');
 plainto_tsquery
-----------------
 'sn'
</programlisting>
    </para>
   </note>

  </sect2>

 </sect1>

 <sect1 id="textsearch-indexes">
  <title>Types d'index GiST et GIN</title>

  <indexterm zone="textsearch-indexes">
   <primary>recherche plein texte</primary>
   <secondary>index</secondary>
  </indexterm>

  <para>
   Il existe deux types d'index qui peuvent être utilisés pour accélérer les
   recherches plein texte. Notez que les index ne sont pas obligatoires pour
   la recherche plein texte mais, dans les cas où une colonne est utilisée
   fréquemment dans une recherche, un index sera suffisamment intéressant.

   <variablelist>

    <varlistentry>
     <term>
      <indexterm zone="textsearch-indexes">
       <primary>index</primary>
       <secondary>GiST</secondary>
       <tertiary>recherche plein texte</tertiary>
      </indexterm>
          
      <synopsis>
       CREATE INDEX <replaceable>nom</replaceable> ON <replaceable>table</replaceable> USING gist(<replaceable>colonne</replaceable>);
      </synopsis>
     </term>

     <listitem>
      <para>
       Crée un index GiST (Generalized Search Tree).
       La <replaceable>colonne</replaceable> peut être de type
       <type>tsvector</type> ou <type>tsquery</type>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>

     <term>

      <indexterm zone="textsearch-indexes">
       <primary>index</primary>
       <secondary>GIN</secondary>
       <tertiary>recherche plein texte</tertiary>
      </indexterm>

      <synopsis>
       CREATE INDEX <replaceable>nom</replaceable> ON <replaceable>table</replaceable> USING gin(<replaceable>colonne</replaceable>);
      </synopsis>
     </term>

     <listitem>
      <para>
       Crée un index GIN (Generalized Inverted Index).
       La <replaceable>colonne</replaceable> doit être de type
       <type>tsvector</type>.
      </para>
     </listitem>
    </varlistentry>

   </variablelist>
  </para>

  <para>
   Il y a des différences de performances substantielles entre les deux types
   d'index, donc il est important de comprendre lequel utiliser.
  </para>

  <para>
   Un index GiST est <firstterm>à perte</firstterm>, signifiant que l'index
   peut produire des faux positifs, et il est nécessaire de vérifier la
   ligne de la table pour les éliminer.
   <productname>PostgreSQL</productname> le fait automatiquement&nbsp;; par
   exemple, dans le plan de requête ci-dessous, la ligne
   <literal>Filter:</literal> indique que la sortie de l'index est de nouveau
   vérifiée&nbsp;:

<programlisting>
EXPLAIN SELECT * FROM apod WHERE textsearch @@ to_tsquery('supernovae');
                               QUERY PLAN
-------------------------------------------------------------------------
 Index Scan using textsearch_gidx on apod  (cost=0.00..12.29 rows=2 width=1469)
   Index Cond: (textsearch @@ '''supernova'''::tsquery)
   Filter: (textsearch @@ '''supernova'''::tsquery)
</programlisting>

   Les index GiST sont à perte car chaque document est représenté dans l'index
   par une signature à longueur fixe. La signature est générée par le hachage de
   chaque mot en un bit aléatoire dans une chaîne à n bit, tous ces bits étant
   assemblés dans une opération OR qui produit une signature du document sur n
   bits. Quand deux hachages de mots sont identiques, nous avons un faux
   positif. Si tous les mots de la requête ont une correspondance (vraie ou
   fausse), alors la ligne de la table doit être récupérée pour voir si la
   correspondance est correcte.
  </para>

  <para>
   La perte implique une dégradation des performances à cause de
   récupérations inutiles d'enregistrements de la table qui s'avèrent être de
   fausses correspondances. Comme les accès aléatoire aux enregistrements de
   la table sont lents, ceci limite l'utilité des index GiST. La probabilité de
   faux positifs dépends de plusieurs facteurs, en particulier le nombre de
   mots uniques, donc l'utilisation de dictionnaires qui réduisent ce nombre
   est recommandée.
  </para>

  <para>
   Les index GIN ne sont pas à perte mais leur performance dépendent
   logarithmiquement du nombre de mots uniques.
  </para>

  <para>
   En fait, les index GIN stockent seulement les mots (lexemes) des
   valeurs <type>tsvector</type>, et non pas leur poids. Du coup, alors qu'un
   index GIN peut être considéré sans perte pour une requête qui ne précise pas
   de poids, il l'est pour les autres. Une deuxième vérification d'une
   ligne de table est nécessaire lors de l'utilisation d'une requête impliquant
   des poids. Malheureusement, dans la conception actuelle de
   <productname>PostgreSQL</productname>, savoir si une nouvelle vérification
   est nécessaire est une propriété statique d'un opérateur particulier et n'est
   pas quelque chose qui peut être activé ou désactivé en ligne suivant les
   valeurs données à l'opérateur. Pour gérer cette situation sans imposer une
   surcharge dûe aux vérifications sur des requêtes qui n'en ont pas besoin,
   l'approche suivant a été adoptée&nbsp;:
  </para>

  <itemizedlist  spacing="compact" mark="bullet">
   <listitem>
    <para>
     L'opérateur standard de correspondance de texte <literal>@@</literal> est
     marqué comme sans perte pour les index GIN.
    </para>
   </listitem>

   <listitem>
    <para>
     Un opérateur de correspondance supplémentaire, <literal>@@@</literal>,
     est fourni et marqué comme à perte pour les index GIN. Sinon, cet
     opérateur se comporte exactement comme <literal>@@</literal>.
    </para>
   </listitem>

   <listitem>
    <para>
     Quand une recherche par index GIN est lancée avec l'opérateur
     <literal>@@</literal>, le code de support d'index va renvoyer une erreur
     si la requête spécifie un poids. Ceci protège contre les mauvaises réponses
     dûes à un échec de la vérification des poids.
    </para>
   </listitem>
  </itemizedlist>

  <para>
   En bref, vous devez utiliser <literal>@@@</literal> plutôt que
   <literal>@@</literal> pour traiter les recherches par index GIN sur des
   requêtes qui impliquent des restrictions de poids. Pour les requêtes
   qui n'ont pas ces restrictions, les deux opérateurs fonctionneront mais
   <literal>@@</literal> sera plus rapide. Cette bizarreté sera certainement
   corrigée dans une prochaine version de
   <productname>PostgreSQL</productname>.
  </para>

  <para>
   Dans le choix du type d'index à utiliser, GiST ou GIN, pensez à ces
   différences de performances&nbsp;:

   <itemizedlist  spacing="compact" mark="bullet">
    <listitem>
     <para>
      Les recherches par index GIN sont environ trois fois plus rapides que
      celles par index GiST.
     </para>
    </listitem>
    <listitem>
     <para>
      Les index GIN prennent trois fois plus de temps à se contruire que les
      index GiST.
     </para>
    </listitem>
    <listitem>
     <para>
      Les index GIN sont environ dix fois plus lents à mettre à jour que les
      index GiST.
     </para>
    </listitem>
    <listitem>
     <para>
      Les index GIN sont entre deux et trois fois plus gros que les index GiST.
     </para>
    </listitem>
   </itemizedlist>
  </para>

  <para>
   En règle générale, les index <acronym>GIN</acronym> sont meilleurs pour des
   données statiques car les recherches sont plus rapides. Pour des données
   dynamiques, les index GiST sont plus rapides à mettre à jour. Autrement dit,
   les index <acronym>GiST</acronym> sont très bons pour les données dynamiques
   et rapides si le nombre de mots uniques (lexemes) est inférieur à 100000
   alors que les index <acronym>GIN</acronym> gèreront plus de 100000 lexemes
   plus facilement mais sont plus lents à mettre à jour.
  </para>

  <para>
   Notez que le temps de construction de l'index <acronym>GIN</acronym> peut
   souvent être amélioré en augmentant <xref
   linkend="guc-maintenance-work-mem"/> alors qu'un index
   <acronym>GiST</acronym> n'est pas sensible à ce paramètre.
  </para>

  <para>
   Le partitionnement de gros ensembles et l'utilisation intelligente des index
   GIN et GiST autorise l'implémentation de recherches très rapides avec une
   mise à jour en ligne. Le partitionnement peut se faire au niveau de la base
   en utilisant l'héritage et <varname>constraint_exclusion</varname>, ou
   en distribuant les documents sur des serveurs et en récupérant les résultats
   de la recherche en utilisant le module <filename>contrib/dblink</filename>.
   Ce dernier est possible car les fonctions de score utilisent les
   informations locales.
  </para>

 </sect1>

 <sect1 id="textsearch-psql">
  <title>Support de <application>psql</application></title>

  <para>
   Des informations sur les objets de configuration de la recherche plein
   texte peuvent être obtenues dans <application>psql</application> en utilisant
   l'ensemble de commandes&nbsp;:
   <synopsis>
   \dF{d,p,t}<optional>+</optional> <optional>MODÈLE</optional>
   </synopsis>
   Un <literal>+</literal> supplémentaire affiche plus de détails.
  </para>

  <para>
   Le paramètre <literal>MODÈLE</literal> doit être le nom d'un objet de la
   recherche plein texte, pouvant être qualifié du nom du schéma. Si
   <literal>MODÈLE</literal> est omis, alors l'information sur tous les
   objets visibles est affichée. <literal>MODÈLE</literal> peut être une
   expression rationnelle et peut fournir des modèles
   <emphasis>séparés</emphasis> pour les noms du schéma et de l'objet. Les
   exemples suivants illustrent ceci&nbsp;:

<programlisting>
=&gt; \dF *fulltext*
       List of text search configurations
 Schema |  Name        | Description
--------+--------------+-------------
 public | fulltext_cfg |
</programlisting>

<programlisting>
=&gt; \dF *.fulltext*
       List of text search configurations
 Schema   |  Name        | Description
----------+----------------------------
 fulltext | fulltext_cfg |
 public   | fulltext_cfg |
</programlisting>

   Les commandes suivantes sont&nbsp;:
  </para>

  <variablelist>

   <varlistentry>
    <term><synopsis>\dF<optional>+</optional> <optional>MODÈLE</optional></synopsis></term>

    <listitem>
     <para>
      Liste les configurations de recherche plein texte (ajouter
      <literal>+</literal> pour plus de détails).
     </para>

     <para>

<programlisting>
=&gt; \dF russian
            List of text search configurations
   Schema   |  Name   |            Description             
------------+---------+------------------------------------
 pg_catalog | russian | configuration for russian language

=&gt; \dF+ russian
Text search configuration "pg_catalog.russian"
Parser: "pg_catalog.default"
      Token      | Dictionaries 
-----------------+--------------
 asciihword      | english_stem
 asciiword       | english_stem
 email           | simple
 file            | simple
 float           | simple
 host            | simple
 hword           | russian_stem
 hword_asciipart | english_stem
 hword_numpart   | simple
 hword_part      | russian_stem
 int             | simple
 numhword        | simple
 numword         | simple
 sfloat          | simple
 uint            | simple
 url             | simple
 url_path        | simple
 version         | simple
 word            | russian_stem
</programlisting>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><synopsis>\dFd<optional>+</optional> <optional>MODÈLE</optional></synopsis></term>
    <listitem>
     <para>
      Liste les dictionnaires de recherche plein texte (ajouter
      <literal>+</literal> pour plus de détails).
     </para>

     <para>
<programlisting>
=&gt; \dFd
                            List of text search dictionaries
   Schema   |      Name       |                        Description                        
------------+-----------------+-----------------------------------------------------------
 pg_catalog | danish_stem     | snowball stemmer for danish language
 pg_catalog | dutch_stem      | snowball stemmer for dutch language
 pg_catalog | english_stem    | snowball stemmer for english language
 pg_catalog | finnish_stem    | snowball stemmer for finnish language
 pg_catalog | french_stem     | snowball stemmer for french language
 pg_catalog | german_stem     | snowball stemmer for german language
 pg_catalog | hungarian_stem  | snowball stemmer for hungarian language
 pg_catalog | italian_stem    | snowball stemmer for italian language
 pg_catalog | norwegian_stem  | snowball stemmer for norwegian language
 pg_catalog | portuguese_stem | snowball stemmer for portuguese language
 pg_catalog | romanian_stem   | snowball stemmer for romanian language
 pg_catalog | russian_stem    | snowball stemmer for russian language
 pg_catalog | simple          | simple dictionary: just lower case and check for stopword
 pg_catalog | spanish_stem    | snowball stemmer for spanish language
 pg_catalog | swedish_stem    | snowball stemmer for swedish language
 pg_catalog | turkish_stem    | snowball stemmer for turkish language
</programlisting>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>

   <term><synopsis>\dFp<optional>+</optional> <optional>MODÈLE</optional></synopsis></term>
    <listitem>
     <para>
      Liste les analyseurs de recherche plein texte (ajouter
      <literal>+</literal> pour plus de détails).
     </para>

     <para>
<programlisting>
=&gt; \dFp
        List of text search parsers
   Schema   |  Name   |     Description     
------------+---------+---------------------
 pg_catalog | default | default word parser
=&gt; \dFp+
    Text search parser "pg_catalog.default"
     Method      |    Function    | Description 
-----------------+----------------+-------------
 Start parse     | prsd_start     | 
 Get next token  | prsd_nexttoken | 
 End parse       | prsd_end       | 
 Get headline    | prsd_headline  | 
 Get token types | prsd_lextype   | 

        Token types for parser "pg_catalog.default"
   Token name    |               Description                
-----------------+------------------------------------------
 asciihword      | Hyphenated word, all ASCII
 asciiword       | Word, all ASCII
 blank           | Space symbols
 email           | Email address
 entity          | XML entity
 file            | File or path name
 float           | Decimal notation
 host            | Host
 hword           | Hyphenated word, all letters
 hword_asciipart | Hyphenated word part, all ASCII
 hword_numpart   | Hyphenated word part, letters and digits
 hword_part      | Hyphenated word part, all letters
 int             | Signed integer
 numhword        | Hyphenated word, letters and digits
 numword         | Word, letters and digits
 protocol        | Protocol head
 sfloat          | Scientific notation
 tag             | HTML tag
 uint            | Unsigned integer
 url             | URL
 url_path        | URL path
 version         | Version number
 word            | Word, all letters
(23 rows)
</programlisting>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>

   <term><synopsis>\dFt<optional>+</optional> <optional>MODÈLE</optional></synopsis></term>
    <listitem>
     <para>
      Liste les modèles de recherche plein texte (ajouter
      <literal>+</literal> pour plus de détails).
     </para>

     <para>
<programlisting>
=&gt; \dFt
                           List of text search templates
   Schema   |   Name    |                        Description                        
------------+-----------+-----------------------------------------------------------
 pg_catalog | ispell    | ispell dictionary
 pg_catalog | simple    | simple dictionary: just lower case and check for stopword
 pg_catalog | snowball  | snowball stemmer
 pg_catalog | synonym   | synonym dictionary: replace word by its synonym
 pg_catalog | thesaurus | thesaurus dictionary: phrase by phrase substitution
</programlisting>
     </para>
    </listitem>
   </varlistentry>

  </variablelist>

 </sect1>

 <sect1 id="textsearch-limitations">
  <title>Limites</title>

  <para>
   Les limites actuelles de la recherche plein texte de
   <productname>PostgreSQL</productname> sont&nbsp;:
   <itemizedlist  spacing="compact" mark="bullet">
    <listitem>
     <para>La longueur de chaque lexeme doit être inférieure à 2&nbsp;Ko</para>
    </listitem>
    <listitem>
     <para>La longueur d'un <type>tsvector</type> (lexemes + positions) doit
      être inférieure à 1&nbsp;Mo</para>
    </listitem>
    <listitem>
     <!-- TODO: number of lexemes in what?  This is unclear -->
     <para>Le nombre de lexemes doit être inférieur à
     2<superscript>64</superscript></para>
    </listitem>
    <listitem>
     <para>Les valeurs de position dans un <type>tsvector</type> doivent
      être supérieures à 0 et inférieures ou égales à 16383</para>
    </listitem>
    <listitem>
     <para>Pas plus de 256 positions par lexeme</para>
    </listitem>
    <listitem>
     <para>Le nombre de n&oelig;uds (lexemes + opérateurs) dans un <type>tsquery</type>
      doit être inférieur à 32768</para>
    </listitem>
   </itemizedlist>
  </para>

  <para>
   Pour comparaison, la documentation de <productname>PostgreSQL</productname>
   8.1 contient 10441 mots uniques, un total de 335420 mots, et le mot le plus
   fréquent, <quote>postgresql</quote>, est mentionné 6127 fois dans 655
   documents.
  </para>

   <!-- TODO we need to put a date on these numbers? -->
  <para>
   Un autre exemple &mdash; les archives de la liste de discussion de
   <productname>PostgreSQL</productname> contenait 910989 mots uniques avec
   57491343 lexemes dans 461020 messages.
  </para>

 </sect1>

 <sect1 id="textsearch-migration">
  <title>Migration à partir d'une recherche plein texte antérieure à 8.3</title>

  <para>
   Les applications qui ont utilisé le module contrib
   <filename>contrib/tsearch2</filename> pour la recherche plein texte auront
   besoin de quelques ajustements pour fonctionner avec la version
   interne&nbsp;:
  </para>

  <itemizedlist>
   <listitem>
    <para>
     Certaines fonctions ont été renommées ou ont profité de petits ajustements
     dans leur listes d'arguments. Elles sont toutes dans le schéma
     <literal>pg_catalog</literal> alors que, dans une installation précédente,
     elles auraient fait partie de <literal>public</literal> ou d'un autre
     schéma utilisateur. Il existe une nouvelle version de
     <filename>contrib/tsearch2</filename> (voir la <xref linkend="tsearch2"/>)
     qui fournit une couche de compatibilité permettant de résoudre la majorité
     des problèmes connus.
    </para>
   </listitem>

   <listitem>
    <para>
     Les anciennes fonctions et les autres objets de
     <filename>contrib/tsearch2</filename> <emphasis>doivent</emphasis> être
     supprimés lors du chargement d'une sauvegarde
     <application>pg_dump</application> provenant d'une version antérieure à
     la 8.3. Bien que beaucoup des objets ne sont pas chargés de toute
     façon, certains le sont et peuvent causer des problèmes. La
     façon la plus simple de gérer ceci est de charger seulement le module
     <filename>contrib/tsearch2</filename> avant la restauration de la
     sauvegarde&nbsp;; cela bloquera la restauration des anciens objets.
    </para>
   </listitem>

   <listitem>
    <para>
     Le paramétrage de la configuration de la recherche plein texte est
     complètement différent maintenant. Au lieu d'insérer manuellement des
     lignes dans les tables de configuration, la recherche se configure avec
     des commandes SQL spécialisées indiquées dans tout ce chapitre. Il n'existe
     pas encore de support automatisé pour convertir une configuration
     personnalisée existante pour la 8.3. Vous devez vous en occuper
     manuellement.
    </para>
   </listitem>

   <listitem>
    <para>
     Le plupart des types de dictionnaires repose sur certains fichiers de
     configuration en dehors de la base de données. Ils sont largement
     compatibles pour une utilisation pre-8.3, mais notez malgré tout les
     différences qui suivent&nbsp;:

     <itemizedlist  spacing="compact" mark="bullet">
      <listitem>
       <para>
        Les fichiers de configuration doivent être placés dans le
	répertoire <filename>$SHAREDIR/tsearch_data</filename>, et
	doivent avoir une extension spécifique dépendant du type de fichier,
	comme indiqué précédemment dans les descriptions des différents types
	de dictionnaires. Cette restriction a été ajoutée pour éviter des
	problèmes de sécurité.
       </para>
      </listitem>

      <listitem>
       <para>
        Les fichiers de configuration doivent être encodés en UTF-8, quelque
	soit l'encodage utilisé par la base de données.
       </para>
      </listitem>

      <listitem>
       <para>
        Dans les fichiers de configuration du thésaurus, les termes courants
	doivent être marqués avec <literal>?</literal>.
       </para>
      </listitem>
     </itemizedlist>
    </para>
   </listitem>

  </itemizedlist>

 </sect1>

</chapter>