Document the system attributes ctid and tableoid, which for some reason

were never yet mentioned anywhere in our documentation.  Improve
explanations of the other system attributes, too.

diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 4a02fab823f75874c91a8266d570f8eeffa904e6..d8cd5f18a28f322e4d63a4216de88d002c6fc753 100644 (file)
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.32 2001/01/06 11:58:56 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.33 2001/01/08 22:07:47 tgl Exp $
 -->
 
 <chapter id="sql-syntax">
@@ -568,27 +568,33 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
        <term>oid</term>
        <listitem>
    <para>
-    stands for the unique identifier of an instance which is added by
-    Postgres to all instances automatically. OIDs are not reused and are
-    32-bit quantities.
+    The unique identifier (object ID) of a row.  This is a serial number
+    that is added by Postgres to all rows automatically. OIDs are not
+    reused and are 32-bit quantities.
    </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
-       <term>xmin</term>
+      <term>tableoid</term>
        <listitem>
    <para>
-    The identity of the inserting transaction.
+    The OID of the table containing this row.  This attribute is
+    particularly handy for queries that select from inheritance
+    hierarchies, since without it, it's difficult to tell which
+    individual table a row came from.  The tableoid can be joined
+    against the OID attribute of pg_class to obtain the table name.
    </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
-      <term>xmax</term>
+       <term>xmin</term>
        <listitem>
    <para>
-    The identity of the deleting transaction.
+    The identity (transaction ID) of the inserting transaction for
+    this tuple.  (Note: a tuple is an individual state of a row;
+    each UPDATE of a row creates a new tuple for the same logical row.)
    </para>
        </listitem>
       </varlistentry>
@@ -597,7 +603,19 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
       <term>cmin</term>
        <listitem>
    <para>
-    The command identifier within the inserting transaction.
+    The command identifier (starting at zero) within the inserting
+    transaction.
+   </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>xmax</term>
+       <listitem>
+   <para>
+    The identity (transaction ID) of the deleting transaction,
+    or zero for an undeleted tuple.  In practice, this is never nonzero
+    for a visible tuple.
    </para>
        </listitem>
       </varlistentry>
@@ -606,7 +624,24 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
       <term>cmax</term>
        <listitem>
    <para>
-    The command identifier within the deleting transaction.
+    The command identifier within the deleting transaction, or zero.
+    Again, this is never nonzero for a visible tuple.
+   </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term>ctid</term>
+       <listitem>
+   <para>
+    The tuple ID of the tuple within its table.  This is a pair
+    (block number, tuple index within block) that identifies the
+    physical location of the tuple.  Note that although the ctid
+    can be used to locate the tuple very quickly, a row's ctid
+    will change each time it is updated or moved by VACUUM.
+    Therefore ctid is useless as a long-term row identifier.
+    The OID, or even better a user-defined serial number, should
+    be used to identify logical rows.
    </para>
        </listitem>
       </varlistentry>