Documentation PostgreSQL 15.15 » Internes » Index B-Tree » Fonctions de support B-Tree

Précédent | Niveau supérieur | Suivant
67.2. Comportement des classes d'opérateur B-Tree | Sommaire | 67.4. Implémentation

## 67.3. Fonctions de support B-Tree

Comme montré dans Tableau 38.9, btree définit une fonction de support obligatoire et quatre facultatives. Les cinq méthodes définies par l'utilisateur sont :

`order`

  Pour chaque combinaison de types de données pour laquelle une famille d'opérateur B-tree fournit des opérateurs de comparaison, elle doit fournir une fonction de support de comparaison inscrite dans `pg_amproc` avec la fonction de support 1 et `amproclefttype`/`amprocrighttype` égaux aux types de données gauche et droit pour la comparaison (c'est-à-dire les mêmes types de données que l'opérateur correspondant a inscrit dans `pg_amop`). La fonction de comparaison doit prendre en entrée deux valeurs non nulles `A` et `B` et retourner une valeur `int32` qui est `<` `0`, `0`, ou `>` `0` quand, respectivement `A` `<` `B`, `A` `=` `B`, ou `A` `>` `B`. Une valeur de retour NULL est également interdite : toutes les valeurs du type de données doivent être comparables. Voir `src/backend/access/nbtree/nbtcompare.c` pour plus d'exemples.

  Si les valeurs comparées sont d'un type avec collation, l'identifiant de collation approprié sera passé à la fonction de support de comparaison, en utilisant le mécanisme standard `PG_GET_COLLATION()`.

`sortsupport`

  De manière facultative, une famille d'opérateurs B-tree peut fournir une ou plusieurs fonctions sort support, inscrites comme fonctions de support numéro 2. Ces fonctions permettent d'implémenter des comparaisons dans l'optique de tri de manière plus efficace qu'appeler naivement la fonction de support de comparaison. Les API impliquées pour cela sont définies dans `src/include/utils/sortsupport.h`.

