<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/inherit.sgml,v 1.11 2000/07/02 22:00:23 momjian Exp $
-->

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

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

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

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

   In this case, an  instance  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  class  can inherit from zero or more other classes,
   and a query can reference either  all  instances  of  a
   class  or  all  instances  of  a  class 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, the query is:

   <programlisting>
    SELECT c.name, c.altitude
    FROM cities c
    WHERE c.altitude > 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, but not capital cities 
   that are situated at an attitude 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 classes 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 attribute 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 > 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 > 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 SQL. Under the old
    syntax, to get the sub-classes you append "*" to the table name.
    For example
<programlisting>
SELECT * from cities*;
</programlisting>
    To get the old behavior, the set 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:
-->
