Skip to content

Commit 15cb2bd

Browse files
akorotkovakorotkov
committed
Add documentation for opclass options
911e702 added opclass options and adjusted documentation for each particular affected opclass. However, documentation for extendability was not adjusted. This commit adjusts documentation for interfaces of index AMs and opclasses. Discussion: https://postgr.es/m/CAH2-WzmQnW6%2Bz5F9AW%2BSz%2BzEcEvXofTwh_A9J3%3D_WA-FBP0wYg%40mail.gmail.com Author: Alexander Korotkov Reported-by: Peter Geoghegan Reviewed-by: Peter Geoghegan
1 parent d28ab91 commit 15cb2bd

File tree

7 files changed

+336
-4
lines changed

7 files changed

+336
-4
lines changed

‎doc/src/sgml/brin.sgml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -562,6 +562,36 @@ typedef struct BrinOpcInfo
562562
</varlistentry>
563563
</variablelist>
564564

565+
Optionally, an operator class for <acronym>BRIN</acronym> can supply the
566+
following method:
567+
568+
<variablelist>
569+
<varlistentry>
570+
<term><function>void options(local_relopts *relopts)</function></term>
571+
<listitem>
572+
<para>
573+
Defines set of user-visible parameters that control operator class
574+
behavior.
575+
</para>
576+
577+
<para>
578+
The <function>options</function> function has given pointer to
579+
<replaceable>local_relopts</replaceable> struct, which needs to be
580+
filled with a set of operator class specific options. The options
581+
can be accessed from other support functions using
582+
<literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
583+
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
584+
</para>
585+
586+
<para>
587+
Since both key extraction for indexed value and representation of the
588+
key in <acronym>GIN</acronym> are flexible, it may depends on
589+
user-specified parameters.
590+
</para>
591+
</listitem>
592+
</varlistentry>
593+
</variablelist>
594+
565595
The core distribution includes support for two types of operator classes:
566596
minmax and inclusion. Operator class definitions using them are shipped for
567597
in-core data types as appropriate. Additional operator classes can be

‎doc/src/sgml/btree.sgml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -550,6 +550,39 @@ equalimage(<replaceable>opcintype</replaceable> <type>oid</type>) returns bool
550550
</para>
551551
</listitem>
552552
</varlistentry>
553+
<varlistentry>
554+
<term><function>options</function></term>
555+
<listitem>
556+
<para>
557+
Optionally, a B-tree operator family may provide
558+
<function>options</function> (<quote>operator class specific
559+
options</quote>) support functions, registered under support
560+
function number 5. These functions define set of user-visible
561+
parameters that control operator class behavior.
562+
</para>
563+
<para>
564+
An <function>options</function> support function must have the
565+
signature
566+
<synopsis>
567+
options(<replaceable>relopts</replaceable> <type>local_relopts *</type>) returns void
568+
</synopsis>
569+
The function has given pointer to <replaceable>local_relopts</replaceable>
570+
struct, which needs to be filled with a set of operator class
571+
specific options. The options can be accessed from other support
572+
functions using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
573+
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
574+
</para>
575+
<para>
576+
Currently, no B-Tree operator class has <function>options</function>
577+
support function. B-tree doesn't allow flexible representation of keys
578+
like GiST, SP-GiST, GIN and BRIN do. So, <function>options</function>
579+
probably doesn't have much usage in current shape of B-tree index
580+
access method. Nevertheless, this support function was added to B-tree
581+
for uniformity, and probably it will found its usage during further
582+
evolution of B-tree in <productname>PostgreSQL</productname>.
583+
</para>
584+
</listitem>
585+
</varlistentry>
553586
</variablelist>
554587

555588
</sect1>

‎doc/src/sgml/gin.sgml‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -380,7 +380,7 @@
380380

381381
<para>
382382
Optionally, an operator class for <acronym>GIN</acronym> can supply the
383-
following method:
383+
following methods:
384384

385385
<variablelist>
386386
<varlistentry>
@@ -402,6 +402,30 @@
402402
</para>
403403
</listitem>
404404
</varlistentry>
405+
<varlistentry>
406+
<term><function>void options(local_relopts *relopts)</function></term>
407+
<listitem>
408+
<para>
409+
Defines set of user-visible parameters that control operator class
410+
behavior.
411+
</para>
412+
413+
<para>
414+
The <function>options</function> function has given pointer to
415+
<replaceable>local_relopts</replaceable> struct, which needs to be
416+
filled with s set of operator class specific options. The options
417+
can be accessed from other support functions using
418+
<literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
419+
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
420+
</para>
421+
422+
<para>
423+
Since both key extraction for indexed value and representation of the
424+
key in <acronym>GIN</acronym> are flexible, it may depends on
425+
user-specified parameters.
426+
</para>
427+
</listitem>
428+
</varlistentry>
405429
</variablelist>
406430
</para>
407431

