~~ 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.

Indexing In VXQuery

  VXQuery includes indexing functionality for creating, viewing, using, updating and deleting.


* Configuring Indexing

  VXQuery creates all indexes in a user specified directory.
  In order to use indexing, you will need to set the index directory in your cluster configuration file.
  Add the following line to your cluster configuration (e.g. cluster.xml).
  Make sure you create the indexing directory ("path/to/index/directory").
  Please note: The indexing directory must exist on all nodes.

--------
<index_directory>path/to/index/directory</index_directory>
--------


* Creating An Index For A Collection

  To create an index for an XML collection stored in <$collection>, use the following query:

--------
build-index-on-collection($collection as xs:string) as xs:boolean
--------

  Consider an example where this function takes the collection path ("/home/data/bookstore/barnes") as an argument.

  Example:

--------
build-index-on-collection("/home/data/bookstore/barnes")
--------

  Result:

------
true
------


* Viewing Indexes

  The <show-indexes> function displays a list of collections that have been indexed.
  This function takes no arguments and returns a sequence of collection paths.
  If there are no indexes created for any collection, the result will be an empty sequence.

------
show-indexes() as xs:string*
------

  Suppose we have a two collections ("/home/data/bookstore/barnes" and "/home/data/bookstore/borders") that have been indexed.

  Example:

------
show-indexes()
------

  Result:

------
/home/data/bookstore/barnes
/home/data/bookstore/borders
------

* Using An Index In Query

  To use an index in a query, use the <collection-from-index> function.
  The function takes two arguments: <$collection> as <xs:string> and <$path> as <xs:string>
  The query is written the same way as you would use the <collection> function with one additional argument for the
  search path steps.

------
collection-from-index($collection as xs:string, $path as xs:string) as node()*
------

  Example:

------
for $x in collection-from-index("/home/data/bookstore/barnes", "/bookstore/book")/book
where $x/price<30
order by $x/title
return $x/title
------

  Result:

------
<book category="CHILDREN">
  <title lang="en">Harry Potter</title>
  <author>J K. Rowling</author>
  <year>2005</year>
  <price>29.99</price>
</book>
------

* Updating An Index

  When the indexed data has changed, the index can be updated corresponding.
  The <update-index> function will check for file system changes and update an index.
  The function takes one argument: <$collection> as xs:string.

--------
update-index($collection as xs:string) as xs:boolean
--------

  Example:

-------
update-index("/home/data/bookstore/barnes")
-------

  Result:

------
true
------


* Deleting An Index

  An index can be deleted by using the <delete-index> function.
  The function takes one argument: <$collection> as xs:string.

--------
delete-index($collection as xs:string) as xs:boolean
--------

  Example:

-------
delete-index("/home/data/bookstore/barnes")
-------

  Result:

------
true
------


* Indexing Partitioned Collections

  Similar to the <collection> function, indexing queries can be partitioned for collection distributed among
  several directories.
  Partitioned queries use the vertical bar (|) to delimit partition paths within a query.

  Previous examples used a single collection.
  The following example has two collections in a single <$collection> variable for building an index:

--------
build-index-on-collection("/home/data/bookstore/barnes|/home/data/bookstore/borders")
--------

  The partition delimiter can be used in all the indexing <$collection> arguments.