begriffs open source - ai-pg/blob - full-docs/src/sgml/html/ltree.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.22. ltree — hierarchical tree-like data type</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="lo.html" title="F.21. lo — manage large objects" /><link rel="next" href="pageinspect.html" title="F.23. pageinspect — low-level inspection of database pages" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.22. ltree — hierarchical tree-like data type</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="lo.html" title="F.21. lo — manage large objects">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules and Extensions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="pageinspect.html" title="F.23. pageinspect — low-level inspection of database pages">Next</a></td></tr></table><hr /></div><div class="sect1" id="LTREE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.22. ltree — hierarchical tree-like data type <a href="#LTREE" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ltree.html#LTREE-DEFINITIONS">F.22.1. Definitions</a></span></dt><dt><span class="sect2"><a href="ltree.html#LTREE-OPS-FUNCS">F.22.2. Operators and Functions</a></span></dt><dt><span class="sect2"><a href="ltree.html#LTREE-INDEXES">F.22.3. Indexes</a></span></dt><dt><span class="sect2"><a href="ltree.html#LTREE-EXAMPLE">F.22.4. Example</a></span></dt><dt><span class="sect2"><a href="ltree.html#LTREE-TRANSFORMS">F.22.5. Transforms</a></span></dt><dt><span class="sect2"><a href="ltree.html#LTREE-AUTHORS">F.22.6. Authors</a></span></dt></dl></div><a id="id-1.11.7.32.2" class="indexterm"></a><p>
   3   This module implements a data type <code class="type">ltree</code> for representing
   4   labels of data stored in a hierarchical tree-like structure.
   5   Extensive facilities for searching through label trees are provided.
   6  </p><p>
   7   This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
   8   installed by non-superusers who have <code class="literal">CREATE</code> privilege
   9   on the current database.
  10  </p><div class="sect2" id="LTREE-DEFINITIONS"><div class="titlepage"><div><div><h3 class="title">F.22.1. Definitions <a href="#LTREE-DEFINITIONS" class="id_link">#</a></h3></div></div></div><p>
  11    A <em class="firstterm">label</em> is a sequence of alphanumeric characters,
  12    underscores, and hyphens. Valid alphanumeric character ranges are
  13    dependent on the database locale. For example, in C locale, the characters
  14    <code class="literal">A-Za-z0-9_-</code> are allowed.
  15    Labels must be no more than 1000 characters long.
  16   </p><p>
  17    Examples: <code class="literal">42</code>, <code class="literal">Personal_Services</code>
  18   </p><p>
  19    A <em class="firstterm">label path</em> is a sequence of zero or more
  20    labels separated by dots, for example <code class="literal">L1.L2.L3</code>, representing
  21    a path from the root of a hierarchical tree to a particular node.  The
  22    length of a label path cannot exceed 65535 labels.
  23   </p><p>
  24    Example: <code class="literal">Top.Countries.Europe.Russia</code>
  25   </p><p>
  26    The <code class="filename">ltree</code> module provides several data types:
  27   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  28      <code class="type">ltree</code> stores a label path.
  29     </p></li><li class="listitem"><p>
  30      <code class="type">lquery</code> represents a regular-expression-like pattern
  31      for matching <code class="type">ltree</code> values.  A simple word matches that
  32      label within a path.  A star symbol (<code class="literal">*</code>) matches zero
  33      or more labels.  These can be joined with dots to form a pattern that
  34      must match the whole label path.  For example:
  35 </p><pre class="synopsis">
  36 foo         <em class="lineannotation"><span class="lineannotation">Match the exact label path <code class="literal">foo</code></span></em>
  37 *.foo.*     <em class="lineannotation"><span class="lineannotation">Match any label path containing the label <code class="literal">foo</code></span></em>
  38 *.foo       <em class="lineannotation"><span class="lineannotation">Match any label path whose last label is <code class="literal">foo</code></span></em>
  39 </pre><p>
  40     </p><p>
  41      Both star symbols and simple words can be quantified to restrict how many
  42      labels they can match:
  43 </p><pre class="synopsis">
  44 *{<em class="replaceable"><code>n</code></em>}        <em class="lineannotation"><span class="lineannotation">Match exactly <em class="replaceable"><code>n</code></em> labels</span></em>
  45 *{<em class="replaceable"><code>n</code></em>,}       <em class="lineannotation"><span class="lineannotation">Match at least <em class="replaceable"><code>n</code></em> labels</span></em>
  46 *{<em class="replaceable"><code>n</code></em>,<em class="replaceable"><code>m</code></em>}      <em class="lineannotation"><span class="lineannotation">Match at least <em class="replaceable"><code>n</code></em> but not more than <em class="replaceable"><code>m</code></em> labels</span></em>
  47 *{,<em class="replaceable"><code>m</code></em>}       <em class="lineannotation"><span class="lineannotation">Match at most <em class="replaceable"><code>m</code></em> labels — same as </span></em>*{0,<em class="replaceable"><code>m</code></em>}
  48 foo{<em class="replaceable"><code>n</code></em>,<em class="replaceable"><code>m</code></em>}    <em class="lineannotation"><span class="lineannotation">Match at least <em class="replaceable"><code>n</code></em> but not more than <em class="replaceable"><code>m</code></em> occurrences of <code class="literal">foo</code></span></em>
  49 foo{,}      <em class="lineannotation"><span class="lineannotation">Match any number of occurrences of <code class="literal">foo</code>, including zero</span></em>
  50 </pre><p>
  51      In the absence of any explicit quantifier, the default for a star symbol
  52      is to match any number of labels (that is, <code class="literal">{,}</code>) while
  53      the default for a non-star item is to match exactly once (that
  54      is, <code class="literal">{1}</code>).
  55     </p><p>
  56      There are several modifiers that can be put at the end of a non-star
  57      <code class="type">lquery</code> item to make it match more than just the exact match:
  58 </p><pre class="synopsis">
  59 @           <em class="lineannotation"><span class="lineannotation">Match case-insensitively, for example <code class="literal">a@</code> matches <code class="literal">A</code></span></em>
  60 *           <em class="lineannotation"><span class="lineannotation">Match any label with this prefix, for example <code class="literal">foo*</code> matches <code class="literal">foobar</code></span></em>
  61 %           <em class="lineannotation"><span class="lineannotation">Match initial underscore-separated words</span></em>
  62 </pre><p>
  63      The behavior of <code class="literal">%</code> is a bit complicated.  It tries to match
  64      words rather than the entire label.  For example
  65      <code class="literal">foo_bar%</code> matches <code class="literal">foo_bar_baz</code> but not
  66      <code class="literal">foo_barbaz</code>.  If combined with <code class="literal">*</code>, prefix
  67      matching applies to each word separately, for example
  68      <code class="literal">foo_bar%*</code> matches <code class="literal">foo1_bar2_baz</code> but
  69      not <code class="literal">foo1_br2_baz</code>.
  70     </p><p>
  71      Also, you can write several possibly-modified non-star items separated with
  72      <code class="literal">|</code> (OR) to match any of those items, and you can put
  73      <code class="literal">!</code> (NOT) at the start of a non-star group to match any
  74      label that doesn't match any of the alternatives.  A quantifier, if any,
  75      goes at the end of the group; it means some number of matches for the
  76      group as a whole (that is, some number of labels matching or not matching
  77      any of the alternatives).
  78     </p><p>
  79      Here's an annotated example of <code class="type">lquery</code>:
  80 </p><pre class="programlisting">
  81 Top.*{0,2}.sport*@.!football|tennis{1,}.Russ*|Spain
  82 a.  b.     c.      d.                   e.
  83 </pre><p>
  84      This query will match any label path that:
  85     </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>
  86        begins with the label <code class="literal">Top</code>
  87       </p></li><li class="listitem"><p>
  88        and next has zero to two labels before
  89       </p></li><li class="listitem"><p>
  90        a label beginning with the case-insensitive prefix <code class="literal">sport</code>
  91       </p></li><li class="listitem"><p>
  92        then has one or more labels, none of which
  93        match <code class="literal">football</code> nor <code class="literal">tennis</code>
  94       </p></li><li class="listitem"><p>
  95        and then ends with a label beginning with <code class="literal">Russ</code> or
  96        exactly matching <code class="literal">Spain</code>.
  97       </p></li></ol></div></li><li class="listitem"><p><code class="type">ltxtquery</code> represents a full-text-search-like
  98     pattern for matching <code class="type">ltree</code> values.  An
  99     <code class="type">ltxtquery</code> value contains words, possibly with the
 100     modifiers <code class="literal">@</code>, <code class="literal">*</code>, <code class="literal">%</code> at the end;
 101     the modifiers have the same meanings as in <code class="type">lquery</code>.
 102     Words can be combined with <code class="literal">&amp;</code> (AND),
 103     <code class="literal">|</code> (OR), <code class="literal">!</code> (NOT), and parentheses.
 104     The key difference from
 105     <code class="type">lquery</code> is that <code class="type">ltxtquery</code> matches words without
 106     regard to their position in the label path.
 107     </p><p>
 108      Here's an example <code class="type">ltxtquery</code>:
 109 </p><pre class="programlisting">
 110 Europe &amp; Russia*@ &amp; !Transportation
 111 </pre><p>
 112      This will match paths that contain the label <code class="literal">Europe</code> and
 113      any label beginning with <code class="literal">Russia</code> (case-insensitive),
 114      but not paths containing the label <code class="literal">Transportation</code>.
 115      The location of these words within the path is not important.
 116      Also, when <code class="literal">%</code> is used, the word can be matched to any
 117      underscore-separated word within a label, regardless of position.
 118     </p></li></ul></div><p>
 119    Note: <code class="type">ltxtquery</code> allows whitespace between symbols, but
 120    <code class="type">ltree</code> and <code class="type">lquery</code> do not.
 121   </p></div><div class="sect2" id="LTREE-OPS-FUNCS"><div class="titlepage"><div><div><h3 class="title">F.22.2. Operators and Functions <a href="#LTREE-OPS-FUNCS" class="id_link">#</a></h3></div></div></div><p>
 122    Type <code class="type">ltree</code> has the usual comparison operators
 123    <code class="literal">=</code>, <code class="literal">&lt;&gt;</code>,
 124    <code class="literal">&lt;</code>, <code class="literal">&gt;</code>, <code class="literal">&lt;=</code>, <code class="literal">&gt;=</code>.
 125    Comparison sorts in the order of a tree traversal, with the children
 126    of a node sorted by label text.  In addition, the specialized
 127    operators shown in <a class="xref" href="ltree.html#LTREE-OP-TABLE" title="Table F.12. ltree Operators">Table F.12</a> are available.
 128   </p><div class="table" id="LTREE-OP-TABLE"><p class="title"><strong>Table F.12. <code class="type">ltree</code> Operators</strong></p><div class="table-contents"><table class="table" summary="ltree Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
 129         Operator
 130        </p>
 131        <p>
 132         Description
 133        </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
 134         <code class="type">ltree</code> <code class="literal">@&gt;</code> <code class="type">ltree</code>
 135         → <code class="returnvalue">boolean</code>
 136        </p>
 137        <p>
 138         Is left argument an ancestor of right (or equal)?
 139        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 140         <code class="type">ltree</code> <code class="literal">&lt;@</code> <code class="type">ltree</code>
 141         → <code class="returnvalue">boolean</code>
 142        </p>
 143        <p>
 144         Is left argument a descendant of right (or equal)?
 145        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 146         <code class="type">ltree</code> <code class="literal">~</code> <code class="type">lquery</code>
 147         → <code class="returnvalue">boolean</code>
 148        </p>
 149        <p class="func_signature">
 150         <code class="type">lquery</code> <code class="literal">~</code> <code class="type">ltree</code>
 151         → <code class="returnvalue">boolean</code>
 152        </p>
 153        <p>
 154         Does <code class="type">ltree</code> match <code class="type">lquery</code>?
 155        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 156         <code class="type">ltree</code> <code class="literal">?</code> <code class="type">lquery[]</code>
 157         → <code class="returnvalue">boolean</code>
 158        </p>
 159        <p class="func_signature">
 160         <code class="type">lquery[]</code> <code class="literal">?</code> <code class="type">ltree</code>
 161         → <code class="returnvalue">boolean</code>
 162        </p>
 163        <p>
 164         Does <code class="type">ltree</code> match any <code class="type">lquery</code> in array?
 165        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 166         <code class="type">ltree</code> <code class="literal">@</code> <code class="type">ltxtquery</code>
 167         → <code class="returnvalue">boolean</code>
 168        </p>
 169        <p class="func_signature">
 170         <code class="type">ltxtquery</code> <code class="literal">@</code> <code class="type">ltree</code>
 171         → <code class="returnvalue">boolean</code>
 172        </p>
 173        <p>
 174         Does <code class="type">ltree</code> match <code class="type">ltxtquery</code>?
 175        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 176         <code class="type">ltree</code> <code class="literal">||</code> <code class="type">ltree</code>
 177         → <code class="returnvalue">ltree</code>
 178        </p>
 179        <p>
 180         Concatenates <code class="type">ltree</code> paths.
 181        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 182         <code class="type">ltree</code> <code class="literal">||</code> <code class="type">text</code>
 183         → <code class="returnvalue">ltree</code>
 184        </p>
 185        <p class="func_signature">
 186         <code class="type">text</code> <code class="literal">||</code> <code class="type">ltree</code>
 187         → <code class="returnvalue">ltree</code>
 188        </p>
 189        <p>
 190         Converts text to <code class="type">ltree</code> and concatenates.
 191        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 192         <code class="type">ltree[]</code> <code class="literal">@&gt;</code> <code class="type">ltree</code>
 193         → <code class="returnvalue">boolean</code>
 194        </p>
 195        <p class="func_signature">
 196         <code class="type">ltree</code> <code class="literal">&lt;@</code> <code class="type">ltree[]</code>
 197         → <code class="returnvalue">boolean</code>
 198        </p>
 199        <p>
 200         Does array contain an ancestor of <code class="type">ltree</code>?
 201        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 202         <code class="type">ltree[]</code> <code class="literal">&lt;@</code> <code class="type">ltree</code>
 203         → <code class="returnvalue">boolean</code>
 204        </p>
 205        <p class="func_signature">
 206         <code class="type">ltree</code> <code class="literal">@&gt;</code> <code class="type">ltree[]</code>
 207         → <code class="returnvalue">boolean</code>
 208        </p>
 209        <p>
 210         Does array contain a descendant of <code class="type">ltree</code>?
 211        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 212         <code class="type">ltree[]</code> <code class="literal">~</code> <code class="type">lquery</code>
 213         → <code class="returnvalue">boolean</code>
 214        </p>
 215        <p class="func_signature">
 216         <code class="type">lquery</code> <code class="literal">~</code> <code class="type">ltree[]</code>
 217         → <code class="returnvalue">boolean</code>
 218        </p>
 219        <p>
 220         Does array contain any path matching <code class="type">lquery</code>?
 221        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 222         <code class="type">ltree[]</code> <code class="literal">?</code> <code class="type">lquery[]</code>
 223         → <code class="returnvalue">boolean</code>
 224        </p>
 225        <p class="func_signature">
 226         <code class="type">lquery[]</code> <code class="literal">?</code> <code class="type">ltree[]</code>
 227         → <code class="returnvalue">boolean</code>
 228        </p>
 229        <p>
 230         Does <code class="type">ltree</code> array contain any path matching
 231         any <code class="type">lquery</code>?
 232        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 233         <code class="type">ltree[]</code> <code class="literal">@</code> <code class="type">ltxtquery</code>
 234         → <code class="returnvalue">boolean</code>
 235        </p>
 236        <p class="func_signature">
 237         <code class="type">ltxtquery</code> <code class="literal">@</code> <code class="type">ltree[]</code>
 238         → <code class="returnvalue">boolean</code>
 239        </p>
 240        <p>
 241         Does array contain any path matching <code class="type">ltxtquery</code>?
 242        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 243         <code class="type">ltree[]</code> <code class="literal">?@&gt;</code> <code class="type">ltree</code>
 244         → <code class="returnvalue">ltree</code>
 245        </p>
 246        <p>
 247         Returns first array entry that is an ancestor of <code class="type">ltree</code>,
 248         or <code class="literal">NULL</code> if none.
 249        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 250         <code class="type">ltree[]</code> <code class="literal">?&lt;@</code> <code class="type">ltree</code>
 251         → <code class="returnvalue">ltree</code>
 252        </p>
 253        <p>
 254         Returns first array entry that is a descendant of <code class="type">ltree</code>,
 255         or <code class="literal">NULL</code> if none.
 256        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 257         <code class="type">ltree[]</code> <code class="literal">?~</code> <code class="type">lquery</code>
 258         → <code class="returnvalue">ltree</code>
 259        </p>
 260        <p>
 261         Returns first array entry that matches <code class="type">lquery</code>,
 262         or <code class="literal">NULL</code> if none.
 263        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 264         <code class="type">ltree[]</code> <code class="literal">?@</code> <code class="type">ltxtquery</code>
 265         → <code class="returnvalue">ltree</code>
 266        </p>
 267        <p>
 268         Returns first array entry that matches <code class="type">ltxtquery</code>,
 269         or <code class="literal">NULL</code> if none.
 270        </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
 271    The operators <code class="literal">&lt;@</code>, <code class="literal">@&gt;</code>,
 272    <code class="literal">@</code> and <code class="literal">~</code> have analogues
 273    <code class="literal">^&lt;@</code>, <code class="literal">^@&gt;</code>, <code class="literal">^@</code>,
 274    <code class="literal">^~</code>, which are the same except they do not use
 275    indexes.  These are useful only for testing purposes.
 276   </p><p>
 277    The available functions are shown in <a class="xref" href="ltree.html#LTREE-FUNC-TABLE" title="Table F.13. ltree Functions">Table F.13</a>.
 278   </p><div class="table" id="LTREE-FUNC-TABLE"><p class="title"><strong>Table F.13. <code class="type">ltree</code> Functions</strong></p><div class="table-contents"><table class="table" summary="ltree Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
 279         Function
 280        </p>
 281        <p>
 282         Description
 283        </p>
 284        <p>
 285         Example(s)
 286        </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
 287         <a id="id-1.11.7.32.6.6.2.2.1.1.1.1" class="indexterm"></a>
 288         <code class="function">subltree</code> ( <code class="type">ltree</code>, <em class="parameter"><code>start</code></em> <code class="type">integer</code>, <em class="parameter"><code>end</code></em> <code class="type">integer</code> )
 289         → <code class="returnvalue">ltree</code>
 290        </p>
 291        <p>
 292         Returns subpath of <code class="type">ltree</code> from
 293         position <em class="parameter"><code>start</code></em> to
 294         position <em class="parameter"><code>end</code></em>-1 (counting from 0).
 295        </p>
 296        <p>
 297         <code class="literal">subltree('Top.Child1.Child2', 1, 2)</code>
 298         → <code class="returnvalue">Child1</code>
 299        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 300         <a id="id-1.11.7.32.6.6.2.2.2.1.1.1" class="indexterm"></a>
 301         <code class="function">subpath</code> ( <code class="type">ltree</code>, <em class="parameter"><code>offset</code></em> <code class="type">integer</code>, <em class="parameter"><code>len</code></em> <code class="type">integer</code> )
 302         → <code class="returnvalue">ltree</code>
 303        </p>
 304        <p>
 305         Returns subpath of <code class="type">ltree</code> starting at
 306         position <em class="parameter"><code>offset</code></em>, with
 307         length <em class="parameter"><code>len</code></em>.  If <em class="parameter"><code>offset</code></em>
 308         is negative, subpath starts that far from the end of the path.
 309         If <em class="parameter"><code>len</code></em> is negative, leaves that many labels off
 310         the end of the path.
 311        </p>
 312        <p>
 313         <code class="literal">subpath('Top.Child1.Child2', 0, 2)</code>
 314         → <code class="returnvalue">Top.Child1</code>
 315        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 316         <code class="function">subpath</code> ( <code class="type">ltree</code>, <em class="parameter"><code>offset</code></em> <code class="type">integer</code> )
 317         → <code class="returnvalue">ltree</code>
 318        </p>
 319        <p>
 320         Returns subpath of <code class="type">ltree</code> starting at
 321         position <em class="parameter"><code>offset</code></em>, extending to end of path.
 322         If <em class="parameter"><code>offset</code></em> is negative, subpath starts that far
 323         from the end of the path.
 324        </p>
 325        <p>
 326         <code class="literal">subpath('Top.Child1.Child2', 1)</code>
 327         → <code class="returnvalue">Child1.Child2</code>
 328        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 329         <a id="id-1.11.7.32.6.6.2.2.4.1.1.1" class="indexterm"></a>
 330         <code class="function">nlevel</code> ( <code class="type">ltree</code> )
 331         → <code class="returnvalue">integer</code>
 332        </p>
 333        <p>
 334         Returns number of labels in path.
 335        </p>
 336        <p>
 337         <code class="literal">nlevel('Top.Child1.Child2')</code>
 338         → <code class="returnvalue">3</code>
 339        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 340         <a id="id-1.11.7.32.6.6.2.2.5.1.1.1" class="indexterm"></a>
 341         <code class="function">index</code> ( <em class="parameter"><code>a</code></em> <code class="type">ltree</code>, <em class="parameter"><code>b</code></em> <code class="type">ltree</code> )
 342         → <code class="returnvalue">integer</code>
 343        </p>
 344        <p>
 345         Returns position of first occurrence of <em class="parameter"><code>b</code></em> in
 346         <em class="parameter"><code>a</code></em>, or -1 if not found.
 347        </p>
 348        <p>
 349         <code class="literal">index('0.1.2.3.5.4.5.6.8.5.6.8', '5.6')</code>
 350         → <code class="returnvalue">6</code>
 351        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 352         <code class="function">index</code> ( <em class="parameter"><code>a</code></em> <code class="type">ltree</code>,  <em class="parameter"><code>b</code></em> <code class="type">ltree</code>, <em class="parameter"><code>offset</code></em> <code class="type">integer</code> )
 353         → <code class="returnvalue">integer</code>
 354        </p>
 355        <p>
 356         Returns position of first occurrence of <em class="parameter"><code>b</code></em>
 357         in <em class="parameter"><code>a</code></em>, or -1 if not found.  The search starts at
 358         position <em class="parameter"><code>offset</code></em>;
 359         negative <em class="parameter"><code>offset</code></em> means
 360         start <em class="parameter"><code>-offset</code></em> labels from the end of the path.
 361        </p>
 362        <p>
 363         <code class="literal">index('0.1.2.3.5.4.5.6.8.5.6.8', '5.6', -4)</code>
 364         → <code class="returnvalue">9</code>
 365        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 366         <a id="id-1.11.7.32.6.6.2.2.7.1.1.1" class="indexterm"></a>
 367         <code class="function">text2ltree</code> ( <code class="type">text</code> )
 368         → <code class="returnvalue">ltree</code>
 369        </p>
 370        <p>
 371         Casts <code class="type">text</code> to <code class="type">ltree</code>.
 372        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 373         <a id="id-1.11.7.32.6.6.2.2.8.1.1.1" class="indexterm"></a>
 374         <code class="function">ltree2text</code> ( <code class="type">ltree</code> )
 375         → <code class="returnvalue">text</code>
 376        </p>
 377        <p>
 378         Casts <code class="type">ltree</code> to <code class="type">text</code>.
 379        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 380         <a id="id-1.11.7.32.6.6.2.2.9.1.1.1" class="indexterm"></a>
 381         <code class="function">lca</code> ( <code class="type">ltree</code> [<span class="optional">, <code class="type">ltree</code> [<span class="optional">, ... </span>]</span>] )
 382         → <code class="returnvalue">ltree</code>
 383        </p>
 384        <p>
 385         Computes longest common ancestor of paths
 386         (up to 8 arguments are supported).
 387        </p>
 388        <p>
 389         <code class="literal">lca('1.2.3', '1.2.3.4.5.6')</code>
 390         → <code class="returnvalue">1.2</code>
 391        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 392         <code class="function">lca</code> ( <code class="type">ltree[]</code> )
 393         → <code class="returnvalue">ltree</code>
 394        </p>
 395        <p>
 396         Computes longest common ancestor of paths in array.
 397        </p>
 398        <p>
 399         <code class="literal">lca(array['1.2.3'::ltree,'1.2.3.4'])</code>
 400         → <code class="returnvalue">1.2</code>
 401        </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="LTREE-INDEXES"><div class="titlepage"><div><div><h3 class="title">F.22.3. Indexes <a href="#LTREE-INDEXES" class="id_link">#</a></h3></div></div></div><p>
 402    <code class="filename">ltree</code> supports several types of indexes that can speed
 403    up the indicated operators:
 404   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 405      B-tree index over <code class="type">ltree</code>:
 406      <code class="literal">&lt;</code>, <code class="literal">&lt;=</code>, <code class="literal">=</code>,
 407      <code class="literal">&gt;=</code>, <code class="literal">&gt;</code>
 408     </p></li><li class="listitem"><p>
 409      Hash index over <code class="type">ltree</code>:
 410      <code class="literal">=</code>
 411     </p></li><li class="listitem"><p>
 412      GiST index over <code class="type">ltree</code> (<code class="literal">gist_ltree_ops</code>
 413      opclass):
 414      <code class="literal">&lt;</code>, <code class="literal">&lt;=</code>, <code class="literal">=</code>,
 415      <code class="literal">&gt;=</code>, <code class="literal">&gt;</code>,
 416      <code class="literal">@&gt;</code>, <code class="literal">&lt;@</code>,
 417      <code class="literal">@</code>, <code class="literal">~</code>, <code class="literal">?</code>
 418     </p><p>
 419      <code class="literal">gist_ltree_ops</code> GiST opclass approximates a set of
 420      path labels as a bitmap signature.  Its optional integer parameter
 421      <code class="literal">siglen</code> determines the
 422      signature length in bytes.  The default signature length is 8 bytes.
 423      The length must be a positive multiple of <code class="type">int</code> alignment
 424      (4 bytes on most machines)) up to 2024.  Longer
 425      signatures lead to a more precise search (scanning a smaller fraction of the index and
 426      fewer heap pages), at the cost of a larger index.
 427     </p><p>
 428      Example of creating such an index with the default signature length of 8 bytes:
 429     </p><pre class="programlisting">
 430 CREATE INDEX path_gist_idx ON test USING GIST (path);
 431 </pre><p>
 432      Example of creating such an index with a signature length of 100 bytes:
 433     </p><pre class="programlisting">
 434 CREATE INDEX path_gist_idx ON test USING GIST (path gist_ltree_ops(siglen=100));
 435 </pre></li><li class="listitem"><p>
 436      GiST index over <code class="type">ltree[]</code> (<code class="literal">gist__ltree_ops</code>
 437      opclass):
 438      <code class="literal">ltree[] &lt;@ ltree</code>, <code class="literal">ltree @&gt; ltree[]</code>,
 439      <code class="literal">@</code>, <code class="literal">~</code>, <code class="literal">?</code>
 440     </p><p>
 441      <code class="literal">gist__ltree_ops</code> GiST opclass works similarly to
 442      <code class="literal">gist_ltree_ops</code> and also takes signature length as
 443      a parameter.  The default value of <code class="literal">siglen</code> in
 444       <code class="literal">gist__ltree_ops</code> is 28 bytes.
 445     </p><p>
 446      Example of creating such an index with the default signature length of 28 bytes:
 447     </p><pre class="programlisting">
 448 CREATE INDEX path_gist_idx ON test USING GIST (array_path);
 449 </pre><p>
 450      Example of creating such an index with a signature length of 100 bytes:
 451     </p><pre class="programlisting">
 452 CREATE INDEX path_gist_idx ON test USING GIST (array_path gist__ltree_ops(siglen=100));
 453 </pre><p>
 454      Note: This index type is lossy.
 455     </p></li></ul></div></div><div class="sect2" id="LTREE-EXAMPLE"><div class="titlepage"><div><div><h3 class="title">F.22.4. Example <a href="#LTREE-EXAMPLE" class="id_link">#</a></h3></div></div></div><p>
 456    This example uses the following data (also available in file
 457    <code class="filename">contrib/ltree/ltreetest.sql</code> in the source distribution):
 458   </p><pre class="programlisting">
 459 CREATE TABLE test (path ltree);
 460 INSERT INTO test VALUES ('Top');
 461 INSERT INTO test VALUES ('Top.Science');
 462 INSERT INTO test VALUES ('Top.Science.Astronomy');
 463 INSERT INTO test VALUES ('Top.Science.Astronomy.Astrophysics');
 464 INSERT INTO test VALUES ('Top.Science.Astronomy.Cosmology');
 465 INSERT INTO test VALUES ('Top.Hobbies');
 466 INSERT INTO test VALUES ('Top.Hobbies.Amateurs_Astronomy');
 467 INSERT INTO test VALUES ('Top.Collections');
 468 INSERT INTO test VALUES ('Top.Collections.Pictures');
 469 INSERT INTO test VALUES ('Top.Collections.Pictures.Astronomy');
 470 INSERT INTO test VALUES ('Top.Collections.Pictures.Astronomy.Stars');
 471 INSERT INTO test VALUES ('Top.Collections.Pictures.Astronomy.Galaxies');
 472 INSERT INTO test VALUES ('Top.Collections.Pictures.Astronomy.Astronauts');
 473 CREATE INDEX path_gist_idx ON test USING GIST (path);
 474 CREATE INDEX path_idx ON test USING BTREE (path);
 475 CREATE INDEX path_hash_idx ON test USING HASH (path);
 476 </pre><p>
 477    Now, we have a table <code class="structname">test</code> populated with data describing
 478    the hierarchy shown below:
 479   </p><pre class="literallayout">
 480                         Top
 481                      /   |  \
 482              Science Hobbies Collections
 483                  /       |              \
 484         Astronomy   Amateurs_Astronomy Pictures
 485            /  \                            |
 486 Astrophysics  Cosmology                Astronomy
 487                                         /  |    \
 488                                  Galaxies Stars Astronauts
 489 </pre><p>
 490    We can do inheritance:
 491 </p><pre class="screen">
 492 ltreetest=&gt; SELECT path FROM test WHERE path &lt;@ 'Top.Science';
 493                 path
 494 ------------------------------------
 495  Top.Science
 496  Top.Science.Astronomy
 497  Top.Science.Astronomy.Astrophysics
 498  Top.Science.Astronomy.Cosmology
 499 (4 rows)
 500 </pre><p>
 501   </p><p>
 502    Here are some examples of path matching:
 503 </p><pre class="screen">
 504 ltreetest=&gt; SELECT path FROM test WHERE path ~ '*.Astronomy.*';
 505                      path
 506 -----------------------------------------------
 507  Top.Science.Astronomy
 508  Top.Science.Astronomy.Astrophysics
 509  Top.Science.Astronomy.Cosmology
 510  Top.Collections.Pictures.Astronomy
 511  Top.Collections.Pictures.Astronomy.Stars
 512  Top.Collections.Pictures.Astronomy.Galaxies
 513  Top.Collections.Pictures.Astronomy.Astronauts
 514 (7 rows)
 515
 516 ltreetest=&gt; SELECT path FROM test WHERE path ~ '*.!pictures@.Astronomy.*';
 517                 path
 518 ------------------------------------
 519  Top.Science.Astronomy
 520  Top.Science.Astronomy.Astrophysics
 521  Top.Science.Astronomy.Cosmology
 522 (3 rows)
 523 </pre><p>
 524   </p><p>
 525    Here are some examples of full text search:
 526 </p><pre class="screen">
 527 ltreetest=&gt; SELECT path FROM test WHERE path @ 'Astro*% &amp; !pictures@';
 528                 path
 529 ------------------------------------
 530  Top.Science.Astronomy
 531  Top.Science.Astronomy.Astrophysics
 532  Top.Science.Astronomy.Cosmology
 533  Top.Hobbies.Amateurs_Astronomy
 534 (4 rows)
 535
 536 ltreetest=&gt; SELECT path FROM test WHERE path @ 'Astro* &amp; !pictures@';
 537                 path
 538 ------------------------------------
 539  Top.Science.Astronomy
 540  Top.Science.Astronomy.Astrophysics
 541  Top.Science.Astronomy.Cosmology
 542 (3 rows)
 543 </pre><p>
 544   </p><p>
 545    Path construction using functions:
 546 </p><pre class="screen">
 547 ltreetest=&gt; SELECT subpath(path,0,2)||'Space'||subpath(path,2) FROM test WHERE path &lt;@ 'Top.Science.Astronomy';
 548                  ?column?
 549 ------------------------------------------
 550  Top.Science.Space.Astronomy
 551  Top.Science.Space.Astronomy.Astrophysics
 552  Top.Science.Space.Astronomy.Cosmology
 553 (3 rows)
 554 </pre><p>
 555   </p><p>
 556    We could simplify this by creating an SQL function that inserts a label
 557    at a specified position in a path:
 558 </p><pre class="screen">
 559 CREATE FUNCTION ins_label(ltree, int, text) RETURNS ltree
 560     AS 'select subpath($1,0,$2) || $3 || subpath($1,$2);'
 561     LANGUAGE SQL IMMUTABLE;
 562
 563 ltreetest=&gt; SELECT ins_label(path,2,'Space') FROM test WHERE path &lt;@ 'Top.Science.Astronomy';
 564                 ins_label
 565 ------------------------------------------
 566  Top.Science.Space.Astronomy
 567  Top.Science.Space.Astronomy.Astrophysics
 568  Top.Science.Space.Astronomy.Cosmology
 569 (3 rows)
 570 </pre><p>
 571   </p></div><div class="sect2" id="LTREE-TRANSFORMS"><div class="titlepage"><div><div><h3 class="title">F.22.5. Transforms <a href="#LTREE-TRANSFORMS" class="id_link">#</a></h3></div></div></div><p>
 572    The <code class="literal">ltree_plpython3u</code> extension implements transforms for
 573    the <code class="type">ltree</code> type for PL/Python. If installed and specified when
 574    creating a function, <code class="type">ltree</code> values are mapped to Python lists.
 575    (The reverse is currently not supported, however.)
 576   </p></div><div class="sect2" id="LTREE-AUTHORS"><div class="titlepage"><div><div><h3 class="title">F.22.6. Authors <a href="#LTREE-AUTHORS" class="id_link">#</a></h3></div></div></div><p>
 577    All work was done by Teodor Sigaev (<code class="email">&lt;<a class="email" href="mailto:teodor@stack.net">teodor@stack.net</a>&gt;</code>) and
 578    Oleg Bartunov (<code class="email">&lt;<a class="email" href="mailto:oleg@sai.msu.su">oleg@sai.msu.su</a>&gt;</code>). See
 579    <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/" target="_top">http://www.sai.msu.su/~megera/postgres/gist/</a> for
 580    additional information. Authors would like to thank Eugeny Rodichev for
 581    helpful discussions. Comments and bug reports are welcome.
 582   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="lo.html" title="F.21. lo — manage large objects">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pageinspect.html" title="F.23. pageinspect — low-level inspection of database pages">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.21. lo — manage large objects </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.23. pageinspect — low-level inspection of database pages</td></tr></table></div></body></html>