Skip to content

Commit ed0097e

Browse files
tglsfdctglsfdc
committed
Add SQL-accessible functions for inspecting index AM properties.
Per discussion, we should provide such functions to replace the lost ability to discover AM properties by inspecting pg_am (cf commit 65c5fcd). The added functionality is also meant to displace any code that was looking directly at pg_index.indoption, since we'd rather not believe that the bit meanings in that field are part of any client API contract. As future-proofing, define the SQL API to not assume that properties that are currently AM-wide or index-wide will remain so unless they logically must be; instead, expose them only when inquiring about a specific index or even specific index column. Also provide the ability for an index AM to override the behavior. In passing, document pg_am.amtype, overlooked in commit 473b932. Andrew Gierth, with kibitzing by me and others Discussion: <87mvl5on7n.fsf@news-spur.riddles.org.uk>
1 parent 4997878 commit ed0097e

File tree

28 files changed

+1146
-18
lines changed

28 files changed

+1146
-18
lines changed

‎contrib/bloom/blutils.c‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,7 @@ blhandler(PG_FUNCTION_ARGS)
129129
amroutine->amcanreturn = NULL;
130130
amroutine->amcostestimate = blcostestimate;
131131
amroutine->amoptions = bloptions;
132+
amroutine->amproperty = NULL;
132133
amroutine->amvalidate = blvalidate;
133134
amroutine->ambeginscan = blbeginscan;
134135
amroutine->amrescan = blrescan;

‎doc/src/sgml/catalogs.sgml‎

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -529,10 +529,11 @@
529529
</indexterm>
530530

531531
<para>
532-
The catalog <structname>pg_am</structname> stores information about index
533-
access methods. There is one row for each index access method supported by
534-
the system. The requirements for index access methods are discussed in
535-
detail in <xref linkend="indexam">.
532+
The catalog <structname>pg_am</structname> stores information about
533+
relation access methods. There is one row for each access method supported
534+
by the system.
535+
Currently, only indexes have access methods. The requirements for index
536+
access methods are discussed in detail in <xref linkend="indexam">.
536537
</para>
537538

538539
<table>
@@ -573,10 +574,30 @@
573574
</entry>
574575
</row>
575576

577+
<row>
578+
<entry><structfield>amtype</structfield></entry>
579+
<entry><type>char</type></entry>
580+
<entry></entry>
581+
<entry>
582+
Currently always <literal>i</literal> to indicate an index access
583+
method; other values may be allowed in future
584+
</entry>
585+
</row>
576586
</tbody>
577587
</tgroup>
578588
</table>
579589

590+
<note>
591+
<para>
592+
Before <productname>PostgreSQL</> 9.6, <structname>pg_am</structname>
593+
contained many additional columns representing properties of index access
594+
methods. That data is now only directly visible at the C code level.
595+
However, <function>pg_index_column_has_property()</function> and related
596+
functions have been added to allow SQL queries to inspect index access
597+
method properties; see <xref linkend="functions-info-catalog-table">.
598+
</para>
599+
</note>
600+
580601
</sect1>
581602

582603

‎doc/src/sgml/func.sgml‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16289,6 +16289,18 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
1628916289
<primary>pg_get_viewdef</primary>
1629016290
</indexterm>
1629116291

16292+
<indexterm>
16293+
<primary>pg_index_column_has_property</primary>
16294+
</indexterm>
16295+
16296+
<indexterm>
16297+
<primary>pg_index_has_property</primary>
16298+
</indexterm>
16299+
16300+
<indexterm>
16301+
<primary>pg_indexam_has_property</primary>
16302+
</indexterm>
16303+
1629216304
<indexterm>
1629316305
<primary>pg_options_to_table</primary>
1629416306
</indexterm>
@@ -16476,6 +16488,21 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
1647616488
materialized view; lines with fields are wrapped to specified
1647716489
number of columns, pretty-printing is implied</entry>
1647816490
</row>
16491+
<row>
16492+
<entry><literal><function>pg_index_column_has_property(<parameter>index_oid</parameter>, <parameter>column_no</>, <parameter>prop_name</>)</function></literal></entry>
16493+
<entry><type>boolean</type></entry>
16494+
<entry>test whether an index column has a specified property</entry>
16495+
</row>
16496+
<row>
16497+
<entry><literal><function>pg_index_has_property(<parameter>index_oid</parameter>, <parameter>prop_name</>)</function></literal></entry>
16498+
<entry><type>boolean</type></entry>
16499+
<entry>test whether an index has a specified property</entry>
16500+
</row>
16501+
<row>
16502+
<entry><literal><function>pg_indexam_has_property(<parameter>am_oid</parameter>, <parameter>prop_name</>)</function></literal></entry>
16503+
<entry><type>boolean</type></entry>
16504+
<entry>test whether an index access method has a specified property</entry>
16505+
</row>
1647916506
<row>
1648016507
<entry><literal><function>pg_options_to_table(<parameter>reloptions</parameter>)</function></literal></entry>
1648116508
<entry><type>setof record</type></entry>
@@ -16619,6 +16646,144 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
1661916646
its OID.
1662016647
</para>
1662116648

16649+
<para>
16650+
<function>pg_index_column_has_property</function>,
16651+
<function>pg_index_has_property</function>, and
16652+
<function>pg_indexam_has_property</function> return whether the
16653+
specified index column, index, or index access method possesses the named
16654+
property. <literal>NULL</literal> is returned if the property name is not
16655+
known or does not apply to the particular object, or if the OID or column
16656+
number does not identify a valid object. Refer to
16657+
<xref linkend="functions-info-index-column-props"> for column properties,
16658+
<xref linkend="functions-info-index-props"> for index properties, and
16659+
<xref linkend="functions-info-indexam-props"> for access method properties.
16660+
(Note that extension access methods can define additional property names
16661+
for their indexes.)
16662+
</para>
16663+
16664+
<table id="functions-info-index-column-props">
16665+
<title>Index Column Properties</title>
16666+
<tgroup cols="2">
16667+
<thead>
16668+
<row><entry>Name</entry><entry>Description</entry></row>
16669+
</thead>
16670+
<tbody>
16671+
<row>
16672+
<entry><literal>asc</literal></entry>
16673+
<entry>Does the column sort in ascending order on a forward scan?
16674+
</entry>
16675+
</row>
16676+
<row>
16677+
<entry><literal>desc</literal></entry>
16678+
<entry>Does the column sort in descending order on a forward scan?
16679+
</entry>
16680+
</row>
16681+
<row>
16682+
<entry><literal>nulls_first</literal></entry>
16683+
<entry>Does the column sort with nulls first on a forward scan?
16684+
</entry>
16685+
</row>
16686+
<row>
16687+
<entry><literal>nulls_last</literal></entry>
16688+
<entry>Does the column sort with nulls last on a forward scan?
16689+
</entry>
16690+
</row>
16691+
<row>
16692+
<entry><literal>orderable</literal></entry>
16693+
<entry>Does the column possess any defined sort ordering?
16694+
</entry>
16695+
</row>
16696+
<row>
16697+
<entry><literal>distance_orderable</literal></entry>
16698+
<entry>Can the column be scanned in order by a <quote>distance</>
16699+
operator, for example <literal>ORDER BY col &lt;-&gt; constant</> ?
16700+
</entry>
16701+
</row>
16702+
<row>
16703+
<entry><literal>returnable</literal></entry>
16704+
<entry>Can the column value be returned by an index-only scan?
16705+
</entry>
16706+
</row>
16707+
<row>
16708+
<entry><literal>search_array</literal></entry>
16709+
<entry>Does the column natively support <literal>col = ANY(array)</>
16710+
searches?
16711+
</entry>
16712+
</row>
16713+
<row>
16714+
<entry><literal>search_nulls</literal></entry>
16715+
<entry>Does the column support <literal>IS NULL</> and
16716+
<literal>IS NOT NULL</> searches?
16717+
</entry>
16718+
</row>
16719+
</tbody>
16720+
</tgroup>
16721+
</table>
16722+
16723+
<table id="functions-info-index-props">
16724+
<title>Index Properties</title>
16725+
<tgroup cols="2">
16726+
<thead>
16727+
<row><entry>Name</entry><entry>Description</entry></row>
16728+
</thead>
16729+
<tbody>
16730+
<row>
16731+
<entry><literal>clusterable</literal></entry>
16732+
<entry>Can the index be used in a <literal>CLUSTER</> command?
16733+
</entry>
16734+
</row>
16735+
<row>
16736+
<entry><literal>index_scan</literal></entry>
16737+
<entry>Does the index support plain (non-bitmap) scans?
16738+
</entry>
16739+
</row>
16740+
<row>
16741+
<entry><literal>bitmap_scan</literal></entry>
16742+
<entry>Does the index support bitmap scans?
16743+
</entry>
16744+
</row>
16745+
<row>
16746+
<entry><literal>backward_scan</literal></entry>
16747+
<entry>Can the index be scanned backwards?
16748+
</entry>
16749+
</row>
16750+
</tbody>
16751+
</tgroup>
16752+
</table>
16753+
16754+
<table id="functions-info-indexam-props">
16755+
<title>Index Access Method Properties</title>
16756+
<tgroup cols="2">
16757+
<thead>
16758+
<row><entry>Name</entry><entry>Description</entry></row>
16759+
</thead>
16760+
<tbody>
16761+
<row>
16762+
<entry><literal>can_order</literal></entry>
16763+
<entry>Does the access method support <literal>ASC</>,
16764+
<literal>DESC</> and related keywords in
16765+
<literal>CREATE INDEX</>?
16766+
</entry>
16767+
</row>
16768+
<row>
16769+
<entry><literal>can_unique</literal></entry>
16770+
<entry>Does the access method support unique indexes?
16771+
</entry>
16772+
</row>
16773+
<row>
16774+
<entry><literal>can_multi_col</literal></entry>
16775+
<entry>Does the access method support indexes with multiple columns?
16776+
</entry>
16777+
</row>
16778+
<row>
16779+
<entry><literal>can_exclude</literal></entry>
16780+
<entry>Does the access method support exclusion constraints?
16781+
</entry>
16782+
</row>
16783+
</tbody>
16784+
</tgroup>
16785+
</table>
16786+
1662216787
<para>
1662316788
<function>pg_options_to_table</function> returns the set of storage
1662416789
option name/value pairs

‎doc/src/sgml/indexam.sgml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,7 @@ typedef struct IndexAmRoutine
129129
amcanreturn_function amcanreturn; /* can be NULL */
130130
amcostestimate_function amcostestimate;
131131
amoptions_function amoptions;
132+
amproperty_function amproperty; /* can be NULL */
132133
amvalidate_function amvalidate;
133134
ambeginscan_function ambeginscan;
134135
amrescan_function amrescan;
@@ -407,6 +408,55 @@ amoptions (ArrayType *reloptions,
407408
<para>
408409
<programlisting>
409410
bool
411+
amproperty (Oid index_oid, int attno,
412+
IndexAMProperty prop, const char *propname,
413+
bool *res, bool *isnull);
414+
</programlisting>
415+
The <function>amproperty</> method allows index access methods to override
416+
the default behavior of <function>pg_index_column_has_property</function>
417+
and related functions.
418+
If the access method does not have any special behavior for index property
419+
inquiries, the <structfield>amproperty</> field in
420+
its <structname>IndexAmRoutine</> struct can be set to NULL.
421+
Otherwise, the <function>amproperty</> method will be called with
422+
<parameter>index_oid</> and <parameter>attno</> both zero for
423+
<function>pg_indexam_has_property</function> calls,
424+
or with <parameter>index_oid</> valid and <parameter>attno</> zero for
425+
<function>pg_index_has_property</function> calls,
426+
or with <parameter>index_oid</> valid and <parameter>attno</> greater than
427+
zero for <function>pg_index_column_has_property</function> calls.
428+
<parameter>prop</> is an enum value identifying the property being tested,
429+
while <parameter>propname</> is the original property name string.
430+
If the core code does not recognize the property name
431+
then <parameter>prop</> is <literal>AMPROP_UNKNOWN</>.
432+
Access methods can define custom property names by
433+
checking <parameter>propname</> for a match (use <function>pg_strcasecmp</>
434+
to match, for consistency with the core code); for names known to the core
435+
code, it's better to inspect <parameter>prop</>.
436+
If the <structfield>amproperty</> method returns <literal>true</> then
437+
it has determined the property test result: it must set <literal>*res</>
438+
to the boolean value to return, or set <literal>*isnull</>
439+
to <literal>true</> to return a NULL. (Both of the referenced variables
440+
are initialized to <literal>false</> before the call.)
441+
If the <structfield>amproperty</> method returns <literal>false</> then
442+
the core code will proceed with its normal logic for determining the
443+
property test result.
444+
</para>
445+
446+
<para>
447+
Access methods that support ordering operators should
448+
implement <literal>AMPROP_DISTANCE_ORDERABLE</> property testing, as the
449+
core code does not know how to do that and will return NULL. It may
450+
also be advantageous to implement <literal>AMPROP_RETURNABLE</> testing,
451+
if that can be done more cheaply than by opening the index and calling
452+
<structfield>amcanreturn</>, which is the core code's default behavior.
453+
The default behavior should be satisfactory for all other standard
454+
properties.
455+
</para>
456+
457+
<para>
458+
<programlisting>
459+
bool
410460
amvalidate (Oid opclassoid);
411461
</programlisting>
412462
Validate the catalog entries for the specified operator class, so far as

‎src/backend/access/brin/brin.c‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,7 @@ brinhandler(PG_FUNCTION_ARGS)
102102
amroutine->amcanreturn = NULL;
103103
amroutine->amcostestimate = brincostestimate;
104104
amroutine->amoptions = brinoptions;
105+
amroutine->amproperty = NULL;
105106
amroutine->amvalidate = brinvalidate;
106107
amroutine->ambeginscan = brinbeginscan;
107108
amroutine->amrescan = brinrescan;

‎src/backend/access/gin/ginutil.c‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ ginhandler(PG_FUNCTION_ARGS)
5757
amroutine->amcanreturn = NULL;
5858
amroutine->amcostestimate = gincostestimate;
5959
amroutine->amoptions = ginoptions;
60+
amroutine->amproperty = NULL;
6061
amroutine->amvalidate = ginvalidate;
6162
amroutine->ambeginscan = ginbeginscan;
6263
amroutine->amrescan = ginrescan;

‎src/backend/access/gist/gist.c‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ gisthandler(PG_FUNCTION_ARGS)
7979
amroutine->amcanreturn = gistcanreturn;
8080
amroutine->amcostestimate = gistcostestimate;
8181
amroutine->amoptions = gistoptions;
82+
amroutine->amproperty = gistproperty;
8283
amroutine->amvalidate = gistvalidate;
8384
amroutine->ambeginscan = gistbeginscan;
8485
amroutine->amrescan = gistrescan;

0 commit comments

Comments
 (0)