‎doc/src/sgml/gist.sgml‎

Lines changed: 159 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -269,7 +269,7 @@ CREATE INDEX ON my_table USING GIST (my_inet_column inet_ops);
269269

270270
<para>
271271
There are five methods that an index operator class for
272-
<acronym>GiST</acronym> must provide, and four that are optional.
272+
<acronym>GiST</acronym> must provide, and five that are optional.
273273
Correctness of the index is ensured
274274
by proper implementation of the <function>same</function>, <function>consistent</function>
275275
and <function>union</function> methods, while efficiency (size and speed) of the
@@ -287,7 +287,9 @@ CREATE INDEX ON my_table USING GIST (my_inet_column inet_ops);
287287
if the operator class wishes to support ordered scans (nearest-neighbor
288288
searches). The optional ninth method <function>fetch</function> is needed if the
289289
operator class wishes to support index-only scans, except when the
290-
<function>compress</function> method is omitted.
290+
<function>compress</function> method is omitted. The optional tenth method
291+
<function>options</function> is needed if the operator class provides
292+
the user-specified parameters.
291293
</para>
292294

293295
<variablelist>
@@ -939,6 +941,161 @@ my_fetch(PG_FUNCTION_ARGS)
939941

940942
</listitem>
941943
</varlistentry>
944+
945+
<varlistentry>
946+
<term><function>options</function></term>
947+
<listitem>
948+
<para>
949+
Allows defintion of user-visible parameters that control operator
950+
class behavior.
951+
</para>
952+
953+
<para>
954+
The <acronym>SQL</acronym> declaration of the function must look like this:
955+
956+
<programlisting>
957+
CREATE OR REPLACE FUNCTION my_options(internal)
958+
RETURNS void
959+
AS 'MODULE_PATHNAME'
960+
LANGUAGE C STRICT;
961+
</programlisting>
962+
</para>
963+
964+
<para>
965+
The function has given pointer to <replaceable>local_relopts</replaceable>
966+
struct, which needs to be filled with a set of operator class
967+
specific options. The options can be accessed from other support
968+
functions using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
969+
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
970+
</para>
971+
972+
<para>
973+
The sample implementation of my_option() and parameters usage
974+
in the another support function are given below:
975+
976+
<programlisting>
977+
typedef enum MyEnumType
978+
{
979+
MY_ENUM_ON,
980+
MY_ENUM_OFF,
981+
MY_ENUM_AUTO
982+
} MyEnumType;
983+
984+
typedef struct
985+
{
986+
int32 vl_len_; /* varlena header (do not touch directly!) */
987+
int int_param; /* integer parameter */
988+
double real_param; /* real parameter */
989+
MyEnumType enum_param; /* enum parameter */
990+
int str_param; /* string parameter */
991+
} MyOptionsStruct;
992+
993+
/* String representations for enum values */
994+
static relopt_enum_elt_def myEnumValues[] =
995+
{
996+
{"on", MY_ENUM_ON},
997+
{"off", MY_ENUM_OFF},
998+
{"auto", MY_ENUM_AUTO},
999+
{(const char *) NULL} /* list terminator */
1000+
};
1001+
1002+
static char *str_param_default = "default";
1003+
1004+
/*
1005+
* Sample validatior: checks that string is not longer than 8 bytes.
1006+
*/
1007+
static void
1008+
validate_my_string_relopt(const char *value)
1009+
{
1010+
if (strlen(value) > 8)
1011+
ereport(ERROR,
1012+
(errcode(ERRCODE_INVALID_PARAMETER_VALUE),
1013+
errmsg("str_param must be at most 8 bytes")));
1014+
}
1015+
1016+
/*
1017+
* Sample filler: switches characters to lower case.
1018+
*/
1019+
static Size
1020+
fill_my_string_relopt(const char *value, void *ptr)
1021+
{
1022+
char *tmp = str_tolower(value, strlen(value), DEFAULT_COLLATION_OID);
1023+
int len = strlen(tmp);
1024+
1025+
if (ptr)
1026+
strcpy((char *) ptr, tmp);
1027+
1028+
pfree(tmp);
1029+
return len + 1;
1030+
}
1031+
1032+
PG_FUNCTION_INFO_V1(my_options);
1033+
1034+
Datum
1035+
my_options(PG_FUNCTION_ARGS)
1036+
{
1037+
local_relopts *relopts = (local_relopts *) PG_GETARG_POINTER(0);
1038+
1039+
init_local_reloptions(relopts, sizeof(MyOptionsStruct));
1040+
add_local_int_reloption(relopts, "int_param", "integer parameter",
1041+
100, 0, 1000000,
1042+
offsetof(MyOptionsStruct, int_param));
1043+
add_local_real_reloption(relopts, "real_param", "real parameter",
1044+
1.0, 0.0, 1000000.0,
1045+
offsetof(MyOptionsStruct, real_param));
1046+
add_local_enum_reloption(relopts, "enum_param", "enum parameter",
1047+
myEnumValues, MY_ENUM_ON,
1048+
"Valid values are: \"on\", \"off\" and \"auto\".",
1049+
offsetof(MyOptionsStruct, enum_param));
1050+
add_local_string_reloption(relopts, "str_param", "string parameter",
1051+
str_param_default,
1052+
&amp;validate_my_string_relopt,
1053+
&amp;fill_my_string_relopt,
1054+
offsetof(MyOptionsStruct, str_param));
1055+
1056+
PG_RETURN_VOID();
1057+
}
1058+
1059+
PG_FUNCTION_INFO_V1(my_compress);
1060+
1061+
Datum
1062+
my_compress(PG_FUNCTION_ARGS)
1063+
{
1064+
int int_param = 100;
1065+
double real_param = 1.0;
1066+
MyEnumType enum_param = MY_ENUM_ON;
1067+
char *str_param = str_param_default;
1068+
1069+
/*
1070+
* Normally, when opclass contains 'options' method, then options are always
1071+
* passed to support functions. However, if you add 'options' method to
1072+
* existing opclass, previously defined indexes have no options, so the
1073+
* check is required.
1074+
*/
1075+
if (PG_HAS_OPCLASS_OPTIONS())
1076+
{
1077+
MyOptionsStruct *options = (MyOptionsStruct *) PG_GET_OPCLASS_OPTIONS();
1078+
1079+
int_param = options->int_param;
1080+
real_param = options->real_param;
1081+
enum_param = options->enum_param;
1082+
str_param = GET_STRING_RELOPTION(options, str_param);
1083+
}
1084+
1085+
/* the rest implementation of support function */
1086+
}
1087+
1088+
</programlisting>
1089+
</para>
1090+
1091+
<para>
1092+
Since the representation of the key in <acronym>GiST</acronym> is
1093+
flexible, it may depends on user-specified parameters. For instace,
1094+
the length of key signature may be such parameter. See
1095+
<literal>gtsvector_options()</literal> for example.
1096+
</para>
1097+
</listitem>
1098+
</varlistentry>
9421099
</variablelist>
9431100

9441101
<para>

‎doc/src/sgml/indexam.sgml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,8 @@ typedef struct IndexAmRoutine
9696
uint16 amstrategies;
9797
/* total number of support functions that this AM uses */
9898
uint16 amsupport;
99+
/* opclass options support function number or 0 */
100+
uint16 amoptsprocnum;
99101
/* does AM support ORDER BY indexed column's value? */
100102
bool amcanorder;
101103
/* does AM support ORDER BY result of an operator on indexed column? */

‎doc/src/sgml/spgist.sgml‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -858,7 +858,7 @@ typedef struct spgLeafConsistentOut
858858
</variablelist>
859859

860860
<para>
861-
The optional user-defined method is:
861+
The optional user-defined method are:
862862
</para>
863863

864864
<variablelist>
@@ -875,6 +875,39 @@ typedef struct spgLeafConsistentOut
875875
</para>
876876
</listitem>
877877
</varlistentry>
878+
<varlistentry>
879+
<term><function>options</function></term>
880+
<listitem>
881+
<para>
882+
Defines set of user-visible parameters that control operator class
883+
behavior.
884+
</para>
885+
886+
<para>
887+
The <acronym>SQL</acronym> declaration of the function must look like this:
888+
889+
<programlisting>
890+
CREATE OR REPLACE FUNCTION my_options(internal)
891+
RETURNS void
892+
AS 'MODULE_PATHNAME'
893+
LANGUAGE C STRICT;
894+
</programlisting>
895+
</para>
896+
897+
<para>
898+
The function has given pointer to <replaceable>local_relopts</replaceable>
899+
struct, which needs to be filled with a set of operator class
900+
specific options. The options can be accessed from other support
901+
functions using <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
902+
<literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
903+
</para>
904+
905+
<para>
906+
Since the representation of the key in <acronym>SP-GiST</acronym> is
907+
flexible, it may depends on user-specified parameters.
908+
</para>
909+
</listitem>
910+
</varlistentry>
878911
</variablelist>
879912

880913
<para>

0 commit comments

Comments
 (0)