<!--#include file="top.html" -->
<b>WHAT'S THIS</b>

<p>This is a patch which allows PgSQL to make hierarchical queries a la Oracle do.

<p>(c) Evgen Potemkin 2003,2004, &lt; gppl at inbox dot ru &gt;, entirely based on PostgreSQL (http://www.postgresql.org)<br>
Patch itself distributed under GPL. No warranty of any kind is given, use it at your own risk.<br>


<p><b>INSTALLATION</b>

<p>tar xzf postgresql-7.x.tar.gz<br>
patch -p0 &lt; hier.diff<br>
cd postgresql-7.x/<br>
./configure<br>
... so on

<p><b>SYNOPSIS</b>

<p>#create table data (id int4, pnt int4, data varchar(20));

<p>data:
<pre>
+----+-----+-------------+----------+---------+
| id | pnt |    data     |   c_id   |  c_pnt  |
+----+-----+-------------+----------+---------+
| 0  | 0   | root        | top      |         |
| 1  | 0   | (1 leaf l1) | leaf 1   | top     |
| 2  | 0   | (2 leaf l1) | leaf 2   | top     |
| 3  | 0   | (3 leaf l1) | leaf 3   | top     |
| 4  | 1   | (11 leaf l2)| leaf 21  | leaf 2  |
| 5  | 1   | (12 leaf l2)| leaf 22  | leaf 2  |
| 6  | 1   | (13 leaf l2)| leaf 23  | leaf 2  |
| 7  | 3   | (31 leaf l2)| leaf 211 | leaf 21 |
| 8  | 3   | (32 leaf l2)| leaf 212 | leaf 21 |
+----+-----+-------------+----------+---------+
</pre>
<p># SELECT * FROM data CONNECT BY PRIOR id = pnt START WITH id=0;

<p>output:
<pre>
 id | pnt |    data     | _level_
----+-----+-------------+---------
 0  | 0   | root        | 1
 1  | 0   | (1 leaf l1) | 2
 4  | 1   | (11 leaf l2)| 3
 5  | 1   | (12 leaf l2)| 3
 6  | 1   | (13 leaf l2)| 3
 2  | 0   | (2 leaf l1) | 2
 3  | 0   | (3 leaf l1) | 2
 7  | 3   | (31 leaf l2)| 3
 8  | 3   | (32 leaf l2)| 3
</pre>
<p># create sequence tseq;
<br># SELECT nextval('tseq') as _id , PRIOR nextval('tseq') as _pnt, c_id, c_pnt, _level_ as lvl
  FROM data CONNECT BY PRIOR c_id = c_pnt START WITH c_id='top';
<p>output:
<pre>
 _id | _pnt |   c_id     | c_pnt | lvl
-----+------+----------+---------+----
 1   |      | top      |         | 1
 2   | 1    | leaf 1   | top     | 2
 3   | 1    | leaf 2   | top     | 2
 4   | 3    | leaf 21  | leaf 2  | 3
 5   | 4    | leaf 211 | leaf 21 | 4
 6   | 4    | leaf 212 | leaf 21 | 4
 7   | 3    | leaf 22  | leaf 2  | 3
 8   | 3    | leaf 23  | leaf 2  | 3
 9   | 1    | leaf 3   | top     | 2
</pre>
<br><small>notice: trees based on id/pnt and c_id/c_pnt are different.
<p><b>DESCRIPTION</b>

<p>Hierarchical query.

<p>Lets tree is like:
<pre>
                          (root)
                        /   |    \
                      /     |      \
             (1 leaf l1) (2 leaf l1) (3 leaf l1)
            /    |    \                   |     \
          /      |      \                 |       \
(11 leaf l2) (12 leaf l2) (13 leaf l2) (31 leaf l2) (32 leaf l2)
</pre><br>
so lets define hierarchical query as query which return us a set like:
<pre>
+------------+
|root        |
|(1 leaf l1) |
|(11 leaf l2)|
|(12 leaf l2)|
|(13 leaf l2)|
|(2 leaf l1) |
|(3 leaf l1) |
|(31 leaf l2)|
|(32 leaf l2)|
+------------+
</pre><br>
i.e. first is root,then first child of root,
then first child of first child, if any, or second child otherwise, ... so on.

<p><b>REASON</b>.

<p>Often hierarchical queries are made by adding special field which stores a position
of a row in the tree, and then make "SELECT ... ORDER BY 'hier_position_field'"
over the table. disability of such approach is that we can't sort leaves in some
custom order.

<p>This patch is based on internal PG's query processing and havn't such disadvantage.

<p><b>SYNTAX</b>.
<pre>
SELECT t_expr, PRIOR t_expr [ AS alias ], ... FROM ... [ WHERE condition ] hier_clause
  [ HAVING condition [, ...]] [ ORDER BY ... ] [ LIMIT ... ] [ OFFSET ... ]

hier_clause: connect_clause start_with_clause
                | start_with_clause connect_clause
                | /* EMPTY */
                ;
connect_clause: CONNECT BY PRIOR c_expr qual_Op c_expr
                | CONNECT BY c_expr qual_Op PRIOR c_expr
                ;
start_with_clause: START WITH a_expr
                ;
</pre><br>
... means the same as usual SELECT<br>
qual_Op is an operator.<br>
c_expr is a column name or function call<br>
expr is a WHERE-like expression<br>
t_expr is a valid target list expression

<ul>
<li>WHERE condition
<blockquote>only rows which pass condition will be used

</blockquote>
<li>CONNECT BY PRIOR c_expr qual_Op c_expr <br>
CONNECT BY c_expr qual_Op PRIOR c_expr
<blockquote>    expression next to PRIOR is evaluated against parent tuple, another c_expr - against        child tuple. qual_Op is an operator for comparation, if results of evaluation
        is equal then tuples will be connected.<br>
        qual_Op is not only '=', it may be any comparation operator for types of given expressions.
<br>
        for cases with different parent and child expressions: operator's function is called
                op_func(child_expression, parent_expression).<br>
        for user-defined operators: operator's function must return 0 if values are equal,
          !0 otherwise.<br>
        EX.: CONNECT BY PRIOR id = pnt<br>
        rows will be connected by parent 'id' and child 'pnt' columns.<br>
        i.e. if in some row (A) column 'pnt' is equal to 'id' column of other row (B)<br>
        means that row A is a child of B.<br>

</blockquote>
<li>START WITH expr
<blockquote>rows for which expr is true will be treaten as root rows and other will
        be connected to them.

</blockquote>
<li>HAVING condition
<blockquote>used to qualifying rows after building hierarchy. only which satisfy condition will be returned.

</blockquote>
<li>ORDER BY ...
<blockquote>all childs of any parent will be ordered in choosen order. rows can't be ordered by _level_
        within same select where they're connected, use
        SELECT ... FROM (SELECT ... CONNECT ...) p ORDER BY _level_
        construction.
</blockquote>
<li>PRIOR t_expr (in the target list)
<blockquote> selects value of t_expr from parent row. Can be useful for generating IDs on the fly,
and referencing to them. t_expr must be present in target list.
</ul>
<b>Warn!</b> Aggregates can't be used with CONNECT BY clause.

<p><b>RESULTS</b>.

<p>query returns sets like discribed in synopsis. '_level_' is additional column which
added only in case of hierarchical query.
it means deep of row in the tree, starts from 1.
from version 0.4 and since it can be selected in target list and aliased there.
see 2nd example above.

<p>Difference with Oracle's hierarchical queries:
        WHERE clause evaluated BEFORE connecting.
        for qualifying rows after they been connected use HAVING.

<p><b>MISC</b>.
<p>Subqueries, views and cursors are supported. <br>
initdb is required<br>
Feedback is welcome:)
<p><b>CHANGES</b>.
<p>v 0.5<br>
<ul>
<li> v 0.5.1 fixed silly, but serious bug.
<li> speed improvement. when connOp is '=' or '==', assume this is equality operator,
in such cases used new alorithm which uses hash table. processing speed is comparable to
sorting and can be serveral times faster than with old algorithm.<br>
in other cases of connOp old algorithm is used.
</ul>
<p>v 0.4<br>
<ul>
<li> added PRIOR support
<li> '_level_' column now can be aliased in target list.
</ul>
<p>v 0.3<br>
<ul>
<li>fixed bugs which prevented of using cursors
<li>fixed HAVING bug
<li>fixed typos in readme
</ul>
<p>v 0.2<br>
<ul>
<li>fixed bug which prevents selecting over 1024 rows
<li>fixed troubles with non-numeric type of columns on which connect is performed
<li>speed imrovement
</ul>
<p>v 0.1<br>
<ul>
<li>first release.
</ul>
<!--#include file="bottom.html" -->