commit add6e90ae3670b5178f8104b5e88c7622fac5f92 Author: Alexander Korotkov Date: Tue Jun 16 14:21:57 2020 +0300 Add documentation for opclass options Reported-by: Bug: Discussion: Author: Reviewed-by: Tested-by: Backpatch-through: diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml index 46a7d07bf8b..1ffb367d3bb 100644 --- a/doc/src/sgml/brin.sgml +++ b/doc/src/sgml/brin.sgml @@ -562,6 +562,36 @@ typedef struct BrinOpcInfo + Optionally, an operator class for BRIN can supply the + following method: + + + + void options(local_relopts *relopts) + + + Defines set of user-visible parameters that controls operator class + behavior. + + + + The options function has given pointer to + local_relopts struct, which needs to be + filled with set of operator class specific option. The options + could be accessible from each support function using + PG_HAS_OPCLASS_OPTIONS() and + PG_GET_OPCLASS_OPTIONS() macros. + + + + Since both key extraction for indexed value and representation of the + key in GIN are flexible, it may depends on + user-specified parameters. + + + + + The core distribution includes support for two types of operator classes: minmax and inclusion. Operator class definitions using them are shipped for in-core data types as appropriate. Additional operator classes can be diff --git a/doc/src/sgml/btree.sgml b/doc/src/sgml/btree.sgml index e9cab4a55dc..8df39cbee2d 100644 --- a/doc/src/sgml/btree.sgml +++ b/doc/src/sgml/btree.sgml @@ -550,6 +550,39 @@ equalimage(opcintype oid) returns bool + + options + + + Optionally, a B-tree operator family may provide + options (operator class specific + options) support functions, registered under support + function number 5. These functions define set of user-visible + parameters that controls operator class behavior. + + + An options support function must have the + signature + +options(relopts local_relopts *) returns void + + The function has given pointer to local_relopts + struct, which needs to be filled with set of operator class + specific option. The options could be accessible from each support + function using PG_HAS_OPCLASS_OPTIONS() and + PG_GET_OPCLASS_OPTIONS() macros. + + + Currently, no B-Tree operator class has options + support function. B-tree doesn't allow flexible representation of keys + like GiST, SP-GiST, GIN and BRIN do. So, options + probably doesn't have much usage in current shape of B-tree index + access method. Nevertheless, this support function was added to B-tree + for uniformity, and probably it will found its usage during further + evolution of B-tree in PostgreSQL. + + + diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml index b4f6abae122..d29ca166e30 100644 --- a/doc/src/sgml/gin.sgml +++ b/doc/src/sgml/gin.sgml @@ -380,7 +380,7 @@ Optionally, an operator class for GIN can supply the - following method: + following methods: @@ -402,6 +402,30 @@ + + void options(local_relopts *relopts) + + + Defines set of user-visible parameters that controls operator class + behavior. + + + + The options function has given pointer to + local_relopts struct, which needs to be + filled with set of operator class specific option. The options + could be accessible from each support function using + PG_HAS_OPCLASS_OPTIONS() and + PG_GET_OPCLASS_OPTIONS() macros. + + + + Since both key extraction for indexed value and representation of the + key in GIN are flexible, it may depends on + user-specified parameters. + + + diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml index 60d77411e03..bc1bda78409 100644 --- a/doc/src/sgml/gist.sgml +++ b/doc/src/sgml/gist.sgml @@ -269,7 +269,7 @@ CREATE INDEX ON my_table USING GIST (my_inet_column inet_ops); There are five methods that an index operator class for - GiST must provide, and four that are optional. + GiST must provide, and five that are optional. Correctness of the index is ensured by proper implementation of the same, consistent and union methods, while efficiency (size and speed) of the @@ -287,7 +287,9 @@ CREATE INDEX ON my_table USING GIST (my_inet_column inet_ops); if the operator class wishes to support ordered scans (nearest-neighbor searches). The optional ninth method fetch is needed if the operator class wishes to support index-only scans, except when the - compress method is omitted. + compress method is omitted. The optional tenth method + options is needed if the operator class provides + the user-specified parameters. @@ -939,6 +941,63 @@ my_fetch(PG_FUNCTION_ARGS) + + + options + + + Allows defintion of user-visible parameters that controls operator + class behavior. + + + + The SQL declaration of the function must look like this: + + +CREATE OR REPLACE FUNCTION my_options(internal) +RETURNS void +AS 'MODULE_PATHNAME' +LANGUAGE C STRICT; + + + + + The function has given pointer to local_relopts + struct, which needs to be filled with set of operator class + specific option. The options could be accessible from each support + function using PG_HAS_OPCLASS_OPTIONS() and + PG_GET_OPCLASS_OPTIONS() macros. + + + + The matching code in the C module could then follow this skeleton: + + +PG_FUNCTION_INFO_V1(my_options); + +Datum +my_options(PG_FUNCTION_ARGS) +{ + local_relopts *relopts = (local_relopts *) PG_GETARG_POINTER(0); + + init_local_reloptions(relopts, sizeof(MyOptionsStruct)); + add_local_int_reloption(relopts, "my_param", "my parameter name", + MY_PARAM_DEFAULT, MY_PARAM_MIN, MY_PARAM_MAX, + offsetof(MyOptionsStruct, my_param)); + + PG_RETURN_VOID(); +} + + + + + Since the representation of the key in GiST is + flexible, it may depends on user-specified parameters. For instace, + the length of key signature may be such parameter. See + gtsvector_options() for example. + + + diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml index 37f8d8760a3..af87f172a7c 100644 --- a/doc/src/sgml/indexam.sgml +++ b/doc/src/sgml/indexam.sgml @@ -96,6 +96,8 @@ typedef struct IndexAmRoutine uint16 amstrategies; /* total number of support functions that this AM uses */ uint16 amsupport; + /* opclass options support function number or 0 */ + uint16 amoptsprocnum; /* does AM support ORDER BY indexed column's value? */ bool amcanorder; /* does AM support ORDER BY result of an operator on indexed column? */ diff --git a/doc/src/sgml/spgist.sgml b/doc/src/sgml/spgist.sgml index edf4a67e526..272d2b998e5 100644 --- a/doc/src/sgml/spgist.sgml +++ b/doc/src/sgml/spgist.sgml @@ -858,7 +858,7 @@ typedef struct spgLeafConsistentOut - The optional user-defined method is: + The optional user-defined method are: @@ -875,6 +875,39 @@ typedef struct spgLeafConsistentOut + + options + + + Defines set of user-visible parameters that controls operator class + behavior. + + + + The SQL declaration of the function must look like this: + + +CREATE OR REPLACE FUNCTION my_options(internal) +RETURNS void +AS 'MODULE_PATHNAME' +LANGUAGE C STRICT; + + + + + The function has given pointer to local_relopts + struct, which needs to be filled with set of operator class + specific option. The options could be accessible from each support + function using PG_HAS_OPCLASS_OPTIONS() and + PG_GET_OPCLASS_OPTIONS() macros. + + + + Since the representation of the key in SP-GiST is + flexible, it may depends on user-specified parameters. + + + diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml index 14c1701c9b5..0e4587a81b9 100644 --- a/doc/src/sgml/xindex.sgml +++ b/doc/src/sgml/xindex.sgml @@ -409,6 +409,13 @@ . + + Additionally, some opclasses allow user to set specific parameters, which + controls its behavior. Each builtin index access method have optional + options support function, which defines set of + opclass-specific parameters. + + B-Tree Support Functions @@ -450,6 +457,13 @@ 4 + + + Defines set of options that are specific for this operator class + (optional) + + 5 +
@@ -485,6 +499,13 @@ 2 + + + Defines set of options that are specific for this operator class + (optional) + + 3 + @@ -560,6 +581,14 @@ index-only scans (optional) 9 + + options + + Defines set of options that are specific for this operator class + (optional) + + 10 + @@ -611,6 +640,14 @@ query qualifier 5 + + options + + Defines set of options that are specific for this operator class + (optional) + + 6 + @@ -680,6 +717,14 @@ 6 + + options + + Defines set of options that are specific for this operator class + (optional) + + 7 + @@ -730,6 +775,14 @@ 4 + + options + + Defines set of options that are specific for this operator class + (optional) + + 5 +