(feature) multi-value hierarchical facets documentation; required for eXist-db/exist#3182

Author: tuurma

src/main/xar-resources/data/lucene/listings/listing-520.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<collection xmlns="http://exist-db.org/collection-config/1.0">
+    <index xmlns:db="http://docbook.org/ns/docbook" xmlns:xs="http://www.w3.org/2001/XMLSchema">
+        <lucene>
+            <module uri="http://exist-db.org/lucene/test/" prefix="idx" at="module.xql"/>
+            <text qname="db:article">
+                <facet dimension="keyword" expression="db:info/db:keywordset/db:keyword"/>
+                <facet dimension="date" expression="tokenize(db:info/db:pubdate, '-')" hierarchical="yes"/>
+                <facet dimension="subject" expression="idx:subject-hierarchy(db:info/db:subjectset/db:subject/db:subjectterm)" hierarchical="yes"/>
+            </text>
+        </lucene>
+    </index>
+</collection>

src/main/xar-resources/data/lucene/listings/listing-521.txt

@@ -0,0 +1,5 @@
+declare function idx:subject-hierarchy($key as xs:string*) {
+    array:for-each (array {$key}, function($k) {
+        doc('/db/subjects/subjects.xml')//subject[@name=$k]/ancestor-or-self::subject/@name
+    })
+};

src/main/xar-resources/data/lucene/listings/listing-522.xml

@@ -0,0 +1,11 @@
+<subject>
+    <subject name="science">
+        <subject name="math"/>
+        <subject name="physics"/>
+    </subject>
+    <subject name="humanities">
+        <subject name="art"/>
+        <subject name="sociology"/>
+        <subject name="history"/>
+    </subject>
+</subject>

src/main/xar-resources/data/lucene/lucene.xml

@@ -394,14 +394,30 @@
                     expression rooted in the parent node being indexed. In the example the parent will be a <tag>db:article</tag> element, so the context item
                     for the expression is set to this element.</para>
                 <para>The expression is evaluated and for each result item, a facet value is added
-                    to the dimension using the string value of the item. If the expression returns
-                    the empty sequence  for the current parent node, the corresponding facet will be
-                    empty as well.</para>
+                    to the dimension using the string value of the item. Therefore if the expression
+                    returns multiple items, a facet for that dimension will also hold multiple values.
+                    If the expression returns the empty sequence  for the current parent node, the corresponding
+                    facet will be empty as well.</para>
                 <para>A facet can also be defined to be hierarchical. A typical example would be a date, which consists of a year, month and day component. By
                     indexing the single components as separate parts of a hierarchical facet, we enable the user to drill down by year first, then by month and
                     finally by day. Let's assume each of our docbook articles has a <tag>pubdate</tag> containing a date in <code>xs:date</code>
                     format:</para>
                 <programlisting language="xml" xlink:href="listings/listing-52.txt"></programlisting>
+                <para>Hierarchical facets may also hold multiple values, for example if we would like to associate
+                    our documents with a subject classification on various levels of granularity (say: <emphasis>science</emphasis> with
+                    <emphasis>math</emphasis> and <emphasis>physics</emphasis> as subcategories or <emphasis>humanities</emphasis> with
+                    <emphasis>art</emphasis>, <emphasis>sociology</emphasis> and <emphasis>history</emphasis>).
+                    This way we enable the user to drill down into broad <emphasis>humanities</emphasis>
+                    or <emphasis>science</emphasis> subject first and choose particular topics afterwards.
+                    If the result of the hierarchical facet <code>expression</code>
+                    evaluates to an array, each of array members will be treated as a hierarchical value for that facet.
+                    Such an array could look in XQuery similar to <code>[('science', 'math'), ('humanities', 'history')]</code> and be
+                    a result of evaluationg a function like <code>idx:subject-hierarchy</code> below stored in an imported module (see <link linkend="external-module">below</link>)
+                    </para>
+                <programlisting language="xml" xlink:href="listings/listing-520.xml"/>
+                <programlisting language="xquery" xlink:href="listings/listing-521.txt"/>
+                <para>which assumes hierarchical subject structure stored in <emphasis>/db/lucenetest/subjects.xml</emphasis></para>
+                <programlisting language="xml" xlink:href="listings/listing-522.xml"/>
                 <para>Next, we may want to define fields for the authors and title of the article. In docbook, <tag>author</tag> can be a complex element,
                     consisting e.g. of a <tag>personname</tag> with nested
                         <tag>surname</tag> and <tag>firstname</tag>. For display to the user and sorting we want to pre-compute a normalized string out of those