Documentation PostgreSQL 8.4.22 > Internes > Index GIN > Extensibilité | |
Index GIN | Implantation |
L'interface GIN a un haut niveau d'abstraction. De ce fait, la personne qui code la méthode d'accès n'a besoin d'implanter que les sémantiques du type de données accédé. La couche GIN prend en charge la gestion de la concurrence, des traces et des recherches dans la structure de l'arbre.
Pour obtenir une méthode d'accès GIN fonctionnelle, il suffit d'implanter quatre (ou cinq) méthodes utilisateur. Celles-ci définissent le comportement des clés dans l'arbre et les relations entre clés, valeurs indexées et requêtes indexables. En résumé, GIN combine extensibilité, généralisation, ré-utilisation du code à une interface claire.
Les quatre méthodes qu'une classe d'opérateur GIN doit fournir sont :
Compare les clés (et non les valeurs indexées !) et renvoie un entier négatif, zéro ou un entier positif, qui indique si la première clé est inférieure, égale à ou supérieure à la seconde.
Renvoie un tableau de clés à partir d'une valeur à indexer. Le nombre de clés renvoyées doit être stocké dans *nkeys.
Renvoie un tableau de clés en fonction de la valeur à requêter ; c'est-à-dire que query est la valeur du côté droit d'un opérateur indexable dont le côté gauche est la colonne indexée. n est le numéro de stratégie de l'opérateur dans la classe d'opérateur (voir Section 34.14.2, « Stratégies des méthode d'indexation »). Souvent, extractQuery doit consulter n pour déterminer le type de données de query et les valeurs de clés à extraire. Le nombre de clés renvoyées doit être stocké dans *nkeys. Si query ne contient aucune clé alors extractQuery devra retourner 0 ou -1 dans *nkeys, en fonction des sémantiques de l'opérateur. 0 signifie que toutes les valeurs correspondent à query et qu'un parcours d'index complet doit être effectué (mais voir Section 52.5, « Limitations » pour plus de détails). -1 signifie que rien ne peut correspondre à query, ce qui entraîne que le parcours d'index peut être totalement évité. pmatch est un paramètre de sortie à utiliser quand une correspondance partielle est permise. Pour l'utiliser, extractQuery doit allouer un tableau de booléens *nkeys et stocker son adresse dans *pmatch. Chaque élément du tableau devrait être positionné à TRUE si la clé correspondante a besoin d'une correspondance partielle, FALSE sinon. Si *pmatch est positionné à NULL alors GIN suppose qu'une mise en correspondance partielle n'est pas nécessaire. La variable est initialisée à NULL avant l'appel, et peut donc être simplement ignorée par les classes d'opérateurs qui ne supportent pas les correspondances partielles. extra_data est un paramètre de sortie qui autorise extractQuery à passer des données supplémentaires aux méthodes consistent et comparePartial. Pour l'utiliser, extractQuery doit allouer un tableau de pointeurs *nkeys et stocker son adresse à *extra_data, puis stocker ce qu'il souhaite dans les pointeurs individuels. La variable est initialisée à NULL avant l'appel, afin que ce paramètre soit simplement ignoré par une classe d'opérateurs qui n'a pas besoin de données supplémentaires. Si *extra_data est positionné, le tableau dans son ensemble est passé à la méthode consistent method, et l'élément approprié à la méthode comparePartial.
Retourne TRUE si la valeur indexée satisfait à l'opérateur de requête avec le numéro de stratégie n (ou pourrait satisfaire, si l'indication recheck est retournée). Le tableau check a la longueur nkeys, qui est la même que le nombre de clés retournées précédemment par extractQuery pour ce datum, query. Chaque élément du tableau check est TRUE si la valeur indexée contient la clé correspondante de la requête, c'est-à-dire que si (check[i] == TRUE), la i-ème clé du tableau résultant d'extractQuery est présente dans la valeur indexée. Le datum query d'origine (pas le tableau de clés extrait !) est passé au cas où la méthode consistent a besoin de le consulter. extra_data est le tableau de données supplémentaires retourné par extractQuery, ou NULL si aucun. En cas de succès, *recheck devrait être positionné à TRUE si l'enregistrement du heap a besoin d'être revérifié vis-à-vis de l'opérateur de la requête, ou FALSE si le test sur l'index est exact.
En option, une classe d'opérateurs pour GIN peut fournir une cinquième méthode :
Compare une requête de correspondance partielle à une clé d'index. Renvoie un entier dont le signe indique le résultat : inférieur à zéro signifie que la clé d'index ne correspond pas à la requête mais que le parcours d'index va continuer ; zéro signifie que la clé d'index ne correspond pas à la requête ; supérieur à zéro indique que le parcours d'index doit s'arrêter car il n'existe pas d'autres correspondances. Le numéro de stratégie n de l'opérateur qui a généré la requête de correspondance partielle est fourni au cas où sa sémantique est nécessaire pour déterminer la fin du parcours. De plus, extra_data est l'élément correspondant du tableau extra-data fait par extractQuery, ou NULL sinon.
Pour supporter des requêtes à « correspondance partielle », une classe d'opérateur doit fournir la méthode comparePartial, et sa méthode extractQuery doit positionner le paramètre pmatch quand une requête à correspondance partielle est rencontrée. Voir Section 52.3.2, « Algorithme de mise en correspondance partielle » pour les détails.