diff --git a/postgresql/tablesample-method.xml b/postgresql/tablesample-method.xml index d3f59f9c9..78c4e1c98 100644 --- a/postgresql/tablesample-method.xml +++ b/postgresql/tablesample-method.xml @@ -2,44 +2,49 @@ - Writing A Table Sampling Method + Écrire une méthode d'échantillonnage de table - table sampling method + méthode d'échantillonage de table - TABLESAMPLE method + Méthode TABLESAMPLE - PostgreSQL's implementation of the TABLESAMPLE - clause supports custom table sampling methods, in addition to - the BERNOULLI and SYSTEM methods that are required - by the SQL standard. The sampling method determines which rows of the - table will be selected when the TABLESAMPLE clause is used. + L'implémentation de la clause TABLESAMPLE de + PostgtreSQL supporte l'utilisation de + méthodes personnalisées d'échantillonnage de table, en plus des + méthodes BERNOULLI et SYSTEM + qui sont requises par le standard SQL. La méthode d'échantillonnage + détermine quelles lignes de la table seront sélectionnées lorsque + la clause TABLESAMPLE sera utilisée. - At the SQL level, a table sampling method is represented by a single SQL - function, typically implemented in C, having the signature + Au niveau SQL, une méthode d'echantillonnage de table est représentée + par une simple fonction, classiquement implémentée en C, et qui a + la signature suivante  method_name(internal) RETURNS tsm_handler - The name of the function is the same method name appearing in the - TABLESAMPLE clause. The internal argument is a dummy - (always having value zero) that simply serves to prevent this function from - being called directly from a SQL command. - The result of the function must be a palloc'd struct of - type TsmRoutine, which contains pointers to support functions for - the sampling method. These support functions are plain C functions and - are not visible or callable at the SQL level. The support functions are - described in . + Le nom de la fonction est le même que le nom de la méthode + apparaissant dans la clause TABLESAMPLE. L'argument + internal est factice (il a toujours une valeur de + zéro) qui sert uniquement à interdire que cette fonction soit + appelée directement à partir d'une commande SQL. Le résultat + de cette fonction doit être une structure allouée avec palloc + de type TsmRoutine, qui contient des pointeurs de + fonction supportant la méthode d'échantillonnage. Ces fonctions + sont des fonctions C pleines et entières qui ne sont ni visibles ni + appellables au niveau SQL. Les fonctions de support sont décrites + à . - In addition to function pointers, the TsmRoutine struct must - provide these additional fields: + En plus des pointeurs de fonction, la structure TsmRoutine + doit fournir ces champs additionnels : @@ -47,12 +52,14 @@ method_name(internal) RETURNS tsm_handler List *parameterTypes - This is an OID list containing the data type OIDs of the parameter(s) - that will be accepted by the TABLESAMPLE clause when this - sampling method is used. For example, for the built-in methods, this - list contains a single item with value FLOAT4OID, which - represents the sampling percentage. Custom sampling methods can have - more or different parameters. + Il s'agit d'une liste d'OIDs contenant les OIDs des types de + données du ou des paramètre(s) qui seront acceptés par la + clause TABLESAMPLE lorsque cette méthode + d'échantillonnage sera utilisée. Par exemple, pour les méthodes + incluses, cette liste contient un simple élément avec la valeur + FLOAT4OID, qui représente le pourcentage + d'échantillonnage. Les méthodes d'échantillonnage personnalisées + peuvent avoir des paramètres en plus ou différents. @@ -61,12 +68,14 @@ method_name(internal) RETURNS tsm_handler bool repeatable_across_queries - If true, the sampling method can deliver identical samples - across successive queries, if the same parameters - and REPEATABLE seed value are supplied each time and the - table contents have not changed. When this is false, - the REPEATABLE clause is not accepted for use with the - sampling method. + Si true, la méthode d'échantillonnage + peut renvoyer des échantillons identiques pour des requêtes + successives, si les même paramètres et la valeur de graine de la + clause REPEATABLE sont fournis à chaque fois et + que le contenu de la table n'a pas changé. Lorsque positionné à + false, la clause REPEATABLE + n'est pas acceptée comme valable pour la méthode + d'échantillonnnage. @@ -75,39 +84,43 @@ method_name(internal) RETURNS tsm_handler bool repeatable_across_scans - If true, the sampling method can deliver identical samples - across successive scans in the same query (assuming unchanging - parameters, seed value, and snapshot). - When this is false, the planner will not select plans that - would require scanning the sampled table more than once, since that - might result in inconsistent query output. + Si true, la méthode d'échantillonnage peut + renvoyer des échantillons identiques pour des parcours successifs + dans la même requête (en supposant des paramètres, une graine + et une image de la base inchangés). Lorsque positionné à + false, le planificateur ne sélectionnera pas + des plans qui requièrent de parcourir la table échantillonnée + plus d'une fois, dans la mesure où ceci pourrait entraîner des + résultats de sortie incohérents. - The TsmRoutine struct type is declared - in src/include/access/tsmapi.h, which see for additional - details. + La structure TsmRoutine est déclarée dans le + fichier src/include/access/tsmapi.h, auquel il + convient de se référer pour des détails additionnels. - The table sampling methods included in the standard distribution are good - references when trying to write your own. Look into - the src/backend/access/tablesample subdirectory of the source - tree for the built-in sampling methods, and into the contrib - subdirectory for add-on methods. + Les méthodes d'échantillonnage de table incluses dans + la distribution standard sont de bonnes références + pour écrire la vôtre. Jeter un œil dans le répertoire + src/backend/access/tablesample de l'arbre + des sources pour les méthodes incluses, et dans le répertoire + contrib pour des méthodes additionnelles. - Sampling Method Support Functions + Fonctions de support d'une méthode d'échantillonnage - The TSM handler function returns a palloc'd TsmRoutine struct - containing pointers to the support functions described below. Most of - the functions are required, but some are optional, and those pointers can - be NULL. + La fonction du gestionnaire TSM renvoie une structure + TsmRoutine allouée avec palloc contenant des pointeurs + vers les fonctions de support décrites ci-dessous. La plupart des + fonctions sont obligatoires, mais certaines sont optionnelles, et ces + pointeurs peuvent être NULL. @@ -119,21 +132,26 @@ SampleScanGetSampleSize (PlannerInfo *root, BlockNumber *pages, double *tuples); - - This function is called during planning. It must estimate the number of - relation pages that will be read during a sample scan, and the number of - tuples that will be selected by the scan. (For example, these might be - determined by estimating the sampling fraction, and then multiplying - the baserel->pages and baserel->tuples - numbers by that, being sure to round the results to integral values.) - The paramexprs list holds the expression(s) that are - parameters to the TABLESAMPLE clause. It is recommended to - use estimate_expression_value() to try to reduce these - expressions to constants, if their values are needed for estimation - purposes; but the function must provide size estimates even if they cannot - be reduced, and it should not fail even if the values appear invalid - (remember that they're only estimates of what the run-time values will be). - The pages and tuples parameters are outputs. + Cette fonction est appelée durant la planification. Elle doit + estimée le nombre de pages de la relation qui seront lues + lors d'un simple parcours, et le nombre de lignes qui seront + sélectionnées lors du parcours. (Par exemple, cela pourrait + être déterminé en estimant la fraction échantillonnée, + puis en multipliant baserel->pages + et baserel->tuples par ce chiffre, + après s'être assuré d'avoir arrondi ces chiffres à des + valeurs entières.) La liste paramexprs + contient les expressions qui sont les paramètres de la clause + TABLESAMPLE. Il est recommandé d'utiliser + la fonction estimate_expression_value pour + essayer de réduire ces expressions à des constantes, si leurs + valeurs sont nécessaires pour les besoins de l'estimation; mais la + fonction doit renvoyer les estimations des tailles même si elles + ne peuvent être réduites, et elle ne devrait pas échouer même + si les valeurs apparaissent invalides (rappelez vous qu'il s'agit + uniquement d'une estimation de valeurs futures à l'exécution). Les + paramètres pages et tuples + sont les valeurs de sorties. @@ -143,33 +161,38 @@ InitSampleScan (SampleScanState *node, int eflags); - Initialize for execution of a SampleScan plan node. - This is called during executor startup. - It should perform any initialization needed before processing can start. - The SampleScanState node has already been created, but - its tsm_state field is NULL. - The InitSampleScan function can palloc whatever internal - state data is needed by the sampling method, and store a pointer to - it in node->tsm_state. - Information about the table to scan is accessible through other fields - of the SampleScanState node (but note that the - node->ss.ss_currentScanDesc scan descriptor is not set - up yet). - eflags contains flag bits describing the executor's - operating mode for this plan node. + Initialise pour l'exécution d'un nœud du plan SampleScan. + La fonction est appelée au démarrage de l'exécuteur. Elle + devrait effectuer toutes les initialisations nécessaires + avant que le traitement puisse commencer. Le nœud + SampleScanState a déjà été + créé, mais son champ tsm_state + est NULL. La fonction peut allouer via palloc les + données internes d'état nécessaires à la fonction + d'échantillonnage, et enregistrer un pointeur dans + node->tsm_state. Des informations à + propos de la table à parcourir sont accessibles via d'autres + champs du nœud SampleScanState + (mais veuillez noter que le descripteur du parcours + node->ss.ss_currentScanDesc n'est pas + encore positionné à ce stade). eflags + contient un ensemble de bits décrivant le mode opératoire de + l'exécuteur pour ce nœud du plan. - When (eflags & EXEC_FLAG_EXPLAIN_ONLY) is true, - the scan will not actually be performed, so this function should only do - the minimum required to make the node state valid for EXPLAIN - and EndSampleScan. + Lorsque (eflags & EXEC_FLAG_EXPLAIN_ONLY) est + true, le parcours ne sera actuellement pas effectué, dans ce cas cette + fonction devrait effectuer uniquement le minimum requis pour mettre dans + un état valide le nœud pour la commande EXPLAIN + et la fonction EndSampleScan. - This function can be omitted (set the pointer to NULL), in which case - BeginSampleScan must perform all initialization needed - by the sampling method. + Cette fonction est optionnelle (positionnez alors le pointeur sur + NULL), auquel cas la fonction BeginSampleScan + doit effectuer toutes les initialisations nécessaires à la méthode + d'échantillonnage. @@ -181,48 +204,55 @@ BeginSampleScan (SampleScanState *node, uint32 seed); - Begin execution of a sampling scan. - This is called just before the first attempt to fetch a tuple, and - may be called again if the scan needs to be restarted. - Information about the table to scan is accessible through fields - of the SampleScanState node (but note that the - node->ss.ss_currentScanDesc scan descriptor is not set - up yet). - The params array, of length nparams, contains the - values of the parameters supplied in the TABLESAMPLE clause. - These will have the number and types specified in the sampling - method's parameterTypes list, and have been checked - to not be null. - seed contains a seed to use for any random numbers generated - within the sampling method; it is either a hash derived from the - REPEATABLE value if one was given, or the result - of random() if not. + Débute l'exécution d'un parcours d'échantillonnage. Cette + fonction est appelée juste avant la première tentative de + récupérer une ligne, et peut être appelée à nouveau si le + parcours a besoin d'être relancé. Des informations sur la table à + parcourir sont accessibles via les champs de la structure du nœud + SampleScanState (mais notez que le descripteur + du parcours node->ss.ss_currentScanDesc n'est pas + encore positionné à ce stade). Le tableau params, + de longueur nparams, contient les valeurs des + paramètres indiqués dans la clause TABLESAMPLE. Ces + paramètres seront en nombre et de types spécifiés par la méthode + d'échantillonnage dans la liste parameterTypes, et + ont été vérifiés comme n'étant pas null. seed> + contient une graine à usage de la méthode d'échantillonnage pour + générer des nombres aléatoires; il s'agit soit d'un hash dérivé + de la valeur de la clause REPEATABLE si fournie, + soit sinon du résultat de la fonction random(). - This function may adjust the fields node->use_bulkread - and node->use_pagemode. - If node->use_bulkread is true, which it is by - default, the scan will use a buffer access strategy that encourages - recycling buffers after use. It might be reasonable to set this - to false if the scan will visit only a small fraction of the - table's pages. - If node->use_pagemode is true, which it is by - default, the scan will perform visibility checking in a single pass for - all tuples on each visited page. It might be reasonable to set this - to false if the scan will select only a small fraction of the - tuples on each visited page. That will result in fewer tuple visibility - checks being performed, though each one will be more expensive because it - will require more locking. + Cette fonction peut ajuster les champs + node->use_bulkread + et node->use_pagemode. Si + node->use_bulkread est true, ce qui est le cas + par défaut, le parcours utilisera une stratégie d'accès aux tampons + mémoires qui encourage le recyclage des tampons après usage . Il peut être + raisonnable de mettre cette valeur à false + si le parcours doit visiter seulement une petite fraction des pages + de la table. Si node->use_pagemode est + true, ce qui est la valeur par défaut, le parcours + effectuera une vérification de la visibilité avec un unique passage + pour l'ensemble des lignes composant chaque page visitée. Il peut + être raisonnable de mettre cette valeur à false + si le parcours doit sélectionner seulement une petite fraction des lignes de + chaque page visitée. Ceci aura pour conséquence un nombre moindre + de vérifications de visibilité effectuées, mais chacune sera plus + coûteuse car elle demandera plus de verrouillages. - If the sampling method is - marked repeatable_across_scans, it must be able to - select the same set of tuples during a rescan as it did originally, that is - a fresh call of BeginSampleScan must lead to selecting the - same tuples as before (if the TABLESAMPLE parameters - and seed don't change). + Si la méthode d'échantillonnage est marquée comme + repeatable_across_scans, elle doit être capable de + sélectionner le même ensemble de lignes lors d'un parcours relancé + à nouveau comme elle l'a fait à l'origine, c'est à dire qu'un + nouvel appel à la fonction BeginSampleScan doit + engendrer la sélection des même lignes que précédemment (dans la + mesure où les paramètres de la clause TABLESAMPLE + et la graine ne changent pas). @@ -231,16 +261,18 @@ BlockNumber NextSampleBlock (SampleScanState *node); - Returns the block number of the next page to be scanned, or - InvalidBlockNumber if no pages remain to be scanned. + Renvoie le numéro du bloc de la page suivante à parcourir, ou + InvalidBlockNumber si il n'y a plus de pages + à parcourir. - This function can be omitted (set the pointer to NULL), in which case - the core code will perform a sequential scan of the entire relation. - Such a scan can use synchronized scanning, so that the sampling method - cannot assume that the relation pages are visited in the same order on - each scan. + Cette fonction peut être omise (mettez le pointeur à la valeur NULL), + auquel cas le code du serveur effectuera un parcours séquentiel de + l'ensemble de la relation. Un tel parcours peut utiliser un parcours + synchronisé, aussi la méthode d'échantillonnage ne peut pas supposer + que les pages de la relation sont visitées dans le même ordre à + chaque parcours. @@ -251,36 +283,44 @@ NextSampleTuple (SampleScanState *node, OffsetNumber maxoffset); - Returns the offset number of the next tuple to be sampled on the - specified page, or InvalidOffsetNumber if no tuples remain to - be sampled. maxoffset is the largest offset number in use - on the page. + Renvoie le décalage de la ligne suivante à echantillonner sur la + page spécifiée, ou InvalidOffsetNumber si il + n'y a plus de lignes à échantillonner. maxoffset + est le décalage le plus grand utilisé sur la page. - NextSampleTuple is not explicitly told which of the offset - numbers in the range 1 .. maxoffset actually contain valid - tuples. This is not normally a problem since the core code ignores - requests to sample missing or invisible tuples; that should not result in - any bias in the sample. However, if necessary, the function can - examine node->ss.ss_currentScanDesc->rs_vistuples[] - to identify which tuples are valid and visible. (This - requires node->use_pagemode to be true.) + Il n'est pas explicitement indiqué à la fonction + NextSampleTuple les décalages + dans l'intervalle 1 .. maxoffset qui + contiennent des lignes valides. Ce n'est normalement pas + un problème dans la mesure où le code du serveur ignore + les requêtes pour échantillonner des lignes manquantes + ou non visibles; ceci ne devrait pas entraîner de biais dans + l'échantillon. Cependant, si nécessaire, la fonction peut examiner + node->ss.ss_currentScanDesc->rs_vistuples[] + pour identifier les lignes valides et visibles. (Ceci + requiert que node->use_pagemode soit + true.) - NextSampleTuple must not assume - that blockno is the same page number returned by the most - recent NextSampleBlock call. It was returned by some - previous NextSampleBlock call, but the core code is allowed - to call NextSampleBlock in advance of actually scanning - pages, so as to support prefetching. It is OK to assume that once - sampling of a given page begins, successive NextSampleTuple - calls all refer to the same page until InvalidOffsetNumber is - returned. + La fonction NextSampleTuple ne doit + pas assumer que blockno + est le même numéro de page que celui renvoyé par le plus récent + appel à la fonction NextSampleBlock. Le + numéro a été renvoyé par un précédent appel à la fonction + NextSampleBlock, mais le code du serveur + est autorisé à appeler NextSampleBlock + en amont du parcours des pages, pour rendre possible la + récupération en avance. Il est OK d'assumer qu'une fois le + parcours d'une page débuté, les appels successifs à la fonction + NextSampleTuple se réfèrent tous à la + même page jusqu'à ce que InvalidOffsetNumber + soit retourné. @@ -290,11 +330,11 @@ void EndSampleScan (SampleScanState *node); - End the scan and release resources. It is normally not important - to release palloc'd memory, but any externally-visible resources - should be cleaned up. - This function can be omitted (set the pointer to NULL) in the common - case where no such resources exist. + Termine le parcours et libère les ressources. Il est normalement pas + important de libérer la mémoire allouée via palloc, mais toutes les + ressources visibles à l'extérieur doivent être nettoyées. Cette + fonction peut être omise (positionnez le pointeur sur la valeur NULL) + dans la plupart des cas où de telles ressources n'existent pas.