<?xml version="1.0" encoding="UTF-8"?>

<!--
  - Licensed to the Apache Software Foundation (ASF) under one or more
  - contributor license agreements.  See the NOTICE file distributed with
  - this work for additional information regarding copyright ownership.
  - The ASF licenses this file to You under the Apache License, Version 2.0
  - (the "License"); you may not use this file except in compliance with
  - the License.  You may obtain a copy of the License at
  -
  -     http://www.apache.org/licenses/LICENSE-2.0
  -
  - Unless required by applicable law or agreed to in writing, software
  - distributed under the License is distributed on an "AS IS" BASIS,
  - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  - See the License for the specific language governing permissions and
  - limitations under the License.
  -
  - $Id$
  -->

<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">

<!--
  - Version: $Revision$ $Date$
  - Author: Vadim Gritsenko (vgritsenko@apache.org)
  -->

<document>
  <header>
    <title>Xindice 1.2 XPath Guide</title>
    <version>$Revision$</version>
    <authors>
      <person id="VG" name="Vadim Gritsenko" email=""/>
    </authors>
    <notice/>
    <abstract/>
  </header>
  <body>
    <note>
      If you notice incorrectness in this documentation, please
      <link href="../mail.html">notify</link> Xindice community. Your feedback
      will help create better documentation.
    </note>

    <section>
      <title>Querying the Database</title>
      <p>
        Xindice currently supports XPath as a query language. Queries can
        be executed from within client application (please refer to the
        <link href="guide-developer.html">developers guide</link>), through
        XML-RPC interface, or via a command line (please refer to the
        <link href="guide-tools.html">command line tool guide</link>).
        This document describes what XPath queries are supported and what are
        the results of the query.
      </p>
    </section>

    <section>
      <title>Sample Database</title>
      <p>
        XPath queries and results described below were run against sample
        /db/addressbook collection. There are two documents in the addressbook
        collection.
      </p>
      <p>Key: <code>address1</code></p>
      <source><![CDATA[
  <?xml version="1.0"?>
  <person>
    <fname>John</fname>
    <lname>Smith</lname>
    <phone type="work">563-456-7890</phone>
    <phone type="home">534-567-8901</phone>   
    <email type="home">jsmith@somemail.com</email>
    <email type="work">john@lovesushi.com</email>
    <address type="home">34 S. Colon St.</address>
    <address type="work">9967 W. Shrimp Ave.</address>
  </person>
      ]]></source>
      <p>Key: <code>address2</code></p>
      <source><![CDATA[
  <?xml version="1.0"?>
  <person>
    <fname>SlackJawedLocal</fname>
    <lname>Cletus</lname>
    <phone type="work">123-456-7890</phone>
    <phone type="home">234-567-8901</phone>
    <phone type="cell">345-678-9012</phone>
    <email type="home">cletus@hotmail.com</email>
    <email type="work">cletus@micrsquish.com</email>
    <address type="home">1234 S. Elm St.</address>
    <address type="work">4567 W. Pine St.</address>
  </person>
      ]]></source>
    </section>

    <section>
      <title>Query for Document</title>
      <p>
        One of the common usages for XPath is to obtain documents satisfying
        some criteria. Suppose we want to find everybody with the cell phone:
      </p>
      <source>  xindice xpath -c /db/addressbook -q "/person[phone/@type='cell']"  </source>
      <p>
        Result of the query will be one or more documents. If you have only two
        person entries in the collection, then only one result will be found:
      </p>
      <source><![CDATA[
  <person xmlns:src="http://xml.apache.org/xindice/Query"
          src:col="/db/addressbook" src:key="address2">
    <fname>SlackJawedLocal</fname>
    <lname>Cletus</lname>
    <phone type="work">123-456-7890</phone>
    <phone type="home">234-567-8901</phone>
    <phone type="cell">345-678-9012</phone>
    <email type="home">cletus@hotmail.com</email>
    <email type="work">cletus@micrsquish.com</email>
    <address type="home">1234 S. Elm St.</address>
    <address type="work">4567 W. Pine St.</address>
  </person>
      ]]></source>
    </section>

    <section>
      <title>Query for Element</title>
      <p>
        Here we will issue a query resulting only in some elements from the document.
        Suppose we want to find everybody's home phone numbers:
      </p>
      <source>  xindice xpath -c /db/addressbook -q "/person/phone[@type='home']"  </source>
      <p>
        Result of the query will be all elements satisfying criteria from all documents.
      </p>
      <source><![CDATA[
  <phone src:col="/db/addressbook" src:key="address1"
         xmlns:src="http://xml.apache.org/xindice/Query"
         type="home">534-567-8901</phone>
  <phone src:col="/db/addressbook" src:key="address2"
         xmlns:src="http://xml.apache.org/xindice/Query"
         type="home">234-567-8901</phone>
      ]]></source>
    </section>

    <section>
      <title>Query for Text Node</title>
      <p>
        With Xindice 1.1b4 and above, it is possible to query for text nodes. Each
        resulting text node will be wrapped into <code>result</code> element in the
        Query namespace.
      </p>
      <source>  xindice xpath -c /db/addressbook -q "/person[fname='John']/phone/text()"  </source>
      <p>
        Result of the query will be all phones for all Johns in the collection.
      </p>
      <source><![CDATA[
  <xq:result xmlns:xq="http://xml.apache.org/xindice/Query"
             xq:col="/db/addressbook" xq:key="address1">563-456-7890</xq:result>
  <xq:result xmlns:xq="http://xml.apache.org/xindice/Query"
             xq:col="/db/addressbook" xq:key="address1">534-567-8901</xq:result>
      ]]></source>
    </section>

    <section>
      <title>Query for String</title>
      <p>
        XPath expressions with String result are also supported.
      </p>
      <source>  xindice xpath -c /db/addressbook -q "string(/person[fname='John']/phone)"  </source>
      <p>
        Result of the query will be first phone number for all Johns in the collection,
        and empty result for each non-John.
      </p>
      <source><![CDATA[
  <xq:result xmlns:xq="http://xml.apache.org/xindice/Query"
             xq:col="/db/addressbook" xq:key="address1">563-456-7890</xq:result>
  <xq:result xmlns:xq="http://xml.apache.org/xindice/Query"
             xq:col="/db/addressbook" xq:key="address2"></xq:result>
      ]]></source>
      <note>
        Because XPath is evaluated against each document, and because
        <code>string()</code> function always returns a result, such query will produce
        result from each document in the collection. In this example, result from second
        document is empty, as criteria <code>fname='John'</code> was not satisfied.
      </note>
    </section>

    <section>
      <title>Query for Number</title>
      <p>
        XPath expressions with Number result are also supported. 
      </p>
      <source>  xindice xpath -c /db/addressbook -q "count(/person/phone)"  </source>
      <p>
        This XPath will return count of phone numbers on file for each person. If person
        does not have phone numbers, result for this person will be <code>0.0</code>.
      </p>
      <source><![CDATA[
  <xq:result xmlns:xq="http://xml.apache.org/xindice/Query"
             xq:col="/db/addressbook" xq:key="address1">2.0</xq:result>
  <xq:result xmlns:xq="http://xml.apache.org/xindice/Query"
             xq:col="/db/addressbook" xq:key="address2">3.0</xq:result>
      ]]></source>
    </section>

    <section>
      <title>Using full text search in XPath</title>
      <p>
        Full text search functionality is available in XPath queries in Xindice as an extention function.
      </p>
      <p>Function: boolean ftcontains(string)</p>
      <p>
        The ftcontains function returns true if text content of the context
        node matches full text query passed as the argument, otherwise it
        returns false. Text query syntax is the same as
        <link href="http://lucene.apache.org/java/docs/queryparsersyntax.html">Lucene query syntax</link>,
        except it does not use fields (using fields does not cause errors
        when parsing the query, but function will return false).
      </p>
      <source>  xindice xpath -c /db/addressbook -q "/person/address[@type='work']/text()[ftcontains('pine')]"  </source>
      <p>
        This XPath will return all work addresses of all people in database that
        contain word 'pine'.
      </p>
      <source><![CDATA[
  <xq:result xmlns:xq="http://xml.apache.org/xindice/Query"
             xq:col="/db/addressbook" xq:key="address2">4567 W. Pine St.</xq:result>
      ]]></source>
      <note>
        Function results depend on the analyzer that is used to tokenize both
        node text content and a query. If LuceneIndexer exists for the
        collection being queried, same analyzer will be used for the ftcontains
        function to produce consistent results. If LuceneIndexer is not found,
        default analyzer will be used (at this time it is SimpleAnalyzer).
      </note>
    </section>
  </body>
</document>
