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