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 @@
 
 
 
@@ -568,27 +568,33 @@ CAST ( 'string' AS type )
        oid
        
    
-    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.
    
        
       
 
       
-       xmin
+      tableoid
        
    
-    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.
    
        
       
 
       
-      xmax
+       xmin
        
    
-    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.)
    
        
       
@@ -597,7 +603,19 @@ CAST ( 'string' AS type )
       cmin
        
    
-    The command identifier within the inserting transaction.
+    The command identifier (starting at zero) within the inserting
+    transaction.
+   
+       
+      
+
+      
+      xmax
+       
+   
+    The identity (transaction ID) of the deleting transaction,
+    or zero for an undeleted tuple.  In practice, this is never nonzero
+    for a visible tuple.
    
        
       
@@ -606,7 +624,24 @@ CAST ( 'string' AS type )
       cmax
        
    
-    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.
+   
+       
+      
+
+      
+      ctid
+       
+   
+    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.