diff options
| -rw-r--r-- | doc/src/sgml/ref/create_operator.sgml | 12 | ||||
| -rw-r--r-- | doc/src/sgml/ref/select.sgml | 26 | ||||
| -rw-r--r-- | doc/src/sgml/xindex.sgml | 63 | ||||
| -rw-r--r-- | 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,19 +43,13 @@ 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, since they will be taken as the start of a comment. </para> @@ -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"> @@ -473,17 +473,6 @@ table1.column1 OP table2.column2 <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, the <literal>MERGES</> shorthand was not available: to make a merge-joinable operator one had to write both <literal>SORT1</> and |