<!-- doc/src/sgml/rules.sgml -->

<chapter id="rules">
<title>The Rule System</title>

 <indexterm zone="rules">
  <primary>rule</primary>
 </indexterm>

<para>
     This chapter discusses the rule system in
     <productname>PostgreSQL</productname>.  Production rule systems
     are conceptually simple, but there are many subtle points
     involved in actually using them.
</para>

<para>
     Some other database systems define active database rules, which
     are usually stored procedures and triggers.  In
     <productname>PostgreSQL</productname>, these can be implemented
     using functions and triggers as well.
</para>

<para>
     The rule system (more precisely speaking, the query rewrite rule
     system) is totally different from stored procedures and triggers.
     It modifies queries to take rules into consideration, and then
     passes the modified query to the query planner for planning and
     execution.  It is very powerful, and can be used for many things
     such as query language procedures, views, and versions.  The
     theoretical foundations and the power of this rule system are
     also discussed in <xref linkend="ston90b"/> and <xref
     linkend="ong90"/>.
</para>

<sect1 id="querytree">
<title>The Query Tree</title>

<indexterm zone="querytree">
 <primary>query tree</primary>
</indexterm>

<para>
    To understand how the rule system works it is necessary to know
    when it is invoked and what its input and results are.
</para>

<para>
    The rule system is located between the parser and the planner.
    It takes the output of the parser, one query tree, and the user-defined
    rewrite rules, which are also
    query trees with some extra information, and creates zero or more
    query trees as result. So its input and output are always things
    the parser itself could have produced and thus, anything it sees
    is basically representable as an <acronym>SQL</acronym> statement.
</para>

<para>
    Now what is a query tree? It is an internal representation of an
    <acronym>SQL</acronym> statement where the single parts that it is
    built from are stored separately. These query trees can be shown
    in the server log if you set the configuration parameters
    <varname>debug_print_parse</varname>,
    <varname>debug_print_rewritten</varname>, or
    <varname>debug_print_plan</varname>.  The rule actions are also
    stored as query trees, in the system catalog
    <structname>pg_rewrite</structname>.  They are not formatted like
    the log output, but they contain exactly the same information.
</para>

<para>
    Reading a raw query tree requires some experience.  But since
    <acronym>SQL</acronym> representations of query trees are
    sufficient to understand the rule system, this chapter will not
    teach how to read them.
</para>

<para>
    When reading the <acronym>SQL</acronym> representations of the
    query trees in this chapter it is necessary to be able to identify
    the parts the statement is broken into when it is in the query tree
    structure. The parts of a query tree are

<variablelist>
    <varlistentry>
    <term>
        the command type
    </term>
    <listitem>
    <para>
        This is a simple value telling which command
        (<command>SELECT</command>, <command>INSERT</command>,
        <command>UPDATE</command>, <command>DELETE</command>) produced
        the query tree.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term>
        the range table
      <indexterm><primary>range table</primary></indexterm>
    </term>
    <listitem>
    <para>
        The range table is a list of relations that are used in the query.
        In a <command>SELECT</command> statement these are the relations given after
        the <literal>FROM</literal> key word.
    </para>

    <para>
        Every range table entry identifies a table or view and tells
        by which name it is called in the other parts of the query.
        In the query