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

<sect1 id="ltree" xreflabel="ltree">
 <title>ltree &mdash; hierarchical tree-like data type</title>

 <indexterm zone="ltree">
  <primary>ltree</primary>
 </indexterm>

 <para>
  This module implements a data type <type>ltree</type> for representing
  labels of data stored in a hierarchical tree-like structure.
  Extensive facilities for searching through label trees are provided.
 </para>

 <para>
  This module is considered <quote>trusted</quote>, that is, it can be
  installed by non-superusers who have <literal>CREATE</literal> privilege
  on the current database.
 </para>

 <sect2 id="ltree-definitions">
  <title>Definitions</title>

  <para>
   A <firstterm>label</firstterm> is a sequence of alphanumeric characters,
   underscores, and hyphens. Valid alphanumeric character ranges are
   dependent on the database locale. For example, in C locale, the characters
   <literal>A-Za-z0-9_-</literal> are allowed.
   Labels must be no more than 1000 characters long.
  </para>

  <para>
   Examples: <literal>42</literal>, <literal>Personal_Services</literal>
  </para>

  <para>
   A <firstterm>label path</firstterm> is a sequence of zero or more
   labels separated by dots, for example <literal>L1.L2.L3</literal>, representing
   a path from the root of a hierarchical tree to a particular node.  The
   length of a label path cannot exceed 65535 labels.
  </para>

  <para>
   Example: <literal>Top.Countries.Europe.Russia</literal>
  </para>

  <para>
   The <filename>ltree</filename> module provides several data types:
  </para>

  <itemizedlist>
   <listitem>
    <para>
     <type>ltree</type> stores a label path.
    </para>
   </listitem>

   <listitem>
    <para>
     <type>lquery</type> represents a regular-expression-like pattern
     for matching <type>ltree</type> values.  A simple word matches that
     label within a path.  A star symbol (<literal>*</literal>) matches zero
     or more labels.  These can be joined with dots to form a pattern that
     must match the whole label path.  For example:
<synopsis>
foo         <lineannotation>Match the exact label path <literal>foo</literal></lineannotation>
*.foo.*     <lineannotation>Match any label path containing the label <literal>foo</literal></lineannotation>
*.foo       <lineannotation>Match any label path whose last label is <literal>foo</literal></lineannotation>
</synopsis>
    </para>

    <para>
     Both star symbols and simple words can be quantified to restrict how many
     labels they can match:
<synopsis>
*{<replaceable>n</replaceable>}        <lineannotation>Match exactly <replaceable>n</replaceable> labels</lineannotation>
*{<replaceable>n</replaceable>,}       <lineannotation>Match at least <replaceable>n</replaceable> labels</lineannotation>
*{<replaceable>n</replaceable>,<replaceable>m</replaceable>}      <lineannotation>Match at least <replaceable>n</replaceable> but not more than <replaceable>m</replaceable> labels</lineannotation>
*{,<replaceable>m</replaceable>}       <lineannotation>Match at most <replaceable>m</replaceable> labels &mdash; same as </lineannotation>*{0,<replaceable>m</replaceable>}
foo{<replaceable>n</replaceable>,<replaceable>m</replaceable>}    <lineannotation>Match at least <replaceable>n</replaceable> but not more than <replaceable>m</replaceable> occurrences of <literal>foo</literal></lineannotation>
foo{,}      <lineannotation>Match any number of occurrences of <literal>foo</literal>, including zero</lineannotation>
</synopsis>
     In the absence of any explicit quantifier, the default for a star symbol
     is to match any number of labels (that is, <literal>{,}</literal>) while
     the default for a non-star item is to match exactly once (that
     is, <literal>{1}</literal>).
    </para>

    <para>
     There are several modifiers that can be put at the end of a non-star
     <type>lquery</type> item to make it match more than just the exact match:
<synopsis>
@           <lineannotation>Match