From: Tom Lane Date: Sun, 17 Aug 2003 22:09:00 +0000 (+0000) Subject: Update documentation to reflect the fact that ORDER BY, GROUP BY, etc X-Git-Tag: REL7_4_BETA2~43 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=421594798685c8681a56d2b98db0412dfb41acff;p=postgresql 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. --- diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml index 2ac9d3f2ed..34933a37ef 100644 --- a/doc/src/sgml/ref/create_operator.sgml +++ b/doc/src/sgml/ref/create_operator.sgml @@ -1,5 +1,5 @@ @@ -43,17 +43,11 @@ CREATE OPERATOR name ( The operator name is a sequence of up to NAMEDATALEN-1 (63 by default) characters from the following list: -+ - * / < > = ~ ! @ # % ^ & | ` ? $ ++ - * / < > = ~ ! @ # % ^ & | ` ? There are a few restrictions on your choice of name: - - - $ cannot be defined as a single-character operator, - although it can be part of a multicharacter operator name. - - -- and /* cannot appear anywhere in an operator name, @@ -66,7 +60,7 @@ CREATE OPERATOR name ( -, unless the name also contains at least one of these characters: -~ ! @ # % ^ & | ` ? $ +~ ! @ # % ^ & | ` ? For example, @- is an allowed operator name, but *- is not. diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml index f983b2a821..04d2a36e5b 100644 --- a/doc/src/sgml/ref/select.sgml +++ b/doc/src/sgml/ref/select.sgml @@ -1,5 +1,5 @@ @@ -660,8 +660,11 @@ SELECT name FROM distributors ORDER BY code; ORDER BY clause. If not specified, ASC is assumed by default. Alternatively, a specific ordering operator name may be specified in the USING clause. - ASC is equivalent to USING < and - DESC is equivalent to USING >. + ASC is usually equivalent to USING < and + DESC is usually equivalent to 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.) @@ -671,7 +674,7 @@ SELECT name FROM distributors ORDER BY code; - 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. @@ -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-FROM feature is used in a SELECT statement that also - contains an explicit FROM clause. + contains an explicit FROM clause. Also, it is + possible to disable the implicit-FROM feature + by setting the ADD_MISSING_FROM parameter to false. @@ -1015,7 +1020,7 @@ SELECT distributors.* FROM distributors d, distributors distributors; noise and can be omitted without affecting the meaning. The PostgreSQL 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. AS is optional in FROM items, however. @@ -1025,7 +1030,7 @@ SELECT distributors.* FROM distributors d, distributors distributors; Namespace Available to <literal>GROUP BY</literal> and <literal>ORDER BY</literal> - In the SQL standard, an ORDER BY clause may + In the SQL92 standard, an ORDER BY clause may only use result column names or numbers, while a GROUP BY clause may only use expressions based on input column names. PostgreSQL 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. + + + SQL99 uses a slightly different definition which is not upward compatible + with SQL92. In most cases, however, PostgreSQL + will interpret an ORDER BY or GROUP + BY expression the same way SQL99 does. + diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml index 6416183c95..bd5d1fe78b 100644 --- a/doc/src/sgml/xindex.sgml +++ b/doc/src/sgml/xindex.sgml @@ -1,5 +1,5 @@ @@ -452,7 +452,7 @@ CREATE OPERATOR = ( 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. @@ -551,13 +551,68 @@ CREATE OPERATOR CLASS complex_abs_ops + + System Dependencies on Operator Classes + + + ordering operator + + + + PostgreSQL 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. + + + + In particular, there are SQL features such as ORDER BY and + DISTINCT that require comparison and sorting of values. + To implement these features on a user-defined datatype, + PostgreSQL looks for the default B-tree operator + class for the datatype. The equals member of this operator + class defines the system's notion of equality of values for + GROUP BY and DISTINCT, and the sort ordering + imposed by the operator class defines the default ORDER BY + ordering. + + + + Comparison of arrays of user-defined types also relies on the semantics + defined by the default B-tree operator class. + + + + 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. + + + + When there is no default operator class for a datatype, you will get + errors like could not identify an ordering operator if you + try to use these SQL features with the datatype. + + + + + In PostgreSQL versions before 7.4, + sorting and grouping operations would implicitly use operators named + =, <, and >. The new + behavior of relying on default operator classes avoids having to make + any assumption about the behavior of operators with particular names. + + + + Special Features of Operator Classes 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. diff --git a/doc/src/sgml/xoper.sgml b/doc/src/sgml/xoper.sgml index a2705eb663..dc03c3e7e4 100644 --- a/doc/src/sgml/xoper.sgml +++ b/doc/src/sgml/xoper.sgml @@ -1,5 +1,5 @@ @@ -471,17 +471,6 @@ table1.column1 OP table2.column2 - - - GROUP BY and DISTINCT operations require each - datatype being grouped or compared to have a mergejoinable - equality operator named =. The equality operator and its - associated SORT1 operator are used to implement these - operations. Also, the associated SORT1 operator is the - default ordering operator for ORDER BY. - - - In PostgreSQL versions before 7.3,