Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 630ed05

Browse files
tglsfdctglsfdc
committed
Correct documentation of CREATE OPERATOR.
1 parent eaffc61 commit 630ed05

File tree

2 files changed

+84
-88
lines changed

2 files changed

+84
-88
lines changed

‎doc/src/sgml/ref/create_operator.sgml

Lines changed: 49 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
</refnamediv>
1616
<REFSYNOPSISDIV>
1717
<REFSYNOPSISDIVINFO>
18-
<DATE>1998-09-09</DATE>
18+
<DATE>1999-04-14</DATE>
1919
</REFSYNOPSISDIVINFO>
2020
<SYNOPSIS>
2121
CREATE OPERATOR <replaceable>name</replaceable> (
@@ -25,15 +25,16 @@ CREATE OPERATOR <replaceable>name</replaceable> (
2525
[, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ]
2626
[, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
2727
[, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ]
28-
[, HASHES ]
2928
[, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
30-
[, SORT = <replaceable class="parameter">sort_op</replaceable> [, ...] ]
29+
[, HASHES ]
30+
[, SORT1 = <replaceable class="parameter">left_sort_op</replaceable> ]
31+
[, SORT2 = <replaceable class="parameter">right_sort_op</replaceable> ]
3132
)
3233
</SYNOPSIS>
3334

3435
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-1">
3536
<REFSECT2INFO>
36-
<DATE>1998-09-09</DATE>
37+
<DATE>1999-04-14</DATE>
3738
</REFSECT2INFO>
3839
<TITLE>
3940
Inputs
@@ -89,7 +90,7 @@ omitted for a left-unary operator.
8990
</TERM>
9091
<LISTITEM>
9192
<PARA>
92-
The corresponding commutative operator.
93+
The commutator for this operator.
9394
</PARA>
9495
</LISTITEM>
9596
</VARLISTENTRY>
@@ -99,7 +100,7 @@ The corresponding commutative operator.
99100
</TERM>
100101
<LISTITEM>
101102
<PARA>
102-
The corresponding negation operator.
103+
The negator of this operator.
103104
</PARA>
104105
</LISTITEM>
105106
</VARLISTENTRY>
@@ -109,7 +110,17 @@ The corresponding negation operator.
109110
</TERM>
110111
<LISTITEM>
111112
<PARA>
112-
The corresponding restriction operator.
113+
The restriction selectivity estimator function for this operator.
114+
</PARA>
115+
</LISTITEM>
116+
</VARLISTENTRY>
117+
<VARLISTENTRY>
118+
<TERM>
119+
<replaceable class="parameter">join_proc</replaceable>
120+
</TERM>
121+
<LISTITEM>
122+
<PARA>
123+
The join selectivity estimator function for this operator.
113124
</PARA>
114125
</LISTITEM>
115126
</VARLISTENTRY>
@@ -119,27 +130,27 @@ HASHES
119130
</TERM>
120131
<LISTITEM>
121132
<PARA>
122-
This operator can support a hash-join algorithm.
133+
Indicates this operator can support a hash-join algorithm.
123134
</PARA>
124135
</LISTITEM>
125136
</VARLISTENTRY>
126137
<VARLISTENTRY>
127138
<TERM>
128-
<replaceable class="parameter">join_proc</replaceable>
139+
<replaceable class="parameter">left_sort_op</replaceable>
129140
</TERM>
130141
<LISTITEM>
131142
<PARA>
132-
Procedure supporting table joins.
143+
Operator that sorts the left-hand data type of this operator.
133144
</PARA>
134145
</LISTITEM>
135146
</VARLISTENTRY>
136147
<VARLISTENTRY>
137148
<TERM>
138-
<replaceable class="parameter">sort_op</replaceable>
149+
<replaceable class="parameter">right_sort_op</replaceable>
139150
</TERM>
140151
<LISTITEM>
141152
<PARA>
142-
Operator to use for sorting.
153+
Operator that sorts the right-hand data type of this operator.
143154
</PARA>
144155
</LISTITEM>
145156
</VARLISTENTRY>
@@ -149,7 +160,7 @@ Operator to use for sorting.
149160

150161
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-2">
151162
<REFSECT2INFO>
152-
<DATE>1998-09-09</DATE>
163+
<DATE>1999-04-14</DATE>
153164
</REFSECT2INFO>
154165
<TITLE>
155166
Outputs
@@ -173,7 +184,7 @@ Operator to use for sorting.
173184

174185
<REFSECT1 ID="R1-SQL-CREATEOPERATOR-1">
175186
<REFSECT1INFO>
176-
<DATE>1998-09-09</DATE>
187+
<DATE>1999-04-14</DATE>
177188
</REFSECT1INFO>
178189
<TITLE>
179190
Description
@@ -252,51 +263,44 @@ Operator to use for sorting.
252263
If a commutator operator name is supplied,
253264
<productname>Postgres</productname>
254265
searches for it in the catalog. If it is found and it
255-
does not yet have a commutator itself, then the commutator's
256-
entry is updated to have the current (new) operator
257-
as its commutator. This applies to the negator, as well.
266+
does not yet have a commutator itself, then the commutator's
267+
entry is updated to have the newly created operator as its
268+
commutator. This applies to the negator, as well.
258269
</para>
259270
<para>
260271
This is to allow the definition of two operators that are
261272
the commutators or the negators of each other. The first
262273
operator should be defined without a commutator or negator
263274
(as appropriate). When the second operator is defined,
264275
name the first as the commutator or negator. The first
265-
will be updated as a side effect.
276+
will be updated as a side effect. (As of Postgres 6.5,
277+
it also works to just have both operators refer to each other.)
266278
</para>
267279
<para>
268-
The next two specifications are present to support the
280+
The next three specifications are present to support the
269281
query optimizer in performing joins.
270282
<productname>Postgres</productname> can always
271283
evaluate a join (i.e., processing a clause with two tuple
272284
variables separated by an operator that returns a boolean)
273285
by iterative substitution [WONG76].
274286
In addition, <productname>Postgres</productname>
275-
is planning on implementing a hash-join algorithm along
287+
can use a hash-join algorithm along
276288
the lines of [SHAP86]; however, it must know whether this
277-
strategy is applicable.
278-
For example, a hash-join
279-
algorithm is usable for a clause of the form:
280-
<programlisting>
281-
MYBOXES.description === MYBOXES2.description
282-
</programlisting>
283-
but not for a clause of the form:
284-
<programlisting>
285-
MYBOXES.description &lt;&lt;&lt; MYBOXES2.description.
286-
</programlisting>
287-
The HASHES flag gives the needed information to the query
288-
optimizer concerning whether a hash join strategy is
289-
usable for the operator in question.</para>
289+
strategy is applicable. The current hash-join algorithm
290+
is only correct for operators that represent equality tests;
291+
furthermore, equality of the datatype must mean bitwise equality
292+
of the representation of the type. (For example, a datatype that
293+
contains unused bits that don't matter for equality tests could
294+
not be hashjoined.)
295+
The HASHES flag indicates to the query optimizer that a hash join
296+
may safely be used with this operator.</para>
290297
<para>
291298
Similarly, the two sort operators indicate to the query
292299
optimizer whether merge-sort is a usable join strategy and
293-
what operators should be used to sort the two operand
294-
classes. For the === clause above, the optimizer must
295-
sort both relations using the operator, &lt;&lt;&lt;. On the other
296-
hand, merge-sort is not usable with the clause:
297-
<programlisting>
298-
MYBOXES.description &lt;&lt;&lt; MYBOXES2.description
299-
</programlisting>
300+
which operators should be used to sort the two operand
301+
classes. Sort operators should only be provided for an equality
302+
operator, and they should refer to less-than operators for the
303+
left and right side data types respectively.
300304
</para>
301305
<para>
302306
If other join strategies are found to be practical,
@@ -355,7 +359,7 @@ Operator to use for sorting.
355359

356360
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-3">
357361
<REFSECT2INFO>
358-
<DATE>1998-09-09</DATE>
362+
<DATE>1999-04-14</DATE>
359363
</REFSECT2INFO>
360364
<TITLE>
361365
Notes
@@ -385,9 +389,10 @@ Operator to use for sorting.
385389
COMMUTATOR = ===,
386390
NEGATOR = !==,
387391
RESTRICT = area_restriction_procedure,
392+
JOIN = area_join_procedure,
388393
HASHES,
389-
JOIN = area-join-procedure,
390-
SORT = <<<, <<<)
394+
SORT1 = <<<,
395+
SORT2 = <<<)
391396
</ProgramListing>
392397
</REFSECT1>
393398

@@ -401,7 +406,7 @@ Operator to use for sorting.
401406

402407
<REFSECT2 ID="R2-SQL-CREATEOPERATOR-4">
403408
<REFSECT2INFO>
404-
<DATE>1998-09-09</DATE>
409+
<DATE>1999-04-14</DATE>
405410
</REFSECT2INFO>
406411
<TITLE>
407412
SQL92

‎src/man/create_operator.l

Lines changed: 35 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.\" This is -*-nroff-*-
22
.\" XXX standard disclaimer belongs here....
3-
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_operator.l,v 1.7 1998/07/25 00:17:30 momjian Exp $
3+
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_operator.l,v 1.8 1999/04/15 00:09:00 tgl Exp $
44
.TH "CREATE OPERATOR" SQL 11/05/95 PostgreSQL PostgreSQL
55
.SH NAME
66
create operator - define a new user operator
@@ -13,9 +13,10 @@ create operator - define a new user operator
1313
[\fB, commutator =\fR com_op ]
1414
[\fB, negator =\fR neg_op ]
1515
[\fB, restrict =\fR res_proc ]
16-
[\fB, hashes\fR]
1716
[\fB, join =\fR join_proc ]
18-
[\fB, sort =\fR sor_op1 {\fB,\fR sor_op2 } ]
17+
[\fB, hashes\fR]
18+
[\fB, sort1 =\fR left_sort_op ]
19+
[\fB, sort2 =\fR right_sort_op ]
1920
\fB)\fR
2021
.\" \fB"arg is ("
2122
.\" type [
@@ -90,8 +91,7 @@ and must have one or two arguments.
9091
The commutator operator is present so that Postgres can reverse the order
9192
of the operands if it wishes. For example, the operator
9293
area-less-than, >>>, would have a commutator operator,
93-
area-greater-than, <<<. Suppose that an operator, area-equal, ===,
94-
exists, as well as an area not equal, !==. Hence, the query optimizer
94+
area-greater-than, <<<. Hence, the query optimizer
9595
could freely convert:
9696
.nf
9797

@@ -109,6 +109,8 @@ MYBOXES.description <<< "0,0,1,1"::box
109109
This allows the execution code to always use the latter representation
110110
and simplifies the query optimizer somewhat.
111111
.PP
112+
Suppose that an operator, area-equal, ===,
113+
exists, as well as an area not equal, !==.
112114
The negator operator allows the query optimizer to convert
113115
.nf
114116

@@ -125,53 +127,41 @@ MYBOXES.description !== "0,0,1,1"::box
125127
.fi
126128
If a commutator operator name is supplied, Postgres searches for it in
127129
the catalog. If it is found and it does not yet have a commutator
128-
itself, then the commutator's entry is updated to have the current
129-
(new) operator as its commutator. This applies to the negator, as
130-
well.
130+
itself, then the commutator's entry is updated to have the newly created
131+
operator as its commutator. This applies to the negator, as well.
131132
.PP
132133
This is to allow the definition of two operators that are the
133134
commutators or the negators of each other. The first operator should
134135
be defined without a commutator or negator (as appropriate). When the
135136
second operator is defined, name the first as the commutator or
136-
negator. The first will be updated as a side effect.
137+
negator. The first will be updated as a side effect. (As of Postgres 6.5,
138+
it also works to just have both operators refer to each other.)
137139
.PP
138-
The next two specifications are present to support the query optimizer
140+
The next three specifications are present to support the query optimizer
139141
in performing joins. Postgres can always evaluate a join (i.e.,
140142
processing a clause with two tuple variables separated by an operator
141143
that returns a boolean) by iterative substitution [WONG76]. In
142-
addition, Postgres is planning on implementing a hash-join algorithm
144+
addition, Postgres can use a hash-join algorithm
143145
along the lines of [SHAP86]; however, it must know whether this
144-
strategy is applicable. For example, a hash-join algorithm is usable
145-
for a clause of the form:
146-
.nf
147-
148-
.ce 1
149-
MYBOXES.description === MYBOXES2.description
150-
151-
.fi
152-
but not for a clause of the form:
153-
.nf
154-
155-
.ce 1
156-
MYBOXES.description <<< MYBOXES2.description.
157-
158-
.fi
146+
strategy is applicable.
147+
The current hash-join algorithm
148+
is only correct for operators that represent equality tests;
149+
furthermore, equality of the datatype must mean bitwise equality
150+
of the representation of the type. (For example, a datatype that
151+
contains unused bits that don't matter for equality tests could
152+
not be hashjoined.)
159153
The
160154
.BR hashes
161-
flag gives the needed information to the query optimizer concerning
162-
whether a hash join strategy is usable for the operator in question.
155+
flag indicates to the query optimizer that a hash join may safely be
156+
used with this operator.
163157
.PP
164158
Similarly, the two sort operators indicate to the query optimizer
165-
whether merge-sort is a usable join strategy and what operators should
166-
be used to sort the two operand classes. For the === clause above,
167-
the optimizer must sort both relations using the operator, <<<. On
168-
the other hand, merge-sort is not usable with the clause:
169-
.nf
170-
171-
.ce 1
172-
MYBOXES.description <<< MYBOXES2.description
173-
174-
.fi
159+
whether merge-sort is a usable join strategy and which operators should
160+
be used to sort the two operand classes.
161+
Sort operators should only be provided for an equality
162+
operator, and they should refer to less-than operators for the
163+
left and right side data types respectively.
164+
.PP
175165
If other join strategies are found to be practical, Postgres will change
176166
the optimizer and run-time system to use them and will require
177167
additional specification when an operator is defined. Fortunately,
@@ -236,9 +226,10 @@ create operator === (
236226
commutator = ===,
237227
negator = !==,
238228
restrict = area_restriction_procedure,
229+
join = area_join_procedure,
239230
hashes,
240-
join = area-join-procedure,
241-
sort = <<<, <<<)
231+
sort1 = <<<,
232+
sort2 = <<<)
242233
.\" arg is (box, box)
243234
.fi
244235
.SH "SEE ALSO"
@@ -248,7 +239,7 @@ drop_operator(l).
248239
Operator names cannot be composed of alphabetic characters in
249240
Postgres.
250241
.PP
251-
If an operator is defined before its commuting operator has been defined
252-
(a case specifically warned against above), a dummy operator with invalid
253-
fields will be placed in the system catalogs. This may interfere with
254-
the definition of later operators.
242+
If an operator is defined before its commuting operator has been defined,
243+
a dummy entry for the commutator (with invalid oprproc field) will be placed
244+
in the system catalogs. This entry will be overridden when the commutator
245+
is eventually defined.

0 commit comments

Comments
 (0)