postgresql/doc/src/sgml/inherit.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/inherit.sgml,v 1.13 2001/01/13 23:58:55 petere Exp $
-->

 <chapter id="inherit">
  <title>Inheritance</title>

  <para>
   Let's create two tables. The capitals  table  contains
   state  capitals  which  are also cities. Naturally, the
   capitals table should inherit from cities.

<programlisting>
CREATE TABLE cities (
    name            text,
    population      float,
    altitude        int     -- (in ft)
);

CREATE TABLE capitals (
    state           char(2)
) INHERITS (cities);
</programlisting>

   In this case, a row  of  capitals  <firstterm>inherits</firstterm>  all
   attributes  (name,  population,  and altitude) from its
   parent, cities.  The type  of  the  attribute  name  is
   <type>text</type>,  a  native  <productname>Postgres</productname>  type  for variable length
   ASCII strings.  The type of the attribute population is
   <type>float</type>,  a  native <productname>Postgres</productname> type for double precision
   floating point numbers.  State capitals have  an  extra
   attribute, state, that shows their state.  In <productname>Postgres</productname>,
   a  table  can inherit from zero or more other tables,
   and a query can reference either  all  rows  of  a
   table  or  all  rows of  a  table plus all of its
   descendants. 

   <note>
    <para>
     The inheritance hierarchy is a actually a directed acyclic graph.
    </para>
   </note>
  </para>

  <para>
    For example, the  following  query finds the  names  of  all  cities,
    including  state capitals, that are located at an altitude 
    over 500ft:

    <programlisting>
SELECT name, altitude
    FROM cities
    WHERE altitude &gt; 500;
    </programlisting>

   which returns:

   <programlisting>
+----------+----------+
|name      | altitude |
+----------+----------+
|Las Vegas | 2174     |
+----------+----------+
|Mariposa  | 1953     |
+----------+----------+
|Madison   | 845      |
+----------+----------+
   </programlisting>
  </para>

  <para>
    On the other hand, the  following  query  finds
    all  the cities that are not state capitals and
    are situated at an altitude of 500ft or higher:

   <programlisting>
SELECT name, altitude
    FROM ONLY cities
    WHERE altitude &gt; 500;

+----------+----------+
|name      | altitude |
+----------+----------+
|Las Vegas | 2174     |
+----------+----------+
|Mariposa  | 1953     |
+----------+----------+
   </programlisting>         
  </para>

  <para>
   Here the <quote>ONLY</quote> before cities indicates that the query should
   be  run over only cities and not tables below cities in the
   inheritance hierarchy.  Many of the  commands  that  we
   have  already discussed -- <command>SELECT</command>,
   <command>UPDATE</command> and <command>DELETE</command> --
   support this <quote>ONLY</quote> notation.
  </para>

  <para>
  In some cases you may wish to know which table a particular tuple
  originated from. There is a system column called
  <quote>TABLEOID</quote> in each table which can tell you the
  originating table:

   <programlisting>
    SELECT c.tableoid, c.name, c.altitude
    FROM cities c
    WHERE c.altitude &gt; 500;
   </programlisting>

   which returns:

   <programlisting>
+---------+----------+----------+
|tableoid |name      | altitude |
+---------+----------+----------+
|37292    |Las Vegas | 2174     |
+---------+----------+----------+
|37280    |Mariposa  | 1953     |
+---------+----------+----------+
|37280    |Madison   | 845      |
+---------+----------+----------+
   </programlisting>

   If you do a join with pg_class you can see the actual table name:

   <programlisting>
    SELECT p.relname, c.name, c.altitude
    FROM cities c, pg_class p
    WHERE c.altitude &gt; 500 and c.tableoid = p.oid;
   </programlisting>

   which returns:

   <programlisting>
+---------+----------+----------+
|relname  |name      | altitude |
+---------+----------+----------+
|capitals |Las Vegas | 2174     |
+---------+----------+----------+
|cities   |Mariposa  | 1953     |
+---------+----------+----------+
|cities   |Madison   | 845      |
+---------+----------+----------+
   </programlisting>
   
  </para>

  <note>
   <title>Deprecated</title> 
   <para>
     In previous versions of <productname>Postgres</productname>, the
     default was not to get access to child tables. This was found to
     be error prone and is also in violation of SQL99. Under the old
     syntax, to get the sub-tables you append "*" to the table name.
     For example
<programlisting>
SELECT * from cities*;
</programlisting>
     You can still explicitly specify scanning child tables by appending
     "*", as well as explicitly specify not scanning child tables by
     writing <quote>ONLY</quote>.  But beginning in version 7.1, the default
     behavior for an undecorated table name is to scan its child tables
     too, whereas before the default was not to do so.  To get the old
     default behavior, set the configuration option
     <literal>SQL_Inheritance</literal> to off, e.g.,
<programlisting>
SET SQL_Inheritance TO OFF;
</programlisting>
     or add a line in your <filename>postgresql.conf</filename> file.
   </para>
  </note>
 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->