Changeset 1160

Show
Ignore:
Timestamp:
10/07/08 17:03:20 (2 months ago)
Author:
sas
Message:

En cours

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • traduc/trunk/postgresql/indexam.xml

    r1156 r1160  
    173173  </para> 
    174174 
    175 <!-- SAS::ICI --> 
    176175  <para> 
    177176<programlisting>bool 
    …… 
    184183</programlisting> 
    185184   Insérer une nouvelle ligne dans un index existant. Les tableaux 
    186    <literal>values</literal> et <literal>isnull</literal> donnent les valeurs clés à indexer. 
     185   <literal>values</literal> et <literal>isnull</literal> donnent les valeurs 
     186   de clés à indexer. 
    187187   <literal>heap_tid</literal> est le TID à indexer. Si la méthode d'accès supporte les 
    188188   index uniques (son drapeau <structname>pg_am</structname>.<structfield>amcanunique</structfield> 
    189    vaut true), alors <literal>check_uniqueness</literal> peut aussi valoir true, 
    190    auquel cas la méthode d'accès doit vérifier qu'il n'y a pas de lignes en 
    191    conflit&nbsp;; c'est la seule situation dans laquelle la méthode d'accès a 
    192    habituellement besoin du paramètre <literal>heapRelation</literal>. Voir 
    193    <xref linkend="index-unique-checks"/> pour les détails. Le résultat vaut 
    194    TRUE si une entrée de l'index a été insérée, FALSE sinon (un résultat FALSE 
    195    l'indique par forcément une erreur mais est utilisé dans les cas comme un 
    196    index AM refusant d'indexer une valeur NULL). 
     189   vaut true), alors <literal>check_uniqueness</literal> peut aussi valoir 
     190   true. Dans ce cas la méthode d'accès doit vérifier qu'il n'y a pas de ligne en 
     191   conflit&nbsp;; c'est la seule situation où le paramètre 
     192   <literal>heapRelation</literal> est nécessaire dans la méthode d'accès. 
     193   Voir <xref linkend="index-unique-checks"/> pour les détails. Le résultat vaut 
     194   TRUE si une entrée de l'index a été insérée, FALSE sinon. (Un résultat FALSE 
     195   n'indique pas une erreur, car il est utilisé dans divers cas, dont l'index AM 
     196   qui refuse d'indexer une valeur NULL.) 
    197197  </para> 
    198198 
    …… 
    204204              void *callback_state); 
    205205</programlisting> 
    206    Supprime le(s) ligne(s) de l'index. C'est une opération de <quote>suppression 
    207    en flot</quote> qui a pour but d'être implémentée par le parcours complet de 
    208    l'index et par la vérification de chaque entrée pour vérifier si elle 
    209    doit être supprimée. La fonction <literal>callback</literal> passée doit être 
    210    appelée, dans le style <literal>callback(<replaceable>TID</replaceable>, callback_state) 
    211    renvoie bool</literal>, pour déterminer si une entrée d'index particulière, 
    212    identifiée par son TID référencé, est à supprimer. Doit renvoyer soit NULL 
    213    soit une structure issue d'un palloc et contenant des statistiques sur les 
     206   Supprimer un(des) tuple(s) de l'index. Il s'agit d'une opération de 
     207   <quote>suppression massive</quote> à implanter par le parcours complet de 
     208   l'index et la vérification de chaque entrée pour déterminer si elle 
     209   doit être supprimée. La fonction <literal>callback</literal> en argument doit être 
     210   appelée, sous la forme <literal>callback(<replaceable>TID</replaceable>, callback_state) 
     211   returns bool</literal>, pour déterminer si une entrée d'index particulière, 
     212   identifiée par son TID, est à supprimer. Cette fonction Doit renvoyer NULL 
     213   ou une structure issue d'un palloc qui contient des statistiques sur les 
    214214   effets de l'opération de suppression. 
    215    Il est bien de renvoyer NULL s'il n'est pas nécessaire de renvoyer des 
    216    informations à <function>amvacuumcleanup</function>. 
    217   </para> 
    218  
    219   <para> 
    220    À cause d'un <varname>maintenance_work_mem</varname> limité, 
    221    <function>ambulkdelete</function> pourrait nécessiter d'être appelé plus 
    222    d'une fois lorsque plusieurs lignes sont supprimées. L'argument 
    223    <literal>stats</literal> est le résultat du dernier appel pour cet index 
    224    (il est NULL pour le premier appel à l'intérieur d'une opération 
    225    <command>VACUUM</command>). Ceci permet à l'AM d'accumuler les statistiques 
    226    sur une même opération. Typiquement, <function>ambulkdelete</function> 
    227    modifiera et renverra la même structure si le <literal>stats</literal> fourni 
     215   La fonction peut retourner NULL si aucune information ne doit être envoyée à 
     216   <function>amvacuumcleanup</function>. 
     217  </para> 
     218 
     219  <para> 
     220   En cas de limitation de <varname>maintenance_work_mem</varname>, la 
     221   suppression de nombreux tuples impose d'appeler 
     222   <function>ambulkdelete</function> à plusieurs reprises. 
     223   L'argument <literal>stats</literal> est le résultat du dernier appel pour cet index 
     224   (il est NULL au premier appel dans une opération 
     225   <command>VACUUM</command>). Ceci permet à l'AM d'accumuler des statistiques 
     226   sur l'opération dans son intégralité. Typiquement, <function>ambulkdelete</function> 
     227   modifie et renvoie la même structure si le <literal>stats</literal> fourni 
    228228   n'est pas NULL. 
    229229  </para> 
    …… 
    234234                 IndexBulkDeleteResult *stats); 
    235235</programlisting> 
    236    Nettoie après une opération <command>VACUUM</command> (zéro ou plus d'appels 
    237    à <function>ambulkdelete</function>). Ceci n'a rien à voir avec autre chose 
    238    que le renvoi des statistiques des index, mais il peut réaliser un nettoyage 
    239    en masse, comme réclamer les pages d'index vides. <literal>stats</literal> 
    240    est ce que renvoie l'appel à <function>ambulkdelete</function>, ou NULL si 
    241    <function>ambulkdelete</function> n'a pas été appelé car aucune ligne n'avait 
    242    besoin d'être supprimée. Si le résultat n'est pas NULL, il est une structure 
    243    allouée avec palloc. Les statistiques qu'elle contient seront utilisées pour 
    244    mettre à jour <structname>pg_class</structname>, et seront rapportées par 
    245    <command>VACUUM</command> si <literal>VERBOSE</literal> est indiqué. Il est 
    246    bien de renvoyer NULL si l'index n'a pas changé du tout lors de l'opération 
    247    de <command>VACUUM</command> mais, sinon, des statistiques correctes devront 
    248    être renvoyées. 
     236   Nettoyage après une opération <command>VACUUM</command> (zéro à plusieurs 
     237   appels à <function>ambulkdelete</function>). La fonction n'a pas d'autre but 
     238   que de retourner des statistiques concernant les index, mais elle peut réaliser 
     239   un nettoyage en masse (réclamer les pages d'index vides, par exemple). 
     240   <literal>stats</literal> est le retour de l'appel à <function>ambulkdelete</function>, 
     241   ou NULL si 
     242   <function>ambulkdelete</function> n'a pas été appelée car aucune ligne n'avait 
     243   besoin d'être supprimée. Si le résultat n'est pas NULL, il s'agit d'une structure 
     244   allouée par palloc. Les statistiques qu'elle contient sont utilisées pour 
     245   mettre à jour <structname>pg_class</structname>, et sont rapportées par 
     246   <command>VACUUM</command> si <literal>VERBOSE</literal> est indiqué. La 
     247   fonction peut retourner NULL si l'index n'a pas été modifié lors de l'opération 
     248   de <command>VACUUM</command> mais, dans le cas contraire, il faut retourner 
     249   des statistiques correctes. 
    249250  </para> 
    250251 
    …… 
    261262                double *indexCorrelation); 
    262263</programlisting> 
    263    Estime les coûts d'un parcours d'index. Cette fonction est décrite complètement 
     264   Estimer les coûts d'un parcours d'index. Cette fonction est décrite complètement 
    264265   dans <xref linkend="index-cost-estimation"/>, ci-dessous. 
    265266  </para> 
    …… 
    271272           bool validate); 
    272273</programlisting> 
    273    Analyse et valide le tableau reloptions pour un index. C'est appelé seulement 
    274    quand un tableau reloptions non NULL existe pour l'index. 
     274   Analyser et valider le tableau reloptions pour un index. Cette fonction 
     275   n'est appelée que lorsqu'il existe un tableau reloptions non NULL pour l'index. 
    275276   <parameter>reloptions</parameter> est un tableau de type <type>text</type> 
    276277   contenant des entrées de la forme 
    277278   <replaceable>nom</replaceable><literal>=</literal><replaceable>valeur</replaceable>. 
    278    La fonction devrait construire une valeur de type <type>bytea</type> qui sera 
    279    copiée dans le champ <structfield>rd_options</structfield> de l'entrée relcache 
    280    de l'index. Les données contenues dans la valeur <type>bytea</type> dépendent 
    281    de la méthode d'accès mais les méthodes d'accès standards utilisent actuellement 
    282    tous la structure <structname>StdRdOptions</structname>. 
    283    Quand <parameter>validate</parameter> est true, la fonction devrait rapporter 
    284    un message d'erreur convenable si aucune des option n'est pas reconnue ou a des 
     279   La fonction construit une valeur de type <type>bytea</type> à 
     280   copier dans le champ <structfield>rd_options</structfield> de l'entrée relcache 
     281   de l'index. Les données contenues dans la valeur <type>bytea</type> sont 
     282   définies par la méthode d'accès, mais les méthodes d'accès standard utilisent actuellement 
     283   toutes la structure <structname>StdRdOptions</structname>. 
     284   Lorsque <parameter>validate</parameter> est true, la fonction remonte 
     285   un message d'erreur clair si une option n'est pas reconnue ou a des 
    285286   valeurs invalides&nbsp;; quand <parameter>validate</parameter> est false, les 
    286    entrées invalides devraient être ignorées silencieusement. 
    287    (<parameter>validate</parameter> est faux lors du chargement des options déjà 
     287   entrées invalides sont ignorées silencieusement. 
     288   (<parameter>validate</parameter> est faux lors du chargement d'options déjà 
    288289   stockées dans <structname>pg_catalog</structname>&nbsp;; une entrée invalide 
    289    pourrait seulement être trouvée si la méthode d'accès a modifié ses règles pour 
     290   ne peut être trouvée que si la méthode d'accès a modifié ses règles pour 
    290291   les options et, dans ce cas, ignorer les entrées obsolètes est approprié.) 
    291    Il est aussi bon de renvoyer NULL si le comportement par défaut est voulu. 
    292   </para> 
    293  
    294   <para> 
    295    Bien sûr, Le but d'un index est de supporter les parcours de lignes 
    296    correspondant à une condition <literal>WHERE</literal> indexable, souvent appelée 
    297    un <firstterm>qualifieur</firstterm> ou une <firstterm>clé de parcours</firstterm>. La sémantique 
     292   Pour obtenir le comportement par défaut, il suffit de retourner NULL. 
     293  </para> 
     294 
     295  <para> 
     296   Le but d'un index est de supporter les parcours de lignes 
     297   qui correspondent à une condition <literal>WHERE</literal> indexable, souvent appelée 
     298   <firstterm>qualificateur</firstterm> 
     299   (<foreignphrase>qualifier</foreignphrase>) ou <firstterm>clé de 
     300   parcours</firstterm> (<foreignphrase>scan key</foreignphrase>). La sémantique 
    298301   du parcours d'index est décrite plus complètement dans <xref linkend="index-scanning"/>, 
    299    ci-dessous. Les fonctions relatives au parcours qu'une méthode d'accès à 
     302   ci-dessous. Les fonctions liées au parcours qu'une méthode d'accès à 
    300303   l'index doit fournir sont&nbsp;: 
    301304  </para> 
    …… 
    307310             ScanKey key); 
    308311</programlisting> 
    309    Débute un nouveau parcours. Le tableau <literal>key</literal> (de longueur 
     312   Débuter un nouveau parcours. Le tableau <literal>key</literal> (de longueur 
    310313   <literal>nkeys</literal>) décrit les clés de parcours pour le parcours de 
    311    l'index. Le résultat doit être une structure issue de palloc. Pour les 
    312    raisons de l'implémentation, la méthode d'accès à l'index <emphasis>doit</emphasis> 
     314   l'index. Le résultat doit être une structure allouée par palloc. Pour des 
     315   raisons de codage, la méthode d'accès à l'index <emphasis>doit</emphasis> 
    313316   créer cette structure en appelant <function>RelationGetIndexScan()</function>. Dans 
    314    la plupart des cas, <function>ambeginscan</function> fait peu en dehors de cet 
    315    appel&nbsp;; les parties intéressantes de début du parcours d'index sont 
     317   la plupart des cas, <function>ambeginscan</function> se contente de réaliser 
     318   l'appel&nbsp;; les parties intéressantes de début de parcours d'index sont 
    316319   dans <function>amrescan</function>. 
    317320  </para> 
    …… 
    322325            ScanDirection direction); 
    323326</programlisting> 
    324    Récupère la prochaine ligne dans le parcours donné, se déplaçant dans bonne 
    325    direction (en avant ou en arrière dans l'index). Renvoie TRUE si une ligne a 
    326    été obtenue, FALSE s'il ne reste aucune ligne correspondante. Dans le cas 
    327    TRUE, le TID de la ligne est stocké dans la structure <literal>scan</literal>. Notez 
    328    que <quote>success</quote> signifie seulement que l'index contient une entrée 
    329    correspondant aux clés de parcours, pas que la ligne existe toujours dans 
    330    l'en-tête ou réussira le test de l'appelant. 
     327   Récupérer la prochaine ligne d'un parcours donné, dans la direction donnée 
     328   (vers l'avant ou l'arrière de l'index). Renvoie TRUE si une ligne a 
     329   été obtenue, FALSE s'il ne reste aucune ligne. Dans le cas 
     330   TRUE, le TID de la ligne est stocké dans la structure 
     331   <literal>scan</literal>. <quote>success</quote> signifie uniquement que 
     332   l'index contient une entrée qui correspond aux clés de parcours, pas que 
     333   la ligne existe toujours dans la pile ou qu'elle peut réussir le test 
     334   d'instantané de l'appelant. 
    331335  </para> 
    332336 
    …… 
    338342            int32 *returned_tids); 
    339343</programlisting> 
    340    Récupère plusieurs lignes dans le parcours donné. Renvoie TRUE si le parcours 
    341    devait continuer, FALSE si aucune ligne correspondante ne reste. 
    342    <literal>tids</literal> pointe vers un tableau de <literal>max_tids</literal> fourni par 
    343    l'appelant. <structname>ItemPointerData</structname> enregistre, ce que l'appel remplit 
    344    avec les TID des lignes correspondantes. <literal>*returned_tids</literal> est 
    345    initialisé au nombre de TID réellement renvoyé. Ceci peut être moins que 
    346    <literal>max_tids</literal>, voire même zéro, même si la valeur de retour vaut 
    347    TRUE (ceci permet à la méthode d'accès de choisir les points d'arrêt les 
     344   Récupérer plusieurs lignes d'un parcours donné. Renvoie TRUE si le parcours 
     345   peut continuer, FALSE s'il ne subsiste plus aucune ligne. 
     346   <literal>tids</literal> pointe sur un tableau fournit par l'appelant de 
     347   <literal>max_tids</literal> enregistrements <structname>ItemPointerData</structname>, 
     348   remplit, à l'appel, des TID des lignes correspondantes. <literal>*returned_tids</literal> est 
     349   initialisé au nombre de TID réellement renvoyés. Il peut y en avoir moins 
     350   que <literal>max_tids</literal>, voire zéro, même si la valeur de retour vaut 
     351   TRUE. (Cette provision permet à la méthode d'accès de choisir les points d'arrêt les 
    348352   plus efficaces dans son parcours, par exemple les limites de la page d'index). 
    349353   <function>amgetmulti</function> et <function>amgettuple</function> ne peuvent pas être utilisés 
    350    dans le même parcours d'index&nbsp;; il y a aussi d'autres restrictions lors de 
    351    l'utilisation de <function>amgetmulti</function>, comme expliqué dans <xref 
     354   dans le même parcours d'index&nbsp;; l'utilisation de 
     355   <function>amgetmulti</function> est soumise à d'autres restrictions, comme expliqué dans <xref 
    352356   linkend="index-scanning"/>. 
    353357  </para> 
    …… 
    358362          ScanKey key); 
    359363</programlisting> 
    360    Recommence le parcours donné, si possible avec de nouvelles clés de parcours 
    361    (pour continuer à utiliser les anciennes clés, NULL est passé pour 
    362    <literal>key</literal>). Notez qu'il n'est pas possible de changer le nombre de 
    363    clés. En pratique, la fonctionnalité de relancement est utilisée quand une 
    364    nouvelle ligne externe est sélectionné par une jointure imbriquée en boucle 
    365    et, du coup, la valeur de la comparaison d'une nouvelle clé est nécessaire 
    366    mais la structure de la clé de parcours reste identique. Cette fonction est 
    367    aussi appelée par <function>RelationGetIndexScan()</function>, donc c'est utilisé pour 
    368    une configuration initiale d'un parcours d'index ainsi que pour parcourir de 
    369    nouveau. 
     364   Recommencer le parcours donné, si possible avec de nouvelles clés de parcours 
     365   (pour continuer à utiliser les anciennes clés, passer NULL pour 
     366   <literal>key</literal>). Il n'est pas possible de changer le nombre de 
     367   clés. En pratique, la fonctionnalité de relance est utilisée quand une 
     368   nouvelle ligne externe est sélectionnée par une jointure imbriquée en 
     369   boucle, ce qui impose une nouvelle valeur de comparaison de clés,  
     370   mais la structure de la clé de parcours reste inchangée. Cette fonction est 
     371   aussi appelée par <function>RelationGetIndexScan()</function>. Elle est de 
     372   ce fait à la fois utilisée pour initialiser un parcours d'index et 
     373   pour le re-parcourir. 
    370374  </para> 
    371375 
    …… 
    374378amendscan (IndexScanDesc scan); 
    375379</programlisting> 
    376    Termine un parcours et libère les ressources. La structure <literal>scan</literal> 
    377    elle-même ne devrait pas être libérée, mais aucun verrou pris en interne par 
     380   Terminer un parcours et libérer les ressources. La structure <literal>scan</literal> 
     381   elle-même ne doit pas être libérée, mais tout verrou pris en interne par 
    378382   la méthode d'accès doit être libéré. 
    379383  </para> 
    …… 
    383387ammarkpos (IndexScanDesc scan); 
    384388</programlisting> 
    385    Marque la position courante du parcours. La méthode d'accès a seulement 
    386    besoin de supporter le rappel d'une position de parcours par parcours. 
     389   Marquer la position courante du parcours. La méthode d'accès ne mémorise 
     390   qu'une seule position par parcours. 
    387391  </para> 
    388392 
    …… 
    391395amrestrpos (IndexScanDesc scan); 
    392396</programlisting> 
    393    Restaure le parcours à sa plus récente position marquée. 
     397   Restaurer le parcours à sa plus récente position marquée. 
    394398  </para> 
    395399 
    396400  <para> 
    397401   Par convention, l'entrée <literal>pg_proc</literal> de toute fonction de 
    398    méthode d'accès aux index devrait afficher le bon nombre d'arguments, mais 
    399    les déclarer comme étant du type <type>internal</type> (car la plupart des 
    400    arguments ont des types qui ne sont pas connus en SQL, et nous ne voulons 
    401    pas que les utilisateurs appelent les fonctions directement). Le type 
    402    renvoyé est déclaré comme <type>void</type>, <type>internal</type> ou <type>boolean</type> 
     402   méthode d'accès aux index affiche le bon nombre d'arguments, mais 
     403   les déclare tous du type <type>internal</type> (la plupart des 
     404   arguments ont des types qui ne sont pas connus en SQL, et il n'est pas 
     405   souhaitable que les utilisateurs appelent les fonctions directement). Le type 
     406   de retour est déclaré <type>void</type>, <type>internal</type> ou <type>boolean</type> 
    403407   suivant le cas. 
    404    La seule exception est <function>amoptions</function>, qui devrait être 
    405    correctement déclarée comme prenant <type>text[]</type> et <type>bool</type> 
    406    et renvoyer <type>bytea</type>. Cette provision autorise le code du client à 
     408   La seule exception est <function>amoptions</function>, qui doit être 
     409   correctement déclarée prenant <type>text[]</type> et <type>bool</type> 
     410   et retournant <type>bytea</type>. Cette protection autorise le code client à 
    407411   exécuter <function>amoptions</function> pour tester la validité des paramètres. 
    408412  </para> 
    …… 
    410414 </sect1> 
    411415 
     416<!-- SAS::ICI --> 
    412417 <sect1 id="index-scanning"> 
    413418  <title>Parcours d'index</title>