Correct documentation of CREATE OPERATOR.

2 files changed, 84 insertions, 88 deletions

diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml
index 02961e38a1c..eda81ffa895 100644
--- a/doc/src/sgml/ref/create_operator.sgml
+++ b/doc/src/sgml/ref/create_operator.sgml
@@ -15,7 +15,7 @@
   </refnamediv>
  <REFSYNOPSISDIV>
   <REFSYNOPSISDIVINFO>
-   <DATE>1998-09-09</DATE>
+   <DATE>1999-04-14</DATE>
   </REFSYNOPSISDIVINFO>
   <SYNOPSIS>
 CREATE OPERATOR <replaceable>name</replaceable> (
@@ -25,15 +25,16 @@ CREATE OPERATOR <replaceable>name</replaceable> (
      [, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ]
      [, NEGATOR    = <replaceable class="parameter">neg_op</replaceable> ]
      [, RESTRICT   = <replaceable class="parameter">res_proc</replaceable> ]
-     [, HASHES ]
      [, 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>
   
   <REFSECT2 ID="R2-SQL-CREATEOPERATOR-1">
    <REFSECT2INFO>
-    <DATE>1998-09-09</DATE>
+    <DATE>1999-04-14</DATE>
    </REFSECT2INFO>
    <TITLE>
     Inputs
@@ -89,7 +90,7 @@ omitted for a left-unary operator.
 	 </TERM>
 	 <LISTITEM>
 	  <PARA>
-The corresponding commutative operator.
+The commutator for this operator.
 	  </PARA>
 	 </LISTITEM>
 	</VARLISTENTRY>
@@ -99,7 +100,7 @@ The corresponding commutative operator.
 	 </TERM>
 	 <LISTITEM>
 	  <PARA>
-The corresponding negation operator.
+The negator of this operator.
 	  </PARA>
 	 </LISTITEM>
 	</VARLISTENTRY>
@@ -109,7 +110,17 @@ The corresponding negation operator.
 	 </TERM>
 	 <LISTITEM>
 	  <PARA>
-The corresponding restriction operator.
+The restriction selectivity estimator function for this operator.
+	  </PARA>
+	 </LISTITEM>
+	</VARLISTENTRY>
+	<VARLISTENTRY>
+	 <TERM>
+	  <replaceable class="parameter">join_proc</replaceable>
+	 </TERM>
+	 <LISTITEM>
+	  <PARA>
+The join selectivity estimator function for this operator.
 	  </PARA>
 	 </LISTITEM>
 	</VARLISTENTRY>
@@ -119,27 +130,27 @@ HASHES
 	 </TERM>
 	 <LISTITEM>
 	  <PARA>
-This operator can support a hash-join algorithm.
+Indicates this operator can support a hash-join algorithm.
 	  </PARA>
 	 </LISTITEM>
 	</VARLISTENTRY>
 	<VARLISTENTRY>
 	 <TERM>
-	  <replaceable class="parameter">join_proc</replaceable>
+	  <replaceable class="parameter">left_sort_op</replaceable>
 	 </TERM>
 	 <LISTITEM>
 	  <PARA>
-Procedure supporting table joins.
+Operator that sorts the left-hand data type of this operator.
 	  </PARA>
 	 </LISTITEM>
 	</VARLISTENTRY>
 	<VARLISTENTRY>
 	 <TERM>
-	  <replaceable class="parameter">sort_op</replaceable>
+	  <replaceable class="parameter">right_sort_op</replaceable>
 	 </TERM>
 	 <LISTITEM>
 	  <PARA>
-Operator to use for sorting.
+Operator that sorts the right-hand data type of this operator.
 	  </PARA>
 	 </LISTITEM>
 	</VARLISTENTRY>
@@ -149,7 +160,7 @@ Operator to use for sorting.
   
   <REFSECT2 ID="R2-SQL-CREATEOPERATOR-2">
    <REFSECT2INFO>
-    <DATE>1998-09-09</DATE>
+    <DATE>1999-04-14</DATE>
    </REFSECT2INFO>
    <TITLE>
     Outputs
@@ -173,7 +184,7 @@ Operator to use for sorting.
  
  <REFSECT1 ID="R1-SQL-CREATEOPERATOR-1">
   <REFSECT1INFO>
-   <DATE>1998-09-09</DATE>
+   <DATE>1999-04-14</DATE>
   </REFSECT1INFO>
   <TITLE>
    Description
@@ -252,9 +263,9 @@ Operator to use for sorting.
    If  a  commutator  operator  name  is  supplied,  
    <productname>Postgres</productname>
    searches  for  it  in  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 (new) operator
-   as its commutator.  This applies to the negator, as  well.
+   does not yet have a commutator itself, then the commutator's
+   entry is updated to have the newly created operator as its
+   commutator.  This applies to the negator, as well.
   </para>
   <para>
    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
    (as appropriate).  When the second  operator  is  defined,
    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>
-   The next two specifications are  present  to  support  the
+   The next three specifications are  present  to  support  the
    query  optimizer in performing joins.  
    <productname>Postgres</productname> can always
    evaluate a join (i.e., processing a clause with two  tuple
    variables separated by an operator that returns a boolean)
    by iterative substitution [WONG76].  
    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
-   strategy  is  applicable.   
-   For example, a hash-join
-   algorithm is usable for a clause of the form:
-   <programlisting>
-    MYBOXES.description === MYBOXES2.description
-   </programlisting>
-   but not for a clause of the form:
-   <programlisting>
-    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>
+   strategy  is  applicable.   The current hash-join algorithm
+   is only correct for operators that represent equality tests;
+   furthermore, equality of the datatype must mean bitwise equality
+   of the representation of the type.  (For example, a datatype that
+   contains unused bits that don't matter for equality tests could
+   not be hashjoined.)
+   The HASHES flag indicates to the query optimizer that a hash join
+   may safely be used with this operator.</para>
   <para>
    Similarly, the two sort operators indicate  to  the  query
    optimizer whether merge-sort is a usable join strategy and
-   what operators should be used  to  sort  the  two  operand
-   classes.   For  the  ===  clause above, the optimizer must
-   sort both relations using the operator, &lt;&lt;&lt;.  On the other
-   hand, merge-sort is not usable with the clause:
-   <programlisting>
-    MYBOXES.description &lt;&lt;&lt; MYBOXES2.description
-   </programlisting>
+   which operators should be used  to  sort  the  two  operand
+   classes.  Sort operators should only be provided for an equality
+   operator, and they should refer to less-than operators for the
+   left and right side data types respectively.
   </para>
   <para>
    If  other join strategies are found to be practical,
@@ -355,7 +359,7 @@ Operator to use for sorting.
   
   <REFSECT2 ID="R2-SQL-CREATEOPERATOR-3">
    <REFSECT2INFO>
-    <DATE>1998-09-09</DATE>
+    <DATE>1999-04-14</DATE>
    </REFSECT2INFO>
    <TITLE>
     Notes
@@ -385,9 +389,10 @@ Operator to use for sorting.
    COMMUTATOR = ===,
    NEGATOR = !==,
    RESTRICT = area_restriction_procedure,
+   JOIN = area_join_procedure,
    HASHES,
-   JOIN = area-join-procedure,
-   SORT = <<<, <<<)
+   SORT1 = <<<,
+   SORT2 = <<<)
   </ProgramListing>  
  </REFSECT1>
  
@@ -401,7 +406,7 @@ Operator to use for sorting.
   
   <REFSECT2 ID="R2-SQL-CREATEOPERATOR-4">
    <REFSECT2INFO>
-    <DATE>1998-09-09</DATE>
+    <DATE>1999-04-14</DATE>
    </REFSECT2INFO>
    <TITLE>
     SQL92
diff --git a/src/man/create_operator.l b/src/man/create_operator.l
index cc3af636171..7fca24eb083 100644
--- a/src/man/create_operator.l
+++ b/src/man/create_operator.l
@@ -1,6 +1,6 @@
 .\" This is -*-nroff-*-
 .\" 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
 .SH NAME
 create operator - define a new user operator
@@ -13,9 +13,10 @@ create operator - define a new user operator
 	 [\fB, commutator =\fR com_op ]
 	 [\fB, negator =\fR neg_op ]
 	 [\fB, restrict =\fR res_proc ]
-	 [\fB, hashes\fR]
 	 [\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"arg is ("
 .\" type [
@@ -90,8 +91,7 @@ and must have one or two arguments.
 The commutator operator is present so that Postgres can reverse the order
 of the operands if it wishes.  For example, the operator
 area-less-than, >>>, would have a commutator operator,
-area-greater-than, <<<.  Suppose that an operator, area-equal, ===,
-exists, as well as an area not equal, !==.  Hence, the query optimizer
+area-greater-than, <<<.  Hence, the query optimizer
 could freely convert:
 .nf
 
@@ -109,6 +109,8 @@ MYBOXES.description <<< "0,0,1,1"::box
 This allows the execution code to always use the latter representation
 and simplifies the query optimizer somewhat.
 .PP
+Suppose that an operator, area-equal, ===,
+exists, as well as an area not equal, !==.
 The negator operator allows the query optimizer to convert
 .nf
 
@@ -125,53 +127,41 @@ MYBOXES.description !== "0,0,1,1"::box
 .fi
 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
-itself, then the commutator's entry is updated to have the current
-(new) operator as its commutator.  This applies to the negator, as
-well.
+itself, then the commutator's entry is updated to have the newly created
+operator as its commutator.  This applies to the negator, as well.
 .PP
 This is to allow the definition of two operators that are the
 commutators or the negators of each other.  The first operator should
 be defined without a commutator or negator (as appropriate).  When the
 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
-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.,
 processing a clause with two tuple variables separated by an operator
 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
-strategy is applicable.  For example, a hash-join algorithm is usable
-for a clause of the form:
-.nf
-
-.ce 1
-MYBOXES.description === MYBOXES2.description
-
-.fi
-but not for a clause of the form:
-.nf
-
-.ce 1
-MYBOXES.description <<< MYBOXES2.description.
-
-.fi
+strategy is applicable.
+The current hash-join algorithm
+is only correct for operators that represent equality tests;
+furthermore, equality of the datatype must mean bitwise equality
+of the representation of the type.  (For example, a datatype that
+contains unused bits that don't matter for equality tests could
+not be hashjoined.)
 The
 .BR hashes
-flag gives the needed information to the query optimizer concerning
-whether a hash join strategy is usable for the operator in question.
+flag indicates to the query optimizer that a hash join may safely be
+used with this operator.
 .PP
 Similarly, the two sort operators indicate to the query optimizer
-whether merge-sort is a usable join strategy and what operators should
-be used to sort the two operand classes.  For the === clause above,
-the optimizer must sort both relations using the operator, <<<.  On
-the other hand, merge-sort is not usable with the clause:
-.nf
-
-.ce 1
-MYBOXES.description <<< MYBOXES2.description
-
-.fi
+whether merge-sort is a usable join strategy and which operators should
+be used to sort the two operand classes.
+Sort operators should only be provided for an equality
+operator, and they should refer to less-than operators for the
+left and right side data types respectively.
+.PP
 If other join strategies are found to be practical, Postgres will change
 the optimizer and run-time system to use them and will require
 additional specification when an operator is defined.  Fortunately,
@@ -236,9 +226,10 @@ create operator === (
 	commutator = ===,
 	negator = !==,
 	restrict = area_restriction_procedure,
+	join = area_join_procedure,
 	hashes,
-	join = area-join-procedure,
-	sort = <<<, <<<)
+	sort1 = <<<,
+	sort2 = <<<)
 .\"	arg is (box, box)
 .fi
 .SH "SEE ALSO"
@@ -248,7 +239,7 @@ drop_operator(l).
 Operator names cannot be composed of alphabetic characters in 
 Postgres.
 .PP
-If an operator is defined before its commuting operator has been defined
-(a case specifically warned against above), a dummy operator with invalid
-fields will be placed in the system catalogs.  This may interfere with
-the definition of later operators.
+If an operator is defined before its commuting operator has been defined,
+a dummy entry for the commutator (with invalid oprproc field) will be placed
+in the system catalogs.  This entry will be overridden when the commutator
+is eventually defined.