`in_range`

  De manière facultative, une famille d'opérateurs B-tree peut fournir une ou plusieurs fonctions de support in_range inscrites comme fonction de support numéro 3. Celles-ci ne sont pas utilisées durant les opérations d'index B-tree ; mais plutôt, elles étendent les sémantiques de la famille d'opérateurs de telle manière qu'elles puissent supporter les clauses de fenêtrage contenant les types de limite de cadre `RANGE` `décalage` `PRECEDING` et `RANGE` `décalage` `FOLLOWING` (voir Section 4.2.8). Fondamentalement, les informations supplémentaires fournies sont comment additionner et soustraire une valeur d'un `décalage` d'une manière qui est compatible avec le tri de données de la famille.

  Une fonction `in_range` doit avoir la signature

      in_range(val type1, base type1, offset type2, sub bool, less bool)
      returns bool

  `val` et `base` doivent être du même type, qui est un des types supportés par la famille d'opérateur (c'est-à-dire un type pour lequel elle fournit un tri). Cependant, `offset` peut être d'un type de données différent, qui peut par ailleurs ne pas être supporté par la famille. Un exemple est que la famille `time_ops` incluse par défaut fournit une fonction `in_range` qui a un `offset` de type `interval`. Une famille peut fournir des fonctions `in_range` pour n'importe lesquels des types de données qu'elle supporte, et un ou plusieurs types `offset`. Chaque fonction `in_range` devrait être inscrite dans `pg_amproc` avec `amproclefttype` égal à `type1` et `amprocrighttype` égal à `type2`.

  Les sémantiques essentielles pour une fonction `in_range` dépendent des deux paramètres de drapeau booléens. Elle devrait ajouter ou soustraire `base` et `offset`, puis comparer `val` au résultat, comme ceci :

  - si `!``sub` et `!``less`, renvoyer `val` `>=` (`base` `+` `offset`)

  - si `!``sub` et `less`, renvoyer `val` `<=` (`base` `+` `offset`)

  - si `sub` et `!``less`, renvoyer `val` `>=` (`base` `-` `offset`)

  - si `sub` et `less`, renvoyer `val` `<=` (`base` `-` `offset`)

  Avant de procéder, la fonction devrait vérifier le signe d'`offset` : s'il est inférieur à zéro, lever l'erreur `ERRCODE_INVALID_PRECEDING_OR_FOLLOWING_SIZE` (22013) avec un message d'erreur tel que « taille précédente ou suivante invalide dans la fonction de fenêtrage ». (Cela est requis par le standard SQL, bien que des familles d'opérateur non standards pourraient peut être choisir d'ignorer cette restriction, puisqu'il n'y a pas vraiment de nécessité de sémantique dans ce cas.) Cette exigence est déléguée à la fonction `in_range` si bien que le code du moteur n'a pas besoin de comprendre ce que « inférieur à zéro » signifie pour un type de données particulier.

  Une autre attente est que les fonctions `in_range` devraient, si applicable, éviter de générer une erreur si `base` `+` `offset` ou `base` `-` `offset` devait causer un débordement. Le résultat de comparaison correct peut être déterminé même si cette valeur devait être en dehors de l'intervalle des valeurs du type de données. Notez que si le type de données inclut des concepts tels que « infinity » ou « NaN », des précautions supplémentaires pourraient être nécessaires pour s'assurer que les résultats de `in_range` soient en accord avec l'ordre de tri normal de la famille d'opérateurs.

  Les résultats de la fonction `in_range` doivent être cohérents avec l'ordre de tri imposé par la famille d'opérateurs. Pour être précis, pour n'importe quelles valeurs fixées de `offset` et `sub`, alors :

  - Si `in_range` avec `less` = true est vrai pour certains `val1` et `base`, il doit être vrai pour chaque `val2` `<=` `val1` avec le même `base`.

  - Si `in_range` avec `less` = true est faux pour certains `val1` et `base`, il doit être faux pour chaque `val2` `>=` `val1` avec le même `base`.

  - Si `in_range` avec `less` = true est vrai pour certains `val` et `base1`, il doit être vrai pour chaque `base2` `>=` `base1` avec le même `val`.

  - Si `in_range` avec `less` = true est faux pour certains `val` et `base1`, il doit être faux pour chaque `base2` `<=` `base1` avec le même `val`.

  Des déclarations similaires avec des conditions inversées continuent à s'appliquer quand `less` = false.

  Si le type est trié (`type1`) par rapport à une collation, l'OID de collation approprié sera passé à la fonction `in_range` en utilisant le mécanisme standard `PG_GET_COLLATION()`.

  Les fonctions `in_range` n'ont pas besoin de gérer les valeurs en entrée NULL, et typiquement elles seront marquées comme strict.

