Re: Typo in doc or wrong EXCLUDE implementation

On Thu, Aug 9, 2018 at 12:31 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> I think the OP is reading "equivalent" literally, as meaning that
> an EXCLUDE with operators that act like equality is treated as being
> the same as UNIQUE for *every* purpose. We're not going there, IMO,
> so probably we need to tweak the doc wording a little. Perhaps
> writing "functionally equivalent" would be better? Or instead of
> "is equivalent to", write "imposes the same restriction as"?
>

Maybe something like:

diff --git a/doc/src/sgml/ref/create_table.sgml
b/doc/src/sgml/ref/create_table.sgml
index d936de3f23..7c31fe853b 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -928,12 +928,10 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
The <literal>EXCLUDE</literal> clause defines an exclusion
constraint, which guarantees that if
any two rows are compared on the specified column(s) or
- expression(s) using the specified operator(s), not all of these
- comparisons will return <literal>TRUE</literal>. If all of the
- specified operators test for equality, this is equivalent to a
- <literal>UNIQUE</literal> constraint, although an ordinary unique
constraint
- will be faster. However, exclusion constraints can specify
- constraints that are more general than simple equality.
+ expression(s) using the specified operator(s), at least one of the
+ comparisons will return <literal>FALSE<literal/>.
+ Exclusion constraints can (and should) be used to specify
+ expressions that do not involve simple equality.
For example, you can specify a constraint that
no two rows in the table contain overlapping circles
(see <xref linkend="datatype-geometric"/>) by using the
@@ -968,6 +966,14 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
exclusion constraint on a subset of the table; internally this
creates a
partial index. Note that parentheses are required around the
predicate.
</para>
+
+ <para>
+ <productname>PostgreSQL</productname> does not consider an exclusion
+ constraint to be a valid unique constraint for purposes of
determining the
+ validity of a foreign key constraint. For this reason, in addition
to performance,
+ an exclusion constraint defined using only equality operators should
be defined
+ as a <literal>UNIQUE<literal/> constraint.
+ </para>
</listitem>
</varlistentry>