rows, and a parent-key field that references the
    parent (if any) of each row.  <function>connectby</function> can display the
    sub-tree descending from any row.
   </para>

   <para>
    <xref linkend="tablefunc-connectby-parameters"/> explains the
    parameters.
   </para>

   <table id="tablefunc-connectby-parameters">
    <title><function>connectby</function> Parameters</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Parameter</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><parameter>relname</parameter></entry>
       <entry>Name of the source relation</entry>
      </row>
      <row>
       <entry><parameter>keyid_fld</parameter></entry>
       <entry>Name of the key field</entry>
      </row>
      <row>
       <entry><parameter>parent_keyid_fld</parameter></entry>
       <entry>Name of the parent-key field</entry>
      </row>
      <row>
       <entry><parameter>orderby_fld</parameter></entry>
       <entry>Name of the field to order siblings by (optional)</entry>
      </row>
      <row>
       <entry><parameter>start_with</parameter></entry>
       <entry>Key value of the row to start at</entry>
      </row>
      <row>
       <entry><parameter>max_depth</parameter></entry>
       <entry>Maximum depth to descend to, or zero for unlimited depth</entry>
      </row>
      <row>
       <entry><parameter>branch_delim</parameter></entry>
       <entry>String to separate keys with in branch output (optional)</entry>
      </row>
      </tbody>
     </tgroup>
    </table>

    <para>
     The key and parent-key fields can be any data type, but they must be
     the same type.  Note that the <parameter>start_with</parameter> value must be
     entered as a text string, regardless of the type of the key field.
    </para>

    <para>
     The <function>connectby</function> function is declared to return <type>setof
     record</type>, so the actual names and types of the output columns must be
     defined in the <literal>FROM</literal> clause of the calling <command>SELECT</command>
     statement, for example:
    </para>

<programlisting>
SELECT * FROM connectby('connectby_tree', 'keyid', 'parent_keyid', 'pos', 'row2', 0, '~')
    AS t(keyid text, parent_keyid text, level int, branch text, pos int);
</programlisting>

    <para>
     The first two output columns are used for the current row's key and
     its parent row's key; they must match the type of the table's key field.
     The third output column is the depth in the tree and must be of type
     <type>integer</type>.  If a <parameter>branch_delim</parameter> parameter was
     given, the next output column is the branch display and must be of type
     <type>text</type>.  Finally, if an <parameter>orderby_fld</parameter>
     parameter was given, the last output column is a serial number, and must
     be of type <type>integer</type>.
    </para>

    <para>
     The <quote>branch</quote> output column shows the path of keys taken to
     reach the current row.  The keys are separated by the specified
     <parameter>branch_delim</parameter> string.  If no branch display is
     wanted, omit both the <parameter>branch_delim</parameter> parameter
     and the branch column in the output column list.
    </para>

    <para>
     If the ordering of siblings of the same parent is important,
     include the <parameter>orderby_fld</parameter> parameter to
     specify which field to order siblings by.  This field can be of any
     sortable data type.  The output column list must include a final
     integer serial-number column, if and only if
     <parameter>orderby_fld</parameter> is specified.
    </para>

    <para>
     The parameters representing table and field names are copied as-is
     into the SQL