`equalimage`

  Une famille d'opérateurs B-tree facultative peut fournir les fonctions de support `equalimage` (« l'égalité implique une égalité d'image »), inscrites comme fonctions de support numéro 4. Ces fonctions permettent au code du moteur de déterminer quand il est sûr d'appliquer l'optimisation de dédoublonnage B-tree. Actuellement, les fonctions `equalimage` sont seulement appelées lors de la construction ou reconstruction d'un index.

  Une fonction `equalimage` doit avoir comme signature

      equalimage(opcintype oid) returns bool

  La valeur retournée est une information statique relative à une classe d'opérateur et une collation. Retourner `true` indique que la fonction `order` pour la classe d'opérateurs est garantie de retourner seulement `0` (« les arguments sont égaux ») quand ses arguments `A` et `B` sont aussi interchangeables sans aucune perte d'information sémantique. Ne pas inscrire une fonction `equalimage` ou retourner `false` indique que cette condition ne peut être tenue.

  L'argument `opcintype` est le ``pg_type`.oid` du type de données que la classe d'opérateurs indexe. Ceci est une commodité qui permet de réutiliser la même fonction `equalimage` sous-jacente entre plusieurs classes d'opérateurs. Si `opcintype` est un type de données collationné, l'identifiant de collation appropriée sera passé à la fonction `equalimage`, par le mécanisme standard `PG_GET_COLLATION()`.

  Tant que la classe d'opérateurs est concernée, retourner `true` indique que le dédoublement est sûr (ou sûr pour la collation dont l'identifiant a été passé à sa fonction `equalimage`). Cependant, le code du moteur considérera le dédoublonnage sécurisé pour un index, si chaque colonne indexée utilise une classe d'opérateur ayant inscrit une fonction `equalimage`, et si chaque fonction retourne `true` par appel.

  L'égalité d'image est presque la même condition qu'une simple égalité bit à bit. Il n'y a qu'une seule et subtile différence : en indexant un type de données « varlena », la représentation sur disque de deux images de données égales peuvent ne pas être identiques bit à bit, à cause des incohérences lors de l'application de la compression TOAST sur les données en entrée. Dans les règles, quand une fonction `equalimage` d'une classe d'opérateurs retourne `true`, on peut présumer sans se tromper que la fonction C `datum_image_eq()` correspondra avec la fonction `order` de la classe d'opérateurs (sous réserve que le même identifiant de collation soit passé aux fonctions `equalimage` et `order`).

  Le code du moteur est fondamentalement incapable de déduire quoi que ce soit au sujet du statut « l'égalité implique l'égalité d'image » d'une classe d'opérateurs incluse dans une famille de types de données multiples en se basant sur les détails d'autres classes d'opérateur de la même famille. Aussi, il n'est pas pertinent pour une famille d'opérateurs d'inscrire une fonction `equalimage` inter-type, et essayer déclenchera une error. En effet, le statut de « l'égalité implique l'égalité d'image » ne dépend pas juste de la sémantique de l'ordre/égalité, qui est plus ou moins définie au niveau de la famille d'opérateurs. En général, les sémantiques d'un type particulier de données doivent être considérées séparément.

  La convention suivie par les classes d'opérateurs incluses avec la distribution principale PostgreSQL est d'inscrire une fonction générique `equalimage`. La plupart des classes d'opérateurs inscrivent `btequalimage()`, qui indique que le dédoublonnage est sécurisé sans conditions. Les classes d'opérateurs pour les types de données collationnés comme `text` inscrivent `btvarstrequalimage()`, qui indique que le dédoublonnage est sécurisé avec les collations déterministes. La bonne pratique pour une extension tierce est d'inscrire leur propre fonction personnalisée pour garder le contrôle.

`options`

  En option, une famille d'opérateurs B-tree peut fournir des fonctions de support des `options` (« options spécifiques à la classe d'opérateurs »), enregistrées sous le numéro 5 des fonctions de support. Ces fonctions définissent un ensemble de paramètres visibles à l'utilisateur et contrôlant le comportement de la classe d'opérateurs.

  Une fonction de support `options` doit avoir cette signature

      options(relopts local_relopts *) returns void

  La fonction se voit fournie un pointeur vers une structure `local_relopts` qui doit être remplie avec un ensemble d'options spécifiques à une classe d'opérateurs. Les options sont accessibles à partir des autres fonctions de support en utilisant les macros `PG_HAS_OPCLASS_OPTIONS()` et `PG_GET_OPCLASS_OPTIONS()`.

  Actuellement, aucune classe d'opérateurs B-Tree n'a de fonction de support `options`. B-tree n'autorise pas une représentation flexible des clés comme GiST, SP-GiST, GIN et BRIN le font. Donc, `options` n'a probablement pas beaucoup d'intérêt pour la méthode d'accès aux index B-tree actuellement. Néanmoins, cette fonction de support a été ajouté au B-tree par cohérence, et trouvera probablement son utilité lors des prochaines évolutions du B-tree dans PostgreSQL.