Naming of new EXCLUDE constraints

Simon Riggs wrote:
> On Sun, 2010-04-04 at 22:12 -0400, Bruce Momjian wrote:
> > Simon Riggs wrote:
> > >
> > > How about we call it "exclusivity constraints".
> > >
> > > Not much of a change, but helps to differentiate.
> >
> > Well, the keyword is EXCLUDE so we could call it "EXCLUDE contraints".
>
> If that is the keyword then that is what people will use, agreed.
>
> That is poor English, but I think we can reword the sentences to allow
> that phrase to make sense.
>
> e.g. Added capability for EXCLUDE constraints.

I have modified the documentation with the attached patch to call this
new features "exclude constraints".  Is this what everyone wants?

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com
Index: doc/src/sgml/catalogs.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v
retrieving revision 2.225
diff -c -c -r2.225 catalogs.sgml
*** doc/src/sgml/catalogs.sgml    3 Apr 2010 07:22:52 -0000    2.225
--- doc/src/sgml/catalogs.sgml    13 Apr 2010 01:26:31 -0000
***************
*** 1701,1707 ****

    <para>
     The catalog <structname>pg_constraint</structname> stores check, primary
!    key, unique, foreign key, and exclusion constraints on tables.
     (Column constraints are not treated specially.  Every column constraint is
     equivalent to some table constraint.)
     Not-null constraints are represented in the <structname>pg_attribute</>
--- 1701,1707 ----

    <para>
     The catalog <structname>pg_constraint</structname> stores check, primary
!    key, unique, foreign key, and exclude constraints on tables.
     (Column constraints are not treated specially.  Every column constraint is
     equivalent to some table constraint.)
     Not-null constraints are represented in the <structname>pg_attribute</>
***************
*** 1757,1763 ****
          <literal>p</> = primary key constraint,
          <literal>u</> = unique constraint,
          <literal>t</> = constraint trigger,
!         <literal>x</> = exclusion constraint
        </entry>
       </row>

--- 1757,1763 ----
          <literal>p</> = primary key constraint,
          <literal>u</> = unique constraint,
          <literal>t</> = constraint trigger,
!         <literal>x</> = exclude constraint
        </entry>
       </row>

***************
*** 1794,1800 ****
        <entry><type>oid</type></entry>
        <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
        <entry>The index supporting this constraint, if it's a unique, primary
!        key, foreign key, or exclusion constraint; else 0</entry>
       </row>

       <row>
--- 1794,1800 ----
        <entry><type>oid</type></entry>
        <entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
        <entry>The index supporting this constraint, if it's a unique, primary
!        key, foreign key, or exclude constraint; else 0</entry>
       </row>

       <row>
***************
*** 1902,1908 ****
        <entry><structfield>conexclop</structfield></entry>
        <entry><type>oid[]</type></entry>
        <entry><literal><link linkend="catalog-pg-operator"><structname>pg_operator</structname></link>.oid</></entry>
!       <entry>If an exclusion constraint, list of the per-column exclusion operators</entry>
       </row>

       <row>
--- 1902,1908 ----
        <entry><structfield>conexclop</structfield></entry>
        <entry><type>oid[]</type></entry>
        <entry><literal><link linkend="catalog-pg-operator"><structname>pg_operator</structname></link>.oid</></entry>
!       <entry>If an exclude constraint, list of the per-column exclusion operators</entry>
       </row>

       <row>
***************
*** 1923,1929 ****
    </table>

    <para>
!    In the case of an exclusion constraint, <structfield>conkey</structfield>
     is only useful for constraint elements that are simple column references.
     For other cases, a zero appears in <structfield>conkey</structfield>
     and the associated index must be consulted to discover the expression
--- 1923,1929 ----
    </table>

    <para>
!    In the case of an exclude constraint, <structfield>conkey</structfield>
     is only useful for constraint elements that are simple column references.
     For other cases, a zero appears in <structfield>conkey</structfield>
     and the associated index must be consulted to discover the expression
***************
*** 1946,1952 ****
      <literal>pg_class.relchecks</literal> needs to agree with the
      number of check-constraint entries found in this table for each
      relation.  Also, <literal>pg_class.relhasexclusion</literal> must
!     be true if there are any exclusion-constraint entries for the relation.
     </para>
    </note>

--- 1946,1952 ----
      <literal>pg_class.relchecks</literal> needs to agree with the
      number of check-constraint entries found in this table for each
      relation.  Also, <literal>pg_class.relhasexclusion</literal> must
!     be true if there are any exclude-constraint entries for the relation.
     </para>
    </note>

Index: doc/src/sgml/ddl.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v
retrieving revision 1.93
diff -c -c -r1.93 ddl.sgml
*** doc/src/sgml/ddl.sgml    6 Apr 2010 02:18:04 -0000    1.93
--- doc/src/sgml/ddl.sgml    13 Apr 2010 01:26:31 -0000
***************
*** 847,856 ****
    </sect2>

    <sect2>
!    <title>Exclusion constraints</title>

     <indexterm>
!     <primary>exclusion constraint</primary>
     </indexterm>

     <indexterm>
--- 847,856 ----
    </sect2>

    <sect2>
!    <title>Exclude constraints</title>

     <indexterm>
!     <primary>exclude constraint</primary>
     </indexterm>

     <indexterm>
***************
*** 859,865 ****
     </indexterm>

     <para>
!     Exclusion constraints ensure that if any two rows are compared on
      the specified columns or expressions using the specified operators,
      at least one of these operator comparisons will return false or null.
      The syntax is:
--- 859,865 ----
     </indexterm>

     <para>
!     Exclude constraints ensure that if any two rows are compared on
      the specified columns or expressions using the specified operators,
      at least one of these operator comparisons will return false or null.
      The syntax is:
Index: doc/src/sgml/release-9.0.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/release-9.0.sgml,v
retrieving revision 2.15
diff -c -c -r2.15 release-9.0.sgml
*** doc/src/sgml/release-9.0.sgml    5 Apr 2010 02:46:42 -0000    2.15
--- doc/src/sgml/release-9.0.sgml    13 Apr 2010 01:26:31 -0000
***************
*** 2740,2748 ****
         </listitem>
         <listitem>
          <para>
!          Add exclusion constraints, which generalize the concept of
            uniqueness to support any indexable commutative operator, not just
!           equality. Two rows violate the exclusion constraint if
            "row1.col OP row2.col" is TRUE for each of the columns in
            the constraint.
          </para>
--- 2740,2748 ----
         </listitem>
         <listitem>
          <para>
!          Add <literal>EXCLUDE</> constraints, which generalize the concept of
            uniqueness to support any indexable commutative operator, not just
!           equality. Two rows violate the <literal>EXCLUDE</> constraint if
            "row1.col OP row2.col" is TRUE for each of the columns in
            the constraint.
          </para>
Index: doc/src/sgml/ref/create_table.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/create_table.sgml,v
retrieving revision 1.125
diff -c -c -r1.125 create_table.sgml
*** doc/src/sgml/ref/create_table.sgml    3 Apr 2010 07:23:00 -0000    1.125
--- doc/src/sgml/ref/create_table.sgml    13 Apr 2010 01:26:31 -0000
***************
*** 459,472 ****
      <term><literal>EXCLUDE [ USING <replaceable class="parameter">index_method</replaceable> ] ( <replaceable
class="parameter">exclude_element</replaceable>WITH <replaceable class="parameter">operator</replaceable> [, ... ] )
<replaceableclass="parameter">index_parameters</replaceable> [ WHERE ( <replaceable
class="parameter">predicate</replaceable>) ]</literal></term> 
      <listitem>
       <para>
!       The <literal>EXCLUDE</> 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</>.  If all of the
        specified operators test for equality, this is equivalent to a
        <literal>UNIQUE</> constraint, although an ordinary unique constraint
!       will be faster.  However, exclusion constraints can specify
        constraints that are more general than simple equality.
        For example, you can specify a constraint that
        no two rows in the table contain overlapping circles
--- 459,472 ----
      <term><literal>EXCLUDE [ USING <replaceable class="parameter">index_method</replaceable> ] ( <replaceable
class="parameter">exclude_element</replaceable>WITH <replaceable class="parameter">operator</replaceable> [, ... ] )
<replaceableclass="parameter">index_parameters</replaceable> [ WHERE ( <replaceable
class="parameter">predicate</replaceable>) ]</literal></term> 
      <listitem>
       <para>
!       The <literal>EXCLUDE</> clause defines an exclude
        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</>.  If all of the
        specified operators test for equality, this is equivalent to a
        <literal>UNIQUE</> constraint, although an ordinary unique constraint
!       will be faster.  However, exclude constraints can specify
        constraints that are more general than simple equality.
        For example, you can specify a constraint that
        no two rows in the table contain overlapping circles
***************
*** 475,481 ****
       </para>

       <para>
!       Exclusion constraints are implemented using
        an index, so each specified operator must be associated with an
        appropriate operator class
        (see <xref linkend="indexes-opclass">) for the index access
--- 475,481 ----
       </para>

       <para>
!       Exclude constraints are implemented using
        an index, so each specified operator must be associated with an
        appropriate operator class
        (see <xref linkend="indexes-opclass">) for the index access
***************
*** 491,504 ****
        The access method must support <literal>amgettuple</> (see <xref
        linkend="indexam">); at present this means <acronym>GIN</>
        cannot be used.  Although it's allowed, there is little point in using
!       btree or hash indexes with an exclusion constraint, because this
        does nothing that an ordinary unique constraint doesn't do better.
        So in practice the access method will always be <acronym>GiST</>.
       </para>

       <para>
        The <replaceable class="parameter">predicate</> allows you to specify an
!       exclusion constraint on a subset of the table; internally this creates a
        partial index. Note that parentheses are required around the predicate.
       </para>
      </listitem>
--- 491,504 ----
        The access method must support <literal>amgettuple</> (see <xref
        linkend="indexam">); at present this means <acronym>GIN</>
        cannot be used.  Although it's allowed, there is little point in using
!       btree or hash indexes with an exclude constraint, because this
        does nothing that an ordinary unique constraint doesn't do better.
        So in practice the access method will always be <acronym>GiST</>.
       </para>

       <para>
        The <replaceable class="parameter">predicate</> allows you to specify an
!       exclude constraint on a subset of the table; internally this creates a
        partial index. Note that parentheses are required around the predicate.
       </para>
      </listitem>
***************
*** 1176,1182 ****
    </para>

    <para>
!    Create table <structname>circles</> with an exclusion
     constraint that prevents any two circles from overlapping:

  <programlisting>
--- 1176,1182 ----
    </para>

    <para>
!    Create table <structname>circles</> with an exclude
     constraint that prevents any two circles from overlapping:

  <programlisting>
Index: doc/src/sgml/ref/set_constraints.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/ref/set_constraints.sgml,v
retrieving revision 1.19
diff -c -c -r1.19 set_constraints.sgml
*** doc/src/sgml/ref/set_constraints.sgml    3 Apr 2010 07:23:02 -0000    1.19
--- doc/src/sgml/ref/set_constraints.sgml    13 Apr 2010 01:26:35 -0000
***************
*** 73,79 ****
     <literal>NOT NULL</> and <literal>CHECK</> constraints are
     always checked immediately when a row is inserted or modified
     (<emphasis>not</> at the end of the statement).
!    Uniqueness and exclusion constraints that have not been declared
     <literal>DEFERRABLE</> are also checked immediately.
    </para>

--- 73,79 ----
     <literal>NOT NULL</> and <literal>CHECK</> constraints are
     always checked immediately when a row is inserted or modified
     (<emphasis>not</> at the end of the statement).
!    Uniqueness and exclude constraints that have not been declared
     <literal>DEFERRABLE</> are also checked immediately.
    </para>