[Trad] [svn:pgfr] r1160 - traduc/trunk/postgresql
admin at listes.postgresql.fr
admin at listes.postgresql.fr
Mar 7 Oct 17:03:20 CEST 2008
Author: sas
Date: 2008-10-07 17:03:20 +0200 (Tue, 07 Oct 2008)
New Revision: 1160
Modified:
traduc/trunk/postgresql/indexam.xml
Log:
En cours
Modified: traduc/trunk/postgresql/indexam.xml
===================================================================
--- traduc/trunk/postgresql/indexam.xml 2008-09-30 15:37:44 UTC (rev 1159)
+++ traduc/trunk/postgresql/indexam.xml 2008-10-07 15:03:20 UTC (rev 1160)
@@ -172,7 +172,6 @@
les statistiques du nouvel index.
</para>
-<!-- SAS::ICI -->
<para>
<programlisting>bool
aminsert (Relation indexRelation,
@@ -183,17 +182,18 @@
bool check_uniqueness);
</programlisting>
Insérer une nouvelle ligne dans un index existant. Les tableaux
- <literal>values</literal> et <literal>isnull</literal> donnent les valeurs clés à indexer.
+ <literal>values</literal> et <literal>isnull</literal> donnent les valeurs
+ de clés à indexer.
<literal>heap_tid</literal> est le TID à indexer. Si la méthode d'accès supporte les
index uniques (son drapeau <structname>pg_am</structname>.<structfield>amcanunique</structfield>
- vaut true), alors <literal>check_uniqueness</literal> peut aussi valoir true,
- auquel cas la méthode d'accès doit vérifier qu'il n'y a pas de lignes en
- conflit ; c'est la seule situation dans laquelle la méthode d'accès a
- habituellement besoin du paramètre <literal>heapRelation</literal>. Voir
- <xref linkend="index-unique-checks"/> pour les détails. Le résultat vaut
- TRUE si une entrée de l'index a été insérée, FALSE sinon (un résultat FALSE
- l'indique par forcément une erreur mais est utilisé dans les cas comme un
- index AM refusant d'indexer une valeur NULL).
+ vaut true), alors <literal>check_uniqueness</literal> peut aussi valoir
+ true. Dans ce cas la méthode d'accès doit vérifier qu'il n'y a pas de ligne en
+ conflit ; c'est la seule situation où le paramètre
+ <literal>heapRelation</literal> est nécessaire dans la méthode d'accès.
+ Voir <xref linkend="index-unique-checks"/> pour les détails. Le résultat vaut
+ TRUE si une entrée de l'index a été insérée, FALSE sinon. (Un résultat FALSE
+ n'indique pas une erreur, car il est utilisé dans divers cas, dont l'index AM
+ qui refuse d'indexer une valeur NULL.)
</para>
<para>
@@ -203,28 +203,28 @@
IndexBulkDeleteCallback callback,
void *callback_state);
</programlisting>
- Supprime le(s) ligne(s) de l'index. C'est une opération de <quote>suppression
- en flot</quote> qui a pour but d'être implémentée par le parcours complet de
- l'index et par la vérification de chaque entrée pour vérifier si elle
- doit être supprimée. La fonction <literal>callback</literal> passée doit être
- appelée, dans le style <literal>callback(<replaceable>TID</replaceable>, callback_state)
- renvoie bool</literal>, pour déterminer si une entrée d'index particulière,
- identifiée par son TID référencé, est à supprimer. Doit renvoyer soit NULL
- soit une structure issue d'un palloc et contenant des statistiques sur les
+ Supprimer un(des) tuple(s) de l'index. Il s'agit d'une opération de
+ <quote>suppression massive</quote> à implanter par le parcours complet de
+ l'index et la vérification de chaque entrée pour déterminer si elle
+ doit être supprimée. La fonction <literal>callback</literal> en argument doit être
+ appelée, sous la forme <literal>callback(<replaceable>TID</replaceable>, callback_state)
+ returns bool</literal>, pour déterminer si une entrée d'index particulière,
+ identifiée par son TID, est à supprimer. Cette fonction Doit renvoyer NULL
+ ou une structure issue d'un palloc qui contient des statistiques sur les
effets de l'opération de suppression.
- Il est bien de renvoyer NULL s'il n'est pas nécessaire de renvoyer des
- informations à <function>amvacuumcleanup</function>.
+ La fonction peut retourner NULL si aucune information ne doit être envoyée à
+ <function>amvacuumcleanup</function>.
</para>
<para>
- À cause d'un <varname>maintenance_work_mem</varname> limité,
- <function>ambulkdelete</function> pourrait nécessiter d'être appelé plus
- d'une fois lorsque plusieurs lignes sont supprimées. L'argument
- <literal>stats</literal> est le résultat du dernier appel pour cet index
- (il est NULL pour le premier appel à l'intérieur d'une opération
- <command>VACUUM</command>). Ceci permet à l'AM d'accumuler les statistiques
- sur une même opération. Typiquement, <function>ambulkdelete</function>
- modifiera et renverra la même structure si le <literal>stats</literal> fourni
+ En cas de limitation de <varname>maintenance_work_mem</varname>, la
+ suppression de nombreux tuples impose d'appeler
+ <function>ambulkdelete</function> à plusieurs reprises.
+ L'argument <literal>stats</literal> est le résultat du dernier appel pour cet index
+ (il est NULL au premier appel dans une opération
+ <command>VACUUM</command>). Ceci permet à l'AM d'accumuler des statistiques
+ sur l'opération dans son intégralité. Typiquement, <function>ambulkdelete</function>
+ modifie et renvoie la même structure si le <literal>stats</literal> fourni
n'est pas NULL.
</para>
@@ -233,19 +233,20 @@
amvacuumcleanup (IndexVacuumInfo *info,
IndexBulkDeleteResult *stats);
</programlisting>
- Nettoie après une opération <command>VACUUM</command> (zéro ou plus d'appels
- à <function>ambulkdelete</function>). Ceci n'a rien à voir avec autre chose
- que le renvoi des statistiques des index, mais il peut réaliser un nettoyage
- en masse, comme réclamer les pages d'index vides. <literal>stats</literal>
- est ce que renvoie l'appel à <function>ambulkdelete</function>, ou NULL si
- <function>ambulkdelete</function> n'a pas été appelé car aucune ligne n'avait
- besoin d'être supprimée. Si le résultat n'est pas NULL, il est une structure
- allouée avec palloc. Les statistiques qu'elle contient seront utilisées pour
- mettre à jour <structname>pg_class</structname>, et seront rapportées par
- <command>VACUUM</command> si <literal>VERBOSE</literal> est indiqué. Il est
- bien de renvoyer NULL si l'index n'a pas changé du tout lors de l'opération
- de <command>VACUUM</command> mais, sinon, des statistiques correctes devront
- être renvoyées.
+ Nettoyage après une opération <command>VACUUM</command> (zéro à plusieurs
+ appels à <function>ambulkdelete</function>). La fonction n'a pas d'autre but
+ que de retourner des statistiques concernant les index, mais elle peut réaliser
+ un nettoyage en masse (réclamer les pages d'index vides, par exemple).
+ <literal>stats</literal> est le retour de l'appel à <function>ambulkdelete</function>,
+ ou NULL si
+ <function>ambulkdelete</function> n'a pas été appelée car aucune ligne n'avait
+ besoin d'être supprimée. Si le résultat n'est pas NULL, il s'agit d'une structure
+ allouée par palloc. Les statistiques qu'elle contient sont utilisées pour
+ mettre à jour <structname>pg_class</structname>, et sont rapportées par
+ <command>VACUUM</command> si <literal>VERBOSE</literal> est indiqué. La
+ fonction peut retourner NULL si l'index n'a pas été modifié lors de l'opération
+ de <command>VACUUM</command> mais, dans le cas contraire, il faut retourner
+ des statistiques correctes.
</para>
<para>
@@ -260,7 +261,7 @@
Selectivity *indexSelectivity,
double *indexCorrelation);
</programlisting>
- Estime les coûts d'un parcours d'index. Cette fonction est décrite complètement
+ Estimer les coûts d'un parcours d'index. Cette fonction est décrite complètement
dans <xref linkend="index-cost-estimation"/>, ci-dessous.
</para>
@@ -270,33 +271,35 @@
amoptions (ArrayType *reloptions,
bool validate);
</programlisting>
- Analyse et valide le tableau reloptions pour un index. C'est appelé seulement
- quand un tableau reloptions non NULL existe pour l'index.
+ Analyser et valider le tableau reloptions pour un index. Cette fonction
+ n'est appelée que lorsqu'il existe un tableau reloptions non NULL pour l'index.
<parameter>reloptions</parameter> est un tableau de type <type>text</type>
contenant des entrées de la forme
<replaceable>nom</replaceable><literal>=</literal><replaceable>valeur</replaceable>.
- La fonction devrait construire une valeur de type <type>bytea</type> qui sera
- copiée dans le champ <structfield>rd_options</structfield> de l'entrée relcache
- de l'index. Les données contenues dans la valeur <type>bytea</type> dépendent
- de la méthode d'accès mais les méthodes d'accès standards utilisent actuellement
- tous la structure <structname>StdRdOptions</structname>.
- Quand <parameter>validate</parameter> est true, la fonction devrait rapporter
- un message d'erreur convenable si aucune des option n'est pas reconnue ou a des
+ La fonction construit une valeur de type <type>bytea</type> à
+ copier dans le champ <structfield>rd_options</structfield> de l'entrée relcache
+ de l'index. Les données contenues dans la valeur <type>bytea</type> sont
+ définies par la méthode d'accès, mais les méthodes d'accès standard utilisent actuellement
+ toutes la structure <structname>StdRdOptions</structname>.
+ Lorsque <parameter>validate</parameter> est true, la fonction remonte
+ un message d'erreur clair si une option n'est pas reconnue ou a des
valeurs invalides ; quand <parameter>validate</parameter> est false, les
- entrées invalides devraient être ignorées silencieusement.
- (<parameter>validate</parameter> est faux lors du chargement des options déjà
+ entrées invalides sont ignorées silencieusement.
+ (<parameter>validate</parameter> est faux lors du chargement d'options déjà
stockées dans <structname>pg_catalog</structname> ; une entrée invalide
- pourrait seulement être trouvée si la méthode d'accès a modifié ses règles pour
+ ne peut être trouvée que si la méthode d'accès a modifié ses règles pour
les options et, dans ce cas, ignorer les entrées obsolètes est approprié.)
- Il est aussi bon de renvoyer NULL si le comportement par défaut est voulu.
+ Pour obtenir le comportement par défaut, il suffit de retourner NULL.
</para>
<para>
- Bien sûr, Le but d'un index est de supporter les parcours de lignes
- correspondant à une condition <literal>WHERE</literal> indexable, souvent appelée
- un <firstterm>qualifieur</firstterm> ou une <firstterm>clé de parcours</firstterm>. La sémantique
+ Le but d'un index est de supporter les parcours de lignes
+ qui correspondent à une condition <literal>WHERE</literal> indexable, souvent appelée
+ <firstterm>qualificateur</firstterm>
+ (<foreignphrase>qualifier</foreignphrase>) ou <firstterm>clé de
+ parcours</firstterm> (<foreignphrase>scan key</foreignphrase>). La sémantique
du parcours d'index est décrite plus complètement dans <xref linkend="index-scanning"/>,
- ci-dessous. Les fonctions relatives au parcours qu'une méthode d'accès à
+ ci-dessous. Les fonctions liées au parcours qu'une méthode d'accès à
l'index doit fournir sont :
</para>
@@ -306,13 +309,13 @@
int nkeys,
ScanKey key);
</programlisting>
- Débute un nouveau parcours. Le tableau <literal>key</literal> (de longueur
+ Débuter un nouveau parcours. Le tableau <literal>key</literal> (de longueur
<literal>nkeys</literal>) décrit les clés de parcours pour le parcours de
- l'index. Le résultat doit être une structure issue de palloc. Pour les
- raisons de l'implémentation, la méthode d'accès à l'index <emphasis>doit</emphasis>
+ l'index. Le résultat doit être une structure allouée par palloc. Pour des
+ raisons de codage, la méthode d'accès à l'index <emphasis>doit</emphasis>
créer cette structure en appelant <function>RelationGetIndexScan()</function>. Dans
- la plupart des cas, <function>ambeginscan</function> fait peu en dehors de cet
- appel ; les parties intéressantes de début du parcours d'index sont
+ la plupart des cas, <function>ambeginscan</function> se contente de réaliser
+ l'appel ; les parties intéressantes de début de parcours d'index sont
dans <function>amrescan</function>.
</para>
@@ -321,13 +324,14 @@
amgettuple (IndexScanDesc scan,
ScanDirection direction);
</programlisting>
- Récupère la prochaine ligne dans le parcours donné, se déplaçant dans bonne
- direction (en avant ou en arrière dans l'index). Renvoie TRUE si une ligne a
- été obtenue, FALSE s'il ne reste aucune ligne correspondante. Dans le cas
- TRUE, le TID de la ligne est stocké dans la structure <literal>scan</literal>. Notez
- que <quote>success</quote> signifie seulement que l'index contient une entrée
- correspondant aux clés de parcours, pas que la ligne existe toujours dans
- l'en-tête ou réussira le test de l'appelant.
+ Récupérer la prochaine ligne d'un parcours donné, dans la direction donnée
+ (vers l'avant ou l'arrière de l'index). Renvoie TRUE si une ligne a
+ été obtenue, FALSE s'il ne reste aucune ligne. Dans le cas
+ TRUE, le TID de la ligne est stocké dans la structure
+ <literal>scan</literal>. <quote>success</quote> signifie uniquement que
+ l'index contient une entrée qui correspond aux clés de parcours, pas que
+ la ligne existe toujours dans la pile ou qu'elle peut réussir le test
+ d'instantané de l'appelant.
</para>
<para>
@@ -337,18 +341,18 @@
int32 max_tids,
int32 *returned_tids);
</programlisting>
- Récupère plusieurs lignes dans le parcours donné. Renvoie TRUE si le parcours
- devait continuer, FALSE si aucune ligne correspondante ne reste.
- <literal>tids</literal> pointe vers un tableau de <literal>max_tids</literal> fourni par
- l'appelant. <structname>ItemPointerData</structname> enregistre, ce que l'appel remplit
- avec les TID des lignes correspondantes. <literal>*returned_tids</literal> est
- initialisé au nombre de TID réellement renvoyé. Ceci peut être moins que
- <literal>max_tids</literal>, voire même zéro, même si la valeur de retour vaut
- TRUE (ceci permet à la méthode d'accès de choisir les points d'arrêt les
+ Récupérer plusieurs lignes d'un parcours donné. Renvoie TRUE si le parcours
+ peut continuer, FALSE s'il ne subsiste plus aucune ligne.
+ <literal>tids</literal> pointe sur un tableau fournit par l'appelant de
+ <literal>max_tids</literal> enregistrements <structname>ItemPointerData</structname>,
+ remplit, à l'appel, des TID des lignes correspondantes. <literal>*returned_tids</literal> est
+ initialisé au nombre de TID réellement renvoyés. Il peut y en avoir moins
+ que <literal>max_tids</literal>, voire zéro, même si la valeur de retour vaut
+ TRUE. (Cette provision permet à la méthode d'accès de choisir les points d'arrêt les
plus efficaces dans son parcours, par exemple les limites de la page d'index).
<function>amgetmulti</function> et <function>amgettuple</function> ne peuvent pas être utilisés
- dans le même parcours d'index ; il y a aussi d'autres restrictions lors de
- l'utilisation de <function>amgetmulti</function>, comme expliqué dans <xref
+ dans le même parcours d'index ; l'utilisation de
+ <function>amgetmulti</function> est soumise à d'autres restrictions, comme expliqué dans <xref
linkend="index-scanning"/>.
</para>
@@ -357,24 +361,24 @@
amrescan (IndexScanDesc scan,
ScanKey key);
</programlisting>
- Recommence le parcours donné, si possible avec de nouvelles clés de parcours
- (pour continuer à utiliser les anciennes clés, NULL est passé pour
- <literal>key</literal>). Notez qu'il n'est pas possible de changer le nombre de
- clés. En pratique, la fonctionnalité de relancement est utilisée quand une
- nouvelle ligne externe est sélectionné par une jointure imbriquée en boucle
- et, du coup, la valeur de la comparaison d'une nouvelle clé est nécessaire
- mais la structure de la clé de parcours reste identique. Cette fonction est
- aussi appelée par <function>RelationGetIndexScan()</function>, donc c'est utilisé pour
- une configuration initiale d'un parcours d'index ainsi que pour parcourir de
- nouveau.
+ Recommencer le parcours donné, si possible avec de nouvelles clés de parcours
+ (pour continuer à utiliser les anciennes clés, passer NULL pour
+ <literal>key</literal>). Il n'est pas possible de changer le nombre de
+ clés. En pratique, la fonctionnalité de relance est utilisée quand une
+ nouvelle ligne externe est sélectionnée par une jointure imbriquée en
+ boucle, ce qui impose une nouvelle valeur de comparaison de clés,
+ mais la structure de la clé de parcours reste inchangée. Cette fonction est
+ aussi appelée par <function>RelationGetIndexScan()</function>. Elle est de
+ ce fait à la fois utilisée pour initialiser un parcours d'index et
+ pour le re-parcourir.
</para>
<para>
<programlisting>void
amendscan (IndexScanDesc scan);
</programlisting>
- Termine un parcours et libère les ressources. La structure <literal>scan</literal>
- elle-même ne devrait pas être libérée, mais aucun verrou pris en interne par
+ Terminer un parcours et libérer les ressources. La structure <literal>scan</literal>
+ elle-même ne doit pas être libérée, mais tout verrou pris en interne par
la méthode d'accès doit être libéré.
</para>
@@ -382,33 +386,34 @@
<programlisting>void
ammarkpos (IndexScanDesc scan);
</programlisting>
- Marque la position courante du parcours. La méthode d'accès a seulement
- besoin de supporter le rappel d'une position de parcours par parcours.
+ Marquer la position courante du parcours. La méthode d'accès ne mémorise
+ qu'une seule position par parcours.
</para>
<para>
<programlisting>void
amrestrpos (IndexScanDesc scan);
</programlisting>
- Restaure le parcours à sa plus récente position marquée.
+ Restaurer le parcours à sa plus récente position marquée.
</para>
<para>
Par convention, l'entrée <literal>pg_proc</literal> de toute fonction de
- méthode d'accès aux index devrait afficher le bon nombre d'arguments, mais
- les déclarer comme étant du type <type>internal</type> (car la plupart des
- arguments ont des types qui ne sont pas connus en SQL, et nous ne voulons
- pas que les utilisateurs appelent les fonctions directement). Le type
- renvoyé est déclaré comme <type>void</type>, <type>internal</type> ou <type>boolean</type>
+ méthode d'accès aux index affiche le bon nombre d'arguments, mais
+ les déclare tous du type <type>internal</type> (la plupart des
+ arguments ont des types qui ne sont pas connus en SQL, et il n'est pas
+ souhaitable que les utilisateurs appelent les fonctions directement). Le type
+ de retour est déclaré <type>void</type>, <type>internal</type> ou <type>boolean</type>
suivant le cas.
- La seule exception est <function>amoptions</function>, qui devrait être
- correctement déclarée comme prenant <type>text[]</type> et <type>bool</type>
- et renvoyer <type>bytea</type>. Cette provision autorise le code du client à
+ La seule exception est <function>amoptions</function>, qui doit être
+ correctement déclarée prenant <type>text[]</type> et <type>bool</type>
+ et retournant <type>bytea</type>. Cette protection autorise le code client à
exécuter <function>amoptions</function> pour tester la validité des paramètres.
</para>
</sect1>
+<!-- SAS::ICI -->
<sect1 id="index-scanning">
<title>Parcours d'index</title>
More information about the Trad
mailing list