diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index b4c4b5e23ef2a82354b88ce2f96b207a3723e13e..48223943000a43f233679b0afa201871c1fd5f09 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -1257,6 +1257,12 @@ SELECT 3 OPERATOR(pg_catalog.+) 4; + + + A collation expression + + + A scalar subquery @@ -1898,8 +1904,8 @@ CAST ( expression AS type - - COLLATE Clause + + Collation Expressions COLLATE @@ -1925,7 +1931,7 @@ CAST ( expression AS type - The two typical uses of the COLLATE clause are + The two common uses of the COLLATE clause are overriding the sort order in an ORDER BY clause, for example: @@ -1934,15 +1940,28 @@ SELECT a, b, c FROM tbl WHERE ... ORDER BY a COLLATE "C"; and overriding the collation of a function or operator call that has locale-sensitive results, for example: -SELECT * FROM tbl WHERE a > 'foo' COLLATE "C"; +SELECT * FROM tbl WHERE a > 'foo' COLLATE "C"; + + Note that in the latter case the COLLATE clause is + attached to an input argument of the operator we wish to affect. + It doesn't matter which argument of the operator or function call the + COLLATE clause is attached to, because the collation that is + applied by the operator or function is derived by considering all + arguments, and an explicit COLLATE clause will override the + collations of all other arguments. (Attaching non-matching + COLLATE clauses to more than one argument, however, is an + error. For more details see .) + Thus, this gives the same result as the previous example: + +SELECT * FROM tbl WHERE a COLLATE "C" > 'foo'; + + But this is an error: + +SELECT * FROM tbl WHERE (a > 'foo') COLLATE "C"; - In the latter case it doesn't matter which argument of the - operator of function call the COLLATE clause is - attached to, because the collation that is applied by the operator - or function is derived from all arguments, and - the COLLATE clause will override the collations of all - other arguments. Attaching nonmatching COLLATE - clauses to more than one argument, however, is an error. + because it attempts to apply a collation to the result of the + > operator, which is of the non-collatable data type + boolean.