Kevin Grittner <kgri...@ymail.com> wrote:
> Bruce Momjian <br...@momjian.us> wrote:
>> I think we need to see a patch from Kevin that shows all the row
>> comparisons documented and we can see the impact of the
>> user-visibile part.
First draft attached.
> I'm inclined to first submit a proposed documentation patch for the
> existing record operators, and see if we can make everyone happy
> with that, and *then* see about adding documentation for the new
> ones. Trying to deal with both at once is likely to increase
> confusion and wheel-spinning.
When I took a stab at it, the new operators only seemed to merit a
single paragraph, so that is included after all.
--
Kevin Grittner
EDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
*** a/doc/src/sgml/func.sgml
--- b/doc/src/sgml/func.sgml
***************
*** 12739,12745 **** WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
<para>
See <xref linkend="row-wise-comparison"> for details about the meaning
! of a row-wise comparison.
</para>
</sect2>
--- 12739,12745 ----
<para>
See <xref linkend="row-wise-comparison"> for details about the meaning
! of a row constructor comparison.
</para>
</sect2>
***************
*** 12795,12806 **** WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
<para>
See <xref linkend="row-wise-comparison"> for details about the meaning
! of a row-wise comparison.
</para>
</sect2>
<sect2>
! <title>Row-wise Comparison</title>
<indexterm zone="functions-subquery">
<primary>comparison</primary>
--- 12795,12806 ----
<para>
See <xref linkend="row-wise-comparison"> for details about the meaning
! of a row constructor comparison.
</para>
</sect2>
<sect2>
! <title>Single-row Comparison</title>
<indexterm zone="functions-subquery">
<primary>comparison</primary>
***************
*** 12823,12829 **** WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
<para>
See <xref linkend="row-wise-comparison"> for details about the meaning
! of a row-wise comparison.
</para>
</sect2>
</sect1>
--- 12823,12829 ----
<para>
See <xref linkend="row-wise-comparison"> for details about the meaning
! of a row constructor comparison.
</para>
</sect2>
</sect1>
***************
*** 12853,12864 **** WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
</indexterm>
<indexterm>
<primary>row-wise comparison</primary>
</indexterm>
<indexterm>
<primary>comparison</primary>
! <secondary>row-wise</secondary>
</indexterm>
<indexterm>
--- 12853,12874 ----
</indexterm>
<indexterm>
+ <primary>composite type</primary>
+ <secondary>comparison</secondary>
+ </indexterm>
+
+ <indexterm>
<primary>row-wise comparison</primary>
</indexterm>
<indexterm>
<primary>comparison</primary>
! <secondary>composite type</secondary>
! </indexterm>
!
! <indexterm>
! <primary>comparison</primary>
! <secondary>row constructor</secondary>
</indexterm>
<indexterm>
***************
*** 13023,13029 **** AND
</sect2>
<sect2 id="row-wise-comparison">
! <title>Row-wise Comparison</title>
<synopsis>
<replaceable>row_constructor</replaceable> <replaceable>operator</replaceable> <replaceable>row_constructor</replaceable>
--- 13033,13039 ----
</sect2>
<sect2 id="row-wise-comparison">
! <title>Row Constructor Comparison</title>
<synopsis>
<replaceable>row_constructor</replaceable> <replaceable>operator</replaceable> <replaceable>row_constructor</replaceable>
***************
*** 13033,13052 **** AND
Each side is a row constructor,
as described in <xref linkend="sql-syntax-row-constructors">.
The two row values must have the same number of fields.
! Each side is evaluated and they are compared row-wise. Row comparisons
! are allowed when the <replaceable>operator</replaceable> is
<literal>=</>,
<literal><></>,
<literal><</>,
<literal><=</>,
<literal>></> or
! <literal>>=</>,
! or has semantics similar to one of these. (To be specific, an operator
! can be a row comparison operator if it is a member of a B-tree operator
! class, or is the negator of the <literal>=</> member of a B-tree operator
! class.)
</para>
<para>
The <literal>=</> and <literal><></> cases work slightly differently
from the others. Two rows are considered
--- 13043,13067 ----
Each side is a row constructor,
as described in <xref linkend="sql-syntax-row-constructors">.
The two row values must have the same number of fields.
! Each side is evaluated and they are compared row-wise. Row constructor
! comparisons are allowed when the <replaceable>operator</replaceable> is
<literal>=</>,
<literal><></>,
<literal><</>,
<literal><=</>,
<literal>></> or
! <literal>>=</>.
! Every row element must be of a type which has a default B-tree operator
! class or the attempted comparison may generate an error.
</para>
+ <note>
+ <para>
+ Errors related to the number or types of elements might not occur if
+ the comparison is resolved using earlier columns.
+ </para>
+ </note>
+
<para>
The <literal>=</> and <literal><></> cases work slightly differently
from the others. Two rows are considered
***************
*** 13104,13123 **** AND
be either true or false, never null.
</para>
! <note>
! <para>
! The SQL specification requires row-wise comparison to return NULL if the
! result depends on comparing two NULL values or a NULL and a non-NULL.
! <productname>PostgreSQL</productname> does this only when comparing the
! results of two row constructors or comparing a row constructor to the
! output of a subquery (as in <xref linkend="functions-subquery">).
! In other contexts where two composite-type values are compared, two
! NULL field values are considered equal, and a NULL is considered larger
! than a non-NULL. This is necessary in order to have consistent sorting
! and indexing behavior for composite types.
! </para>
! </note>
</sect2>
</sect1>
--- 13119,13182 ----
be either true or false, never null.
</para>
! </sect2>
+ <sect2 id="composite-type-comparison">
+ <title>Composite Type Comparison</title>
+
+ <synopsis>
+ <replaceable>record</replaceable> <replaceable>operator</replaceable> <replaceable>record</replaceable>
+ </synopsis>
+
+ <para>
+ The SQL specification requires row-wise comparison to return NULL if the
+ result depends on comparing two NULL values or a NULL and a non-NULL.
+ <productname>PostgreSQL</productname> does this only when comparing the
+ results of two row constructors (as in
+ <xref linkend="row-wise-comparison">) or comparing a row constructor
+ to the output of a subquery (as in <xref linkend="functions-subquery">).
+ In other contexts where two composite-type values are compared, two
+ NULL field values are considered equal, and a NULL is considered larger
+ than a non-NULL. This is necessary in order to have consistent sorting
+ and indexing behavior for composite types.
+ </para>
+
+ <para>
+ Each side is evaluated and they are compared row-wise. Composite type
+ comparisons are allowed when the <replaceable>operator</replaceable> is
+ <literal>=</>,
+ <literal><></>,
+ <literal><</>,
+ <literal><=</>,
+ <literal>></> or
+ <literal>>=</>,
+ or has semantics similar to one of these. (To be specific, an operator
+ can be a row comparison operator if it is a member of a B-tree operator
+ class, or is the negator of the <literal>=</> member of a B-tree operator
+ class.) The default behavior of the above operators is the same as for
+ <literal>IS [ NOT ] DISTINCT FROM</literal> for row constructors (see
+ <xref linkend="row-wise-comparison">).
+ </para>
+
+ <para>
+ To support matching of rows which include elements without a default
+ B-tree operator class, the following operators are defined for composite
+ type comparison:
+ <literal>*=</>,
+ <literal>*<></>,
+ <literal>*<</>,
+ <literal>*<=</>,
+ <literal>*></>, and
+ <literal>*>=</>.
+ These operators are also used internally to maintain materialized views,
+ and may be useful to replication software. To ensure that all user
+ visible changes are detected, even when the equality operator for the
+ type treats old and new values as equal, the byte images of the stored
+ data are compared. While ordering is deterministic, it is not generally
+ useful except to facilitate merge joins. Ordering may differ between
+ system architectures and major releases of
+ <productname>PostgreSQL</productname>.
+ </para>
</sect2>
</sect1>
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
