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

Correct documentation of CREATE OPERATOR.

Browse Source
This commit is contained in:
Tom Lane
1999-04-15 00:09:00 +00:00
parent eaffc61675
commit 630ed05063
2 changed files with 92 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
doc/src/sgml/ref/create_operator.sgml
View File

@ -15,7 +15,7 @@
</refnamediv> </refnamediv>
<REFSYNOPSISDIV> <REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO> <REFSYNOPSISDIVINFO>
<DATE>1998-09-09</DATE> <DATE>1999-04-14</DATE>
</REFSYNOPSISDIVINFO> </REFSYNOPSISDIVINFO>
<SYNOPSIS> <SYNOPSIS>
CREATE OPERATOR <replaceable>name</replaceable> ( CREATE OPERATOR <replaceable>name</replaceable> (
@ -25,15 +25,16 @@ CREATE OPERATOR <replaceable>name</replaceable> (
[, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ]
[, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
[, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ]
[, HASHES ]
[, JOIN = <replaceable class="parameter">join_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
[, SORT = <replaceable class="parameter">sort_op</replaceable> [, ...] ] [, HASHES ]
[, SORT1 = <replaceable class="parameter">left_sort_op</replaceable> ]
[, SORT2 = <replaceable class="parameter">right_sort_op</replaceable> ]
) )
</SYNOPSIS> </SYNOPSIS>
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-1"> <REFSECT2 ID="R2-SQL-CREATEOPERATOR-1">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-09</DATE> <DATE>1999-04-14</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Inputs Inputs
@ -89,7 +90,7 @@ omitted for a left-unary operator.
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The corresponding commutative operator. The commutator for this operator.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -99,7 +100,7 @@ The corresponding commutative operator.
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The corresponding negation operator. The negator of this operator.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -109,17 +110,7 @@ The corresponding negation operator.
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
The corresponding restriction operator. The restriction selectivity estimator function for this operator.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
HASHES
</TERM>
<LISTITEM>
<PARA>
This operator can support a hash-join algorithm.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -129,17 +120,37 @@ This operator can support a hash-join algorithm.
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Procedure supporting table joins. The join selectivity estimator function for this operator.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
<replaceable class="parameter">sort_op</replaceable> HASHES
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Operator to use for sorting. Indicates this operator can support a hash-join algorithm.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">left_sort_op</replaceable>
</TERM>
<LISTITEM>
<PARA>
Operator that sorts the left-hand data type of this operator.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<replaceable class="parameter">right_sort_op</replaceable>
</TERM>
<LISTITEM>
<PARA>
Operator that sorts the right-hand data type of this operator.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -149,7 +160,7 @@ Operator to use for sorting.
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-2"> <REFSECT2 ID="R2-SQL-CREATEOPERATOR-2">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-09</DATE> <DATE>1999-04-14</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Outputs Outputs
@ -173,7 +184,7 @@ Operator to use for sorting.
<REFSECT1 ID="R1-SQL-CREATEOPERATOR-1"> <REFSECT1 ID="R1-SQL-CREATEOPERATOR-1">
<REFSECT1INFO> <REFSECT1INFO>
<DATE>1998-09-09</DATE> <DATE>1999-04-14</DATE>
</REFSECT1INFO> </REFSECT1INFO>
<TITLE> <TITLE>
Description Description
@ -252,9 +263,9 @@ Operator to use for sorting.
If a commutator operator name is supplied, If a commutator operator name is supplied,
<productname>Postgres</productname> <productname>Postgres</productname>
searches for it in the catalog. If it is found and it searches for it in the catalog. If it is found and it
does not yet have a commutator itself, then the commutator's does not yet have a commutator itself, then the commutator's
entry is updated to have the current (new) operator entry is updated to have the newly created operator as its
as its commutator. This applies to the negator, as well. commutator. This applies to the negator, as well.
</para> </para>
<para> <para>
This is to allow the definition of two operators that are This is to allow the definition of two operators that are
@ -262,41 +273,34 @@ Operator to use for sorting.
operator should be defined without a commutator or negator operator should be defined without a commutator or negator
(as appropriate). When the second operator is defined, (as appropriate). When the second operator is defined,
name the first as the commutator or negator. The first name the first as the commutator or negator. The first
will be updated as a side effect. will be updated as a side effect. (As of Postgres 6.5,
it also works to just have both operators refer to each other.)
</para> </para>
<para> <para>
The next two specifications are present to support the The next three specifications are present to support the
query optimizer in performing joins. query optimizer in performing joins.
<productname>Postgres</productname> can always <productname>Postgres</productname> can always
evaluate a join (i.e., processing a clause with two tuple evaluate a join (i.e., processing a clause with two tuple
variables separated by an operator that returns a boolean) variables separated by an operator that returns a boolean)
by iterative substitution [WONG76]. by iterative substitution [WONG76].
In addition, <productname>Postgres</productname> In addition, <productname>Postgres</productname>
is planning on implementing a hash-join algorithm along can use a hash-join algorithm along
the lines of [SHAP86]; however, it must know whether this the lines of [SHAP86]; however, it must know whether this
strategy is applicable. strategy is applicable. The current hash-join algorithm
For example, a hash-join is only correct for operators that represent equality tests;
algorithm is usable for a clause of the form: furthermore, equality of the datatype must mean bitwise equality
<programlisting> of the representation of the type. (For example, a datatype that
MYBOXES.description === MYBOXES2.description contains unused bits that don't matter for equality tests could
</programlisting> not be hashjoined.)
but not for a clause of the form: The HASHES flag indicates to the query optimizer that a hash join
<programlisting> may safely be used with this operator.</para>
MYBOXES.description &lt;&lt;&lt; MYBOXES2.description.
</programlisting>
The HASHES flag gives the needed information to the query
optimizer concerning whether a hash join strategy is
usable for the operator in question.</para>
<para> <para>
Similarly, the two sort operators indicate to the query Similarly, the two sort operators indicate to the query
optimizer whether merge-sort is a usable join strategy and optimizer whether merge-sort is a usable join strategy and
what operators should be used to sort the two operand which operators should be used to sort the two operand
classes. For the === clause above, the optimizer must classes. Sort operators should only be provided for an equality
sort both relations using the operator, &lt;&lt;&lt;. On the other operator, and they should refer to less-than operators for the
hand, merge-sort is not usable with the clause: left and right side data types respectively.
<programlisting>
MYBOXES.description &lt;&lt;&lt; MYBOXES2.description
</programlisting>
</para> </para>
<para> <para>
If other join strategies are found to be practical, If other join strategies are found to be practical,
@ -355,7 +359,7 @@ Operator to use for sorting.
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-3"> <REFSECT2 ID="R2-SQL-CREATEOPERATOR-3">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-09</DATE> <DATE>1999-04-14</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
Notes Notes
@ -385,9 +389,10 @@ Operator to use for sorting.
COMMUTATOR = ===, COMMUTATOR = ===,
NEGATOR = !==, NEGATOR = !==,
RESTRICT = area_restriction_procedure, RESTRICT = area_restriction_procedure,
JOIN = area_join_procedure,
HASHES, HASHES,
JOIN = area-join-procedure, SORT1 = <<<,
SORT = <<<, <<<) SORT2 = <<<)
</ProgramListing> </ProgramListing>
</REFSECT1> </REFSECT1>
@ -401,7 +406,7 @@ Operator to use for sorting.
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-4"> <REFSECT2 ID="R2-SQL-CREATEOPERATOR-4">
<REFSECT2INFO> <REFSECT2INFO>
<DATE>1998-09-09</DATE> <DATE>1999-04-14</DATE>
</REFSECT2INFO> </REFSECT2INFO>
<TITLE> <TITLE>
SQL92 SQL92

79
src/man/create_operator.l
View File

@ -1,6 +1,6 @@
.\" This is -*-nroff-*- .\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here.... .\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_operator.l,v 1.7 1998/07/25 00:17:30 momjian Exp $ .\" $Header: /cvsroot/pgsql/src/man/Attic/create_operator.l,v 1.8 1999/04/15 00:09:00 tgl Exp $
.TH "CREATE OPERATOR" SQL 11/05/95 PostgreSQL PostgreSQL .TH "CREATE OPERATOR" SQL 11/05/95 PostgreSQL PostgreSQL
.SH NAME .SH NAME
create operator - define a new user operator create operator - define a new user operator
@ -13,9 +13,10 @@ create operator - define a new user operator
[\fB, commutator =\fR com_op ] [\fB, commutator =\fR com_op ]
[\fB, negator =\fR neg_op ] [\fB, negator =\fR neg_op ]
[\fB, restrict =\fR res_proc ] [\fB, restrict =\fR res_proc ]
[\fB, hashes\fR]
[\fB, join =\fR join_proc ] [\fB, join =\fR join_proc ]
[\fB, sort =\fR sor_op1 {\fB,\fR sor_op2 } ] [\fB, hashes\fR]
[\fB, sort1 =\fR left_sort_op ]
[\fB, sort2 =\fR right_sort_op ]
\fB)\fR \fB)\fR
.\" \fB"arg is (" .\" \fB"arg is ("
.\" type [ .\" type [
@ -90,8 +91,7 @@ and must have one or two arguments.
The commutator operator is present so that Postgres can reverse the order The commutator operator is present so that Postgres can reverse the order
of the operands if it wishes. For example, the operator of the operands if it wishes. For example, the operator
area-less-than, >>>, would have a commutator operator, area-less-than, >>>, would have a commutator operator,
area-greater-than, <<<. Suppose that an operator, area-equal, ===, area-greater-than, <<<. Hence, the query optimizer
exists, as well as an area not equal, !==. Hence, the query optimizer
could freely convert: could freely convert:
.nf .nf
@ -109,6 +109,8 @@ MYBOXES.description <<< "0,0,1,1"::box
This allows the execution code to always use the latter representation This allows the execution code to always use the latter representation
and simplifies the query optimizer somewhat. and simplifies the query optimizer somewhat.
.PP .PP
Suppose that an operator, area-equal, ===,
exists, as well as an area not equal, !==.
The negator operator allows the query optimizer to convert The negator operator allows the query optimizer to convert
.nf .nf
@ -125,53 +127,41 @@ MYBOXES.description !== "0,0,1,1"::box
.fi .fi
If a commutator operator name is supplied, Postgres searches for it in If a commutator operator name is supplied, Postgres searches for it in
the catalog. If it is found and it does not yet have a commutator the catalog. If it is found and it does not yet have a commutator
itself, then the commutator's entry is updated to have the current itself, then the commutator's entry is updated to have the newly created
(new) operator as its commutator. This applies to the negator, as operator as its commutator. This applies to the negator, as well.
well.
.PP .PP
This is to allow the definition of two operators that are the This is to allow the definition of two operators that are the
commutators or the negators of each other. The first operator should commutators or the negators of each other. The first operator should
be defined without a commutator or negator (as appropriate). When the be defined without a commutator or negator (as appropriate). When the
second operator is defined, name the first as the commutator or second operator is defined, name the first as the commutator or
negator. The first will be updated as a side effect. negator. The first will be updated as a side effect. (As of Postgres 6.5,
it also works to just have both operators refer to each other.)
.PP .PP
The next two specifications are present to support the query optimizer The next three specifications are present to support the query optimizer
in performing joins. Postgres can always evaluate a join (i.e., in performing joins. Postgres can always evaluate a join (i.e.,
processing a clause with two tuple variables separated by an operator processing a clause with two tuple variables separated by an operator
that returns a boolean) by iterative substitution [WONG76]. In that returns a boolean) by iterative substitution [WONG76]. In
addition, Postgres is planning on implementing a hash-join algorithm addition, Postgres can use a hash-join algorithm
along the lines of [SHAP86]; however, it must know whether this along the lines of [SHAP86]; however, it must know whether this
strategy is applicable. For example, a hash-join algorithm is usable strategy is applicable.
for a clause of the form: The current hash-join algorithm
.nf is only correct for operators that represent equality tests;
furthermore, equality of the datatype must mean bitwise equality
.ce 1 of the representation of the type. (For example, a datatype that
MYBOXES.description === MYBOXES2.description contains unused bits that don't matter for equality tests could
not be hashjoined.)
.fi
but not for a clause of the form:
.nf
.ce 1
MYBOXES.description <<< MYBOXES2.description.
.fi
The The
.BR hashes .BR hashes
flag gives the needed information to the query optimizer concerning flag indicates to the query optimizer that a hash join may safely be
whether a hash join strategy is usable for the operator in question. used with this operator.
.PP .PP
Similarly, the two sort operators indicate to the query optimizer Similarly, the two sort operators indicate to the query optimizer
whether merge-sort is a usable join strategy and what operators should whether merge-sort is a usable join strategy and which operators should
be used to sort the two operand classes. For the === clause above, be used to sort the two operand classes.
the optimizer must sort both relations using the operator, <<<. On Sort operators should only be provided for an equality
the other hand, merge-sort is not usable with the clause: operator, and they should refer to less-than operators for the
.nf left and right side data types respectively.
.PP
.ce 1
MYBOXES.description <<< MYBOXES2.description
.fi
If other join strategies are found to be practical, Postgres will change If other join strategies are found to be practical, Postgres will change
the optimizer and run-time system to use them and will require the optimizer and run-time system to use them and will require
additional specification when an operator is defined. Fortunately, additional specification when an operator is defined. Fortunately,
@ -236,9 +226,10 @@ create operator === (
commutator = ===, commutator = ===,
negator = !==, negator = !==,
restrict = area_restriction_procedure, restrict = area_restriction_procedure,
join = area_join_procedure,
hashes, hashes,
join = area-join-procedure, sort1 = <<<,
sort = <<<, <<<) sort2 = <<<)
.\" arg is (box, box) .\" arg is (box, box)
.fi .fi
.SH "SEE ALSO" .SH "SEE ALSO"
@ -248,7 +239,7 @@ drop_operator(l).
Operator names cannot be composed of alphabetic characters in Operator names cannot be composed of alphabetic characters in
Postgres. Postgres.
.PP .PP
If an operator is defined before its commuting operator has been defined If an operator is defined before its commuting operator has been defined,
(a case specifically warned against above), a dummy operator with invalid a dummy entry for the commutator (with invalid oprproc field) will be placed
fields will be placed in the system catalogs. This may interfere with in the system catalogs. This entry will be overridden when the commutator
the definition of later operators. is eventually defined.