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 @@ @@ -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 f983b2a8213..04d2a36e5b3 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 6416183c95a..bd5d1fe78bf 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 a2705eb6636..dc03c3e7e40 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,