database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-08 11:42:09 +03:00
Code Activity

Doc: Restructure B-Tree support routine docs.

Browse Source 
Use a top-level "variablelist", with one item per B-Tree support
function.  This structure matches the structure used by various
"Extensibility" sections in other documentation chapters for other index
access methods.

An explicit list makes it much clearer where each item begins and ends.
This wasn't really a problem before now, but an upcoming patch that adds
deduplication to nbtree will need to have its own new B-Tree support
function.  Ease the burden of translators by tidying up btree.sgml ahead
of committing the deduplication patch.
This commit is contained in:
Peter Geoghegan
2020-02-12 14:08:34 -08:00
parent 0973f5602c
commit caba0910af
1 changed files with 233 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files

278
doc/src/sgml/btree.sgml
View File

@ -207,48 +207,64 @@
<para> <para>
As shown in <xref linkend="xindex-btree-support-table"/>, btree defines As shown in <xref linkend="xindex-btree-support-table"/>, btree defines
one required and two optional support functions. one required and two optional support functions. The three
user-defined methods are:
</para> </para>
<variablelist>
<varlistentry>
<term><function>order</function></term>
<listitem>
<para> <para>
For each combination of data types that a btree operator family provides For each combination of data types that a btree operator family
comparison operators for, it must provide a comparison support function, provides comparison operators for, it must provide a comparison
registered in <structname>pg_amproc</structname> with support function support function, registered in
number 1 and <structname>pg_amproc</structname> with support function number 1
and
<structfield>amproclefttype</structfield>/<structfield>amprocrighttype</structfield> <structfield>amproclefttype</structfield>/<structfield>amprocrighttype</structfield>
equal to the left and right data types for the comparison (i.e., the equal to the left and right data types for the comparison (i.e.,
same data types that the matching operators are registered with the same data types that the matching operators are registered
in <structname>pg_amop</structname>). with in <structname>pg_amop</structname>). The comparison
The comparison function must take two non-null values function must take two non-null values
<replaceable>A</replaceable> and <replaceable>B</replaceable> and <replaceable>A</replaceable> and <replaceable>B</replaceable> and
return an <type>int32</type> value that return an <type>int32</type> value that is
is <literal>&lt;</literal> <literal>0</literal>, <literal>0</literal>, <literal>&lt;</literal> <literal>0</literal>,
or <literal>&gt;</literal> <literal>0</literal> <literal>0</literal>, or <literal>&gt;</literal>
when <replaceable>A</replaceable> <literal>&lt;</literal> <literal>0</literal> when <replaceable>A</replaceable>
<replaceable>B</replaceable>, <replaceable>A</replaceable> <literal>&lt;</literal> <replaceable>B</replaceable>,
<literal>=</literal> <replaceable>B</replaceable>, <replaceable>A</replaceable> <literal>=</literal>
or <replaceable>A</replaceable> <literal>&gt;</literal> <replaceable>B</replaceable>, or <replaceable>A</replaceable>
<replaceable>B</replaceable>, respectively. <literal>&gt;</literal> <replaceable>B</replaceable>,
A null result is disallowed: all values of the data type must be comparable. respectively. A null result is disallowed: all values of the
See <filename>src/backend/access/nbtree/nbtcompare.c</filename> for data type must be comparable. See
<filename>src/backend/access/nbtree/nbtcompare.c</filename> for
examples. examples.
</para> </para>
<para> <para>
If the compared values are of a collatable data type, the appropriate If the compared values are of a collatable data type, the
collation OID will be passed to the comparison support function, using appropriate collation OID will be passed to the comparison
the standard <function>PG_GET_COLLATION()</function> mechanism. support function, using the standard
<function>PG_GET_COLLATION()</function> mechanism.
</para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>sortsupport</function></term>
<listitem>
<para> <para>
Optionally, a btree operator family may provide <firstterm>sort Optionally, a btree operator family may provide <firstterm>sort
support</firstterm> function(s), registered under support function number support</firstterm> function(s), registered under support
2. These functions allow implementing comparisons for sorting purposes function number 2. These functions allow implementing
in a more efficient way than naively calling the comparison support comparisons for sorting purposes in a more efficient way than
function. The APIs involved in this are defined in naively calling the comparison support function. The APIs
involved in this are defined in
<filename>src/include/utils/sortsupport.h</filename>. <filename>src/include/utils/sortsupport.h</filename>.
</para> </para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>inrange</function></term>
<listitem>
<indexterm> <indexterm>
<primary>in_range support functions</primary> <primary>in_range support functions</primary>
</indexterm> </indexterm>
@ -257,21 +273,20 @@
<primary>support functions</primary> <primary>support functions</primary>
<secondary>in_range</secondary> <secondary>in_range</secondary>
</indexterm> </indexterm>
<para> <para>
Optionally, a btree operator family may Optionally, a btree operator family may provide
provide <firstterm>in_range</firstterm> support function(s), registered <firstterm>in_range</firstterm> support function(s), registered
under support function number 3. These are not used during btree index under support function number 3. These are not used during btree
operations; rather, they extend the semantics of the operator family so index operations; rather, they extend the semantics of the
that it can support window clauses containing operator family so that it can support window clauses containing
the <literal>RANGE</literal> <replaceable>offset</replaceable> the <literal>RANGE</literal> <replaceable>offset</replaceable>
<literal>PRECEDING</literal> <literal>PRECEDING</literal> and <literal>RANGE</literal>
and <literal>RANGE</literal> <replaceable>offset</replaceable> <replaceable>offset</replaceable> <literal>FOLLOWING</literal>
<literal>FOLLOWING</literal> frame bound types (see frame bound types (see <xref
<xref linkend="syntax-window-functions"/>). Fundamentally, the extra linkend="syntax-window-functions"/>). Fundamentally, the extra
information provided is how to add or subtract information provided is how to add or subtract an
an <replaceable>offset</replaceable> value in a way that is compatible <replaceable>offset</replaceable> value in a way that is
with the family's data ordering. compatible with the family's data ordering.
</para> </para>
<para> <para>
@ -280,153 +295,168 @@
in_range(<replaceable>val</replaceable> type1, <replaceable>base</replaceable> type1, <replaceable>offset</replaceable> type2, <replaceable>sub</replaceable> bool, <replaceable>less</replaceable> bool) in_range(<replaceable>val</replaceable> type1, <replaceable>base</replaceable> type1, <replaceable>offset</replaceable> type2, <replaceable>sub</replaceable> bool, <replaceable>less</replaceable> bool)
returns bool returns bool
</synopsis> </synopsis>
<replaceable>val</replaceable> and <replaceable>base</replaceable> must be <replaceable>val</replaceable> and
of the same type, which is one of the types supported by the operator <replaceable>base</replaceable> must be of the same type, which
family (i.e., a type for which it provides an ordering). is one of the types supported by the operator family (i.e., a
However, <replaceable>offset</replaceable> could be of a different type, type for which it provides an ordering). However,
which might be one otherwise unsupported by the family. An example is <replaceable>offset</replaceable> could be of a different type,
that the built-in <literal>time_ops</literal> family provides which might be one otherwise unsupported by the family. An
an <function>in_range</function> function that example is that the built-in <literal>time_ops</literal> family
has <replaceable>offset</replaceable> of type <type>interval</type>. provides an <function>in_range</function> function that has
A family can provide <function>in_range</function> functions for any of <replaceable>offset</replaceable> of type <type>interval</type>.
its supported types and one or more <replaceable>offset</replaceable> A family can provide <function>in_range</function> functions for
types. Each <function>in_range</function> function should be entered any of its supported types and one or more
in <structname>pg_amproc</structname> <replaceable>offset</replaceable> types. Each
with <structfield>amproclefttype</structfield> equal to <type>type1</type> <function>in_range</function> function should be entered in
and <structfield>amprocrighttype</structfield> equal to <type>type2</type>. <structname>pg_amproc</structname> with
<structfield>amproclefttype</structfield> equal to
<type>type1</type> and <structfield>amprocrighttype</structfield>
equal to <type>type2</type>.
</para> </para>
<para> <para>
The essential semantics of an <function>in_range</function> function The essential semantics of an <function>in_range</function>
depend on the two Boolean flag parameters. It should add or function depend on the two Boolean flag parameters. It should
subtract <replaceable>base</replaceable> add or subtract <replaceable>base</replaceable> and
and <replaceable>offset</replaceable>, then <replaceable>offset</replaceable>, then compare
compare <replaceable>val</replaceable> to the result, as follows: <replaceable>val</replaceable> to the result, as follows:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
if <literal>!</literal><replaceable>sub</replaceable> and if <literal>!</literal><replaceable>sub</replaceable> and
<literal>!</literal><replaceable>less</replaceable>, <literal>!</literal><replaceable>less</replaceable>, return
return <replaceable>val</replaceable> <literal>&gt;=</literal> <replaceable>val</replaceable> <literal>&gt;=</literal>
(<replaceable>base</replaceable> <literal>+</literal> (<replaceable>base</replaceable> <literal>+</literal>
<replaceable>offset</replaceable>) <replaceable>offset</replaceable>)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
if <literal>!</literal><replaceable>sub</replaceable> if <literal>!</literal><replaceable>sub</replaceable> and
and <replaceable>less</replaceable>, <replaceable>less</replaceable>, return
return <replaceable>val</replaceable> <literal>&lt;=</literal> <replaceable>val</replaceable> <literal>&lt;=</literal>
(<replaceable>base</replaceable> <literal>+</literal> (<replaceable>base</replaceable> <literal>+</literal>
<replaceable>offset</replaceable>) <replaceable>offset</replaceable>)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
if <replaceable>sub</replaceable> if <replaceable>sub</replaceable> and
and <literal>!</literal><replaceable>less</replaceable>, <literal>!</literal><replaceable>less</replaceable>, return
return <replaceable>val</replaceable> <literal>&gt;=</literal> <replaceable>val</replaceable> <literal>&gt;=</literal>
(<replaceable>base</replaceable> <literal>-</literal> (<replaceable>base</replaceable> <literal>-</literal>
<replaceable>offset</replaceable>) <replaceable>offset</replaceable>)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
if <replaceable>sub</replaceable> and <replaceable>less</replaceable>, if <replaceable>sub</replaceable> and
return <replaceable>val</replaceable> <literal>&lt;=</literal> <replaceable>less</replaceable>, return
<replaceable>val</replaceable> <literal>&lt;=</literal>
(<replaceable>base</replaceable> <literal>-</literal> (<replaceable>base</replaceable> <literal>-</literal>
<replaceable>offset</replaceable>) <replaceable>offset</replaceable>)
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
Before doing so, the function should check the sign Before doing so, the function should check the sign of
of <replaceable>offset</replaceable>: if it is less than zero, raise <replaceable>offset</replaceable>: if it is less than zero, raise
error <literal>ERRCODE_INVALID_PRECEDING_OR_FOLLOWING_SIZE</literal> (22013) error
with error text like <quote>invalid preceding or following size in window <literal>ERRCODE_INVALID_PRECEDING_OR_FOLLOWING_SIZE</literal>
function</quote>. (This is required by the SQL standard, although (22013) with error text like <quote>invalid preceding or
nonstandard operator families might perhaps choose to ignore this following size in window function</quote>. (This is required by
restriction, since there seems to be little semantic necessity for it.) the SQL standard, although nonstandard operator families might
This requirement is delegated to the <function>in_range</function> perhaps choose to ignore this restriction, since there seems to
function so that the core code needn't understand what <quote>less than be little semantic necessity for it.) This requirement is
delegated to the <function>in_range</function> function so that
the core code needn't understand what <quote>less than
zero</quote> means for a particular data type. zero</quote> means for a particular data type.
</para> </para>
<para> <para>
An additional expectation is that <function>in_range</function> functions An additional expectation is that <function>in_range</function>
should, if practical, avoid throwing an error functions should, if practical, avoid throwing an error if
if <replaceable>base</replaceable> <literal>+</literal> <replaceable>base</replaceable> <literal>+</literal>
<replaceable>offset</replaceable> <replaceable>offset</replaceable> or
or <replaceable>base</replaceable> <literal>-</literal> <replaceable>base</replaceable> <literal>-</literal>
<replaceable>offset</replaceable> would overflow. <replaceable>offset</replaceable> would overflow. The correct
The correct comparison result can be determined even if that value would comparison result can be determined even if that value would be
be out of the data type's range. Note that if the data type includes out of the data type's range. Note that if the data type
concepts such as <quote>infinity</quote> or <quote>NaN</quote>, extra care includes concepts such as <quote>infinity</quote> or
may be needed to ensure that <function>in_range</function>'s results agree <quote>NaN</quote>, extra care may be needed to ensure that
with the normal sort order of the operator family. <function>in_range</function>'s results agree with the normal
sort order of the operator family.
</para> </para>
<para> <para>
The results of the <function>in_range</function> function must be The results of the <function>in_range</function> function must be
consistent with the sort ordering imposed by the operator family. consistent with the sort ordering imposed by the operator family.
To be precise, given any fixed values of <replaceable>offset</replaceable> To be precise, given any fixed values of
and <replaceable>sub</replaceable>, then: <replaceable>offset</replaceable> and
<replaceable>sub</replaceable>, then:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
If <function>in_range</function> with <replaceable>less</replaceable> = If <function>in_range</function> with
true is true for some <replaceable>val1</replaceable> <replaceable>less</replaceable> = true is true for some
and <replaceable>base</replaceable>, it must be true for <replaceable>val1</replaceable> and
every <replaceable>val2</replaceable> <literal>&lt;=</literal> <replaceable>base</replaceable>, it must be true for every
<replaceable>val1</replaceable> with the <replaceable>val2</replaceable> <literal>&lt;=</literal>
same <replaceable>base</replaceable>. <replaceable>val1</replaceable> with the same
<replaceable>base</replaceable>.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
If <function>in_range</function> with <replaceable>less</replaceable> = If <function>in_range</function> with
true is false for some <replaceable>val1</replaceable> <replaceable>less</replaceable> = true is false for some
and <replaceable>base</replaceable>, it must be false for <replaceable>val1</replaceable> and
every <replaceable>val2</replaceable> <literal>&gt;=</literal> <replaceable>base</replaceable>, it must be false for every
<replaceable>val1</replaceable> with the <replaceable>val2</replaceable> <literal>&gt;=</literal>
same <replaceable>base</replaceable>. <replaceable>val1</replaceable> with the same
<replaceable>base</replaceable>.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
If <function>in_range</function> with <replaceable>less</replaceable> = If <function>in_range</function> with
true is true for some <replaceable>val</replaceable> <replaceable>less</replaceable> = true is true for some
and <replaceable>base1</replaceable>, it must be true for <replaceable>val</replaceable> and
every <replaceable>base2</replaceable> <literal>&gt;=</literal> <replaceable>base1</replaceable>, it must be true for every
<replaceable>base1</replaceable> with the <replaceable>base2</replaceable> <literal>&gt;=</literal>
same <replaceable>val</replaceable>. <replaceable>base1</replaceable> with the same
<replaceable>val</replaceable>.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
If <function>in_range</function> with <replaceable>less</replaceable> = If <function>in_range</function> with
true is false for some <replaceable>val</replaceable> <replaceable>less</replaceable> = true is false for some
and <replaceable>base1</replaceable>, it must be false for <replaceable>val</replaceable> and
every <replaceable>base2</replaceable> <literal>&lt;=</literal> <replaceable>base1</replaceable>, it must be false for every
<replaceable>base1</replaceable> with the <replaceable>base2</replaceable> <literal>&lt;=</literal>
same <replaceable>val</replaceable>. <replaceable>base1</replaceable> with the same
<replaceable>val</replaceable>.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
Analogous statements with inverted conditions hold Analogous statements with inverted conditions hold when
when <replaceable>less</replaceable> = false. <replaceable>less</replaceable> = false.
</para> </para>
<para> <para>
If the type being ordered (<type>type1</type>) is collatable, If the type being ordered (<type>type1</type>) is collatable, the
the appropriate collation OID will be passed to appropriate collation OID will be passed to the
the <function>in_range</function> function, using the standard <function>in_range</function> function, using the standard
PG_GET_COLLATION() mechanism. PG_GET_COLLATION() mechanism.
</para> </para>
<para> <para>
<function>in_range</function> functions need not handle NULL inputs, and <function>in_range</function> functions need not handle NULL
typically will be marked strict. inputs, and typically will be marked strict.
</para> </para>
</listitem>
</varlistentry>
</variablelist>
</sect1> </sect1>