From 421594798685c8681a56d2b98db0412dfb41acff Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sun, 17 Aug 2003 22:09:00 +0000
Subject: [PATCH] Update documentation to reflect the fact that ORDER BY, GROUP
BY, etc are now driven by the default btree opclass, rather than assuming
that particular operator names have the needed semantics.
---
doc/src/sgml/ref/create_operator.sgml | 12 ++---
doc/src/sgml/ref/select.sgml | 26 ++++++++---
doc/src/sgml/xindex.sgml | 63 +++++++++++++++++++++++++--
doc/src/sgml/xoper.sgml | 13 +-----
4 files changed, 82 insertions(+), 32 deletions(-)
diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml
index 2ac9d3f2edd..34933a37eff 100644
--- a/doc/src/sgml/ref/create_operator.sgml
+++ b/doc/src/sgml/ref/create_operator.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.35 2003/04/22 10:08:08 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.36 2003/08/17 22:09:00 tgl Exp $
PostgreSQL documentation
-->
@@ -43,17 +43,11 @@ CREATE OPERATOR <replaceable>name</replaceable> (
The operator name is a sequence of up to <symbol>NAMEDATALEN</>-1
(63 by default) characters from the following list:
<literallayout>
-+ - * / < > = ~ ! @ # % ^ & | ` ? $
++ - * / < > = ~ ! @ # % ^ & | ` ?
</literallayout>
There are a few restrictions on your choice of name:
<itemizedlist>
- <listitem>
- <para>
- <literal>$</literal> cannot be defined as a single-character operator,
- although it can be part of a multicharacter operator name.
- </para>
- </listitem>
<listitem>
<para>
<literal>--</literal> and <literal>/*</literal> cannot appear anywhere in an operator name,
@@ -66,7 +60,7 @@ CREATE OPERATOR <replaceable>name</replaceable> (
<literal>-</literal>,
unless the name also contains at least one of these characters:
<literallayout>
-~ ! @ # % ^ & | ` ? $
+~ ! @ # % ^ & | ` ?
</literallayout>
For example, <literal>@-</literal> is an allowed operator name,
but <literal>*-</literal> is not.
diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index f983b2a8213..04d2a36e5b3 100644
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.67 2003/05/04 02:23:16 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.68 2003/08/17 22:09:00 tgl Exp $
PostgreSQL documentation
-->
@@ -660,8 +660,11 @@ SELECT name FROM distributors ORDER BY code;
<literal>ORDER BY</> clause. If not specified, <literal>ASC</> is
assumed by default. Alternatively, a specific ordering operator
name may be specified in the <literal>USING</> clause.
- <literal>ASC</> is equivalent to <literal>USING <</> and
- <literal>DESC</> is equivalent to <literal>USING ></>.
+ <literal>ASC</> is usually equivalent to <literal>USING <</> and
+ <literal>DESC</> is usually equivalent to <literal>USING ></>.
+ (But the creator of a user-defined datatype can define exactly what the
+ default sort ordering is, and it might correspond to operators with other
+ names.)
</para>
<para>
@@ -671,7 +674,7 @@ SELECT name FROM distributors ORDER BY code;
</para>
<para>
- Data of character types is sorted according to the locale-specific
+ Character-string data is sorted according to the locale-specific
collation order that was established when the database cluster
was initialized.
</para>
@@ -1003,7 +1006,9 @@ SELECT distributors.* FROM distributors d, distributors distributors;
that he will actually get. To help detect this sort of mistake,
PostgreSQL will warn if the implicit-<literal>FROM</literal>
feature is used in a <command>SELECT</command> statement that also
- contains an explicit <literal>FROM</literal> clause.
+ contains an explicit <literal>FROM</literal> clause. Also, it is
+ possible to disable the implicit-<literal>FROM</literal> feature
+ by setting the <varname>ADD_MISSING_FROM</> parameter to false.
</para>
</refsect2>
@@ -1015,7 +1020,7 @@ SELECT distributors.* FROM distributors d, distributors distributors;
noise and can be omitted without affecting the meaning. The
<productname>PostgreSQL</productname> parser requires this key
word when renaming output columns because the type extensibility
- features lead to parsing ambiguities in this context.
+ features lead to parsing ambiguities without it.
<literal>AS</literal> is optional in <literal>FROM</literal>
items, however.
</para>
@@ -1025,7 +1030,7 @@ SELECT distributors.* FROM distributors d, distributors distributors;
<title>Namespace Available to <literal>GROUP BY</literal> and <literal>ORDER BY</literal></title>
<para>
- In the SQL standard, an <literal>ORDER BY</literal> clause may
+ In the SQL92 standard, an <literal>ORDER BY</literal> clause may
only use result column names or numbers, while a <literal>GROUP
BY</literal> clause may only use expressions based on input column
names. <productname>PostgreSQL</productname> extends each of
@@ -1036,6 +1041,13 @@ SELECT distributors.* FROM distributors d, distributors distributors;
expression will always be taken as input-column names, not as
result-column names.
</para>
+
+ <para>
+ SQL99 uses a slightly different definition which is not upward compatible
+ with SQL92. In most cases, however, <productname>PostgreSQL</productname>
+ will interpret an <literal>ORDER BY</literal> or <literal>GROUP
+ BY</literal> expression the same way SQL99 does.
+ </para>
</refsect2>
<refsect2>
diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml
index 6416183c95a..bd5d1fe78bf 100644
--- a/doc/src/sgml/xindex.sgml
+++ b/doc/src/sgml/xindex.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/xindex.sgml,v 1.30 2003/04/13 09:57:35 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/xindex.sgml,v 1.31 2003/08/17 22:09:00 tgl Exp $
-->
<sect1 id="xindex">
@@ -452,7 +452,7 @@ CREATE OPERATOR = (
</programlisting>
It is important to specify the restriction and join selectivity
functions, otherwise the optimizer will be unable to make effective
- use of the index. Note that there less-than, equal, and
+ use of the index. Note that the less-than, equal, and
greater-than cases should use different selectivity functions.
</para>
@@ -551,13 +551,68 @@ CREATE OPERATOR CLASS complex_abs_ops
</para>
</sect2>
+ <sect2 id="xindex-opclass-dependencies">
+ <title>System Dependencies on Operator Classes</title>
+
+ <indexterm>
+ <primary>ordering operator</primary>
+ </indexterm>
+
+ <para>
+ <productname>PostgreSQL</productname> uses operator classes to infer the
+ properties of operators in more ways than just whether they can be used
+ with indexes. Therefore, you might want to create operator classes
+ even if you have no intention of indexing any columns of your datatype.
+ </para>
+
+ <para>
+ In particular, there are SQL features such as <literal>ORDER BY</> and
+ <literal>DISTINCT</> that require comparison and sorting of values.
+ To implement these features on a user-defined datatype,
+ <productname>PostgreSQL</productname> looks for the default B-tree operator
+ class for the datatype. The <quote>equals</> member of this operator
+ class defines the system's notion of equality of values for
+ <literal>GROUP BY</> and <literal>DISTINCT</>, and the sort ordering
+ imposed by the operator class defines the default <literal>ORDER BY</>
+ ordering.
+ </para>
+
+ <para>
+ Comparison of arrays of user-defined types also relies on the semantics
+ defined by the default B-tree operator class.
+ </para>
+
+ <para>
+ If there is no default B-tree operator class for a datatype, the system
+ will look for a default hash operator class. But since that kind of
+ operator class only provides equality, in practice it is only enough
+ to support array equality.
+ </para>
+
+ <para>
+ When there is no default operator class for a datatype, you will get
+ errors like <quote>could not identify an ordering operator</> if you
+ try to use these SQL features with the datatype.
+ </para>
+
+ <note>
+ <para>
+ In <ProductName>PostgreSQL</ProductName> versions before 7.4,
+ sorting and grouping operations would implicitly use operators named
+ <literal>=</>, <literal><</>, and <literal>></>. The new
+ behavior of relying on default operator classes avoids having to make
+ any assumption about the behavior of operators with particular names.
+ </para>
+ </note>
+ </sect2>
+
<sect2 id="xindex-opclass-features">
<title>Special Features of Operator Classes</title>
<para>
There are two special features of operator classes that we have
- not discussed yet, mainly because they are not very useful
- with the default B-tree index method.
+ not discussed yet, mainly because they are not useful
+ with the most commonly used index methods.
</para>
<para>
diff --git a/doc/src/sgml/xoper.sgml b/doc/src/sgml/xoper.sgml
index a2705eb6636..dc03c3e7e40 100644
--- a/doc/src/sgml/xoper.sgml
+++ b/doc/src/sgml/xoper.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/xoper.sgml,v 1.24 2003/06/22 22:04:54 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/xoper.sgml,v 1.25 2003/08/17 22:09:00 tgl Exp $
-->
<sect1 id="xoper">
@@ -471,17 +471,6 @@ table1.column1 OP table2.column2
</para>
</note>
- <note>
- <para>
- <literal>GROUP BY</> and <literal>DISTINCT</> operations require each
- datatype being grouped or compared to have a mergejoinable
- equality operator named <literal>=</>. The equality operator and its
- associated <literal>SORT1</> operator are used to implement these
- operations. Also, the associated <literal>SORT1</> operator is the
- default ordering operator for <literal>ORDER BY</>.
- </para>
- </note>
-
<note>
<para>
In <ProductName>PostgreSQL</ProductName> versions before 7.3,
--
GitLab