Improved indexing documentation. 159/head
authorPreston Carman <prestonc@apache.org>
Thu, 13 Oct 2016 23:46:50 +0000 (16:46 -0700)
committerPreston Carman <prestonc@apache.org>
Thu, 13 Oct 2016 23:46:50 +0000 (16:46 -0700)
- Rewrote the indexing documentation to used XQuery style function definitions.
- Renamed show-index to show-indexes.

src/site/apt/user_indexing.apt
vxquery-core/src/main/java/org/apache/vxquery/functions/builtin-functions.xml
vxquery-xtest/src/test/resources/ExpectedTestResults/Indexing/Partition-1/showIndexes1.txt [moved from vxquery-xtest/src/test/resources/ExpectedTestResults/Indexing/Partition-1/showIndex1.txt with 100% similarity]
vxquery-xtest/src/test/resources/ExpectedTestResults/Indexing/Partition-1/showIndexes2.txt [moved from vxquery-xtest/src/test/resources/ExpectedTestResults/Indexing/Partition-1/showIndex2.txt with 100% similarity]
vxquery-xtest/src/test/resources/ExpectedTestResults/Indexing/Partition-2/showIndexes1.txt [moved from vxquery-xtest/src/test/resources/ExpectedTestResults/Indexing/Partition-2/showIndex1.txt with 100% similarity]
vxquery-xtest/src/test/resources/ExpectedTestResults/Indexing/Partition-4/showIndexes1.txt [moved from vxquery-xtest/src/test/resources/ExpectedTestResults/Indexing/Partition-4/showIndex1.txt with 100% similarity]
vxquery-xtest/src/test/resources/Queries/XQuery/Indexing/Partition-1/showIndexes.xq [moved from vxquery-xtest/src/test/resources/Queries/XQuery/Indexing/Partition-1/showIndex.xq with 94% similarity]
vxquery-xtest/src/test/resources/Queries/XQuery/Indexing/Partition-2/showIndexes.xq [moved from vxquery-xtest/src/test/resources/Queries/XQuery/Indexing/Partition-2/showIndex.xq with 94% similarity]
vxquery-xtest/src/test/resources/Queries/XQuery/Indexing/Partition-4/showIndexes.xq [moved from vxquery-xtest/src/test/resources/Queries/XQuery/Indexing/Partition-4/showIndex.xq with 94% similarity]
vxquery-xtest/src/test/resources/cat/IndexingQueries.xml

index ce7fafa..97c9616 100644 (file)
 ~~ See the License for the specific language governing permissions and
 ~~ limitations under the License.
 
-How to use Indexing Features in VXQuery.
+Indexing In VXQuery
 
-  In VXQuery, all the indexes are created in user specified directory. In order to use indexing,
-  you will need to set this directory in your cluster configuration file.
+  VXQuery includes indexing functionality for creating, viewing, using, updating and deleting.
 
-* Configuring VXQuery to use indexing functions.
 
-  Add the following line to your cluster configuration (e.g. cluster.xml)
+* 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>
+<index_directory>path/to/index/directory</index_directory>
 --------
 
-  (You should create this index_directory)
-
-* Using indexing queries.
-
-  VXQuery offers following indexing functionality.
-
-  [[a]] Create an index for collection.
-  [[b]] Use the index in executing a query.
-  [[c]] Update the index.
-  [[d]] Delete the index.
-  [[e]] View existing indexes.
-
-*Scenario I - When collection is a single directory.
 
-  In this scenario, all the XML files are stored in a single directory. (There can be sub directories)
+* Creating An Index For A Collection
 
-** Creating an index for collection
-
-  If I need to create index for xml collection stored in <path_to_collection_1>,
-
-  Query structure:
+  To create an index for an XML collection stored in <$collection>, use the following query:
 
 --------
-build-index-on-collection("<path_to_collection_1>")
+build-index-on-collection($collection as xs:string) as xs:boolean
 --------
 
-  You can see the index has created in a new sub-directory in the index_directory specified in local.xml
+  Consider an example where this function takes the collection path ("/home/data/bookstore/barnes") as an argument.
 
   Example:
 
 --------
-build-index-on-collection("<path_to_collection_1>")
+build-index-on-collection("/home/data/bookstore/barnes")
 --------
 
-  This function takes the collection path as an argument.
-
-** Using index in query.
-
-  If we need to use the index and execute a query, use the following structure.
+  Result:
 
 ------
-for $r in collection-from-index("<path1>/collection1", "/dataCollection/data")/data
-where $r/dataType eq "AWND" and xs:decimal($r/value) gt 491.744
-return $r
+true
 ------
 
-  Here the index access function is,
 
-------
-collection-from-index
-------
+* Viewing Indexes
 
-  which takes two arguments, collection folder and the path element.
-
-  Result:
+  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.
 
 ------
-<data>
-  <date>2001-01-01T00:00:00.000</date>
-  <dataType>AWND</dataType>
-  <station>GHCND:US000000001</station>
-  <value>1000</value>
-  <attributes>
-    <attribute/>
-    <attribute/>
-    <attribute>a</attribute>
-  </attributes>
-</data>
+show-indexes() as xs:string*
 ------
 
-** Updating the index.
-
-  A collection can be modified or changed by following ways.
-  [[1]] Inserting new XML files.
-  [[2]] Deleting files.
-  [[3]] Add/ remove or modify the content of XML files.
-
-  In this type of situation, the index corresponding to the modified collection must also be modified.
-  To achieve this the update-index function can be used.
-
-  Query structure:
-
---------
-update-index("<path_to_collection_1>")
---------
+  Suppose we have a two collections ("/home/data/bookstore/barnes" and "/home/data/bookstore/borders") that have been indexed.
 
   Example:
 
--------
-update-index("<path_to_collection_1>")
--------
+------
+show-indexes()
+------
 
-  This function takes the collection which was modified.
+  Result:
 
-** Deleting the index.
+------
+/home/data/bookstore/barnes
+/home/data/bookstore/borders
+------
 
-  If we want to delete the entire index created for a collection, the delete-index function can be used.
-  This function also takes the collection path of which the index is needed to be deleted.
+* Using An Index In Query
 
-  Query structure:
+  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.
 
---------
-delete-index("<path_to_collection_1>")
---------
+------
+collection-from-index($collection as xs:string, $path as xs:string) as node()*
+------
 
   Example:
 
--------
-delete-index("<path_to_collection_1>")
--------
+------
+for $x in collection-from-index("/home/data/bookstore/barnes", "/bookstore/book")/book
+where $x/price<30
+order by $x/title
+return $x/title
+------
 
-*Scenario II - When the collection is distributed.
+  Result:
 
-  In this scenario, the collection is distributed among several directories.
-  We can distribute the queries among partitions.
+------
+<book category="CHILDREN">
+  <title lang="en">Harry Potter</title>
+  <author>J K. Rowling</author>
+  <year>2005</year>
+  <price>29.99</price>
+</book>
+------
 
-** Creating indexes for collections.
+* Updating An Index
 
-  Query structure:
+  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.
 
 --------
-build-index-on-collection("<path_to_collection_1>|<path_to_collection_2>|...|<path_to_collection_n>")
+update-index($collection as xs:string) as xs:boolean
 --------
 
-  In here the parameter contains the list of collection partitions separated by '|' character.
-
   Example:
 
-  Consider the collection has now distributed among four directories, path_to_collection_1, path_to_collection_2,
-  path_to_collection_3 and path_to_collection_4.
-
-  To create indexes for all of the above collections,
-
 -------
-build-index-on-collection("path_to_collection_1|path_to_collection_2|path_to_collection_3|path_to_collection_4")
+update-index("/home/data/bookstore/barnes")
 -------
 
-  In this case, all indexes will be created in separate sub-directories corresponding to each partition.
-  Also note that this query requires each node to have four partitions available.
-
-** Using the indexes in query.
-
-  In this case, suppose you need to run a query on indexes of two collection partitions.
-
-  Example:
-
------
-for $r in collection-from-index("<path_to_collection_1>|<path_to_collection_2>", "/dataCollection/data")/data
-where $r/dataType eq "AWND" and xs:decimal($r/value) gt 491.744
-return $r
------
-
-  The result will be taken from the indexes of both path_to_collection_1 and path_to_collection_2.
-
   Result:
 
 ------
-<data>
-  <date>2001-01-01T00:00:00.000</date>
-  <dataType>AWND</dataType>
-  <station>GHCND:US000000001</station>
-  <value>1000</value>
-  <attributes>
-    <attribute/>
-    <attribute/>
-    <attribute>a</attribute>
-  </attributes>
-</data>
+true
 ------
 
-** Updating the indexes.
 
-  In cases of updating the collection files stored in several partitions, we can use this function to update the
-  indexes of those directories.
+* Deleting An Index
 
-  In this case, give a '|' separated list of collection directories.
-
-  Query structure:
+  An index can be deleted by using the <delete-index> function.
+  The function takes one argument: <$collection> as xs:string.
 
 --------
-update-index("<path_to_collection_1>|<path_to_collection_2>|...|<path_to_collection_n>")
+delete-index($collection as xs:string) as xs:boolean
 --------
 
   Example:
 
-  Suppose that we need to update the indexes in partition1 and partition4
-
---------
-update-index("<path_to_collection_1>|<path_to_collection_4>")
---------
+-------
+delete-index("/home/data/bookstore/barnes")
+-------
 
-** Deleting the indexes.
+  Result:
 
-  If we want to delete indexes of collections in several partitions, we can use this function.
+------
+true
+------
 
-  Query structure:
 
---------
-delete-index("<path_to_collection_1>|<path_to_collection_2>|...|<path_to_collection_n>")
---------
+* Indexing Partitioned Collections
 
-  Example:
+  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.
 
-  Suppose that we need to update the indexes in collection2 and collection3
+  Previous examples used a single collection.
+  The following example has two collections in a single <$collection> variable for building an index:
 
 --------
-delete-index("<path_to_collection_2>|<path_to_collection_3>")
+build-index-on-collection("/home/data/bookstore/barnes|/home/data/bookstore/borders")
 --------
 
-** Viewing Index information.
-
-  Suppose you need to check, what are the collections have indexes created.
-  To do this, the show-index function can be used.
-  This function takes no arguments and returns a sequence of collection paths, which an index is already created.
-  If there are no indexes created for any collection, the result will be null.
+  The partition delimiter can be used in all the indexing <$collection> arguments.
 
-  Suppose we have two collections, <path_to_collection_1>, <path_to_collection_2>  have indexes created.
-
-  Example:
-
-------
-show-index()
-------
-
-  Result:
-
-------
-<path_to_collection_1>
-<path_to_collection_2>
-------
index 688e86e..d64f423 100644 (file)
         <!-- collection-from-index operator is added during the rewrite rules phase.  -->
     </function>
 
-    <!-- fn:show-index as node()* -->
-    <function name="fn:show-index">
+    <!-- fn:show-indexes as node()* -->
+    <function name="fn:show-indexes">
         <return type="node()*"/>
         <runtime type="scalar" class="org.apache.vxquery.runtime.functions.index.ShowIndexScalarEvaluatorFactory"/>
     </function>
@@ -15,5 +15,5 @@
    specific language governing permissions and limitations
    under the License. :)
 
-(: Show indexes after createion :)
-show-index()
\ No newline at end of file
+(: Show indexes after creation :)
+show-indexes()
\ No newline at end of file
@@ -15,5 +15,5 @@
    specific language governing permissions and limitations
    under the License. :)
 
-(: Show indexes after createion :)
-show-index()
\ No newline at end of file
+(: Show indexes after creation :)
+show-indexes()
\ No newline at end of file
@@ -15,5 +15,5 @@
    specific language governing permissions and limitations
    under the License. :)
 
-(: Show indexes after createion :)
-show-index()
\ No newline at end of file
+(: Show indexes after creation :)
+show-indexes()
\ No newline at end of file
index fc668ba..7cf6bf6 100644 (file)
       <query name="createIndex" date="2016-05-26"/>
       <output-file compare="Text">createIndex.txt</output-file>
    </test-case>
-   <test-case name="show-index-1" FilePath="Indexing/Partition-1/" Creator="Menaka Jayawardena">
+   <test-case name="show-indexes-1" FilePath="Indexing/Partition-1/" Creator="Menaka Jayawardena">
       <description>Show indexes after creating index.</description>
-      <query name="showIndex" date="2016-08-18"/>
-      <output-file compare="Text">showIndex1.txt</output-file>
+      <query name="showIndexes" date="2016-08-18"/>
+      <output-file compare="Text">showIndexes1.txt</output-file>
    </test-case>
    <test-case name="use-index-1" FilePath="Indexing/Partition-1/" Creator="Steven Jacobs">
       <description>Get Collection From Lucene Index</description>
       <query name="deleteIndex" date="2016-06-24"/>
       <output-file compare="Text">deleteIndex.txt</output-file>
    </test-case>
-   <test-case name="show-index-2" FilePath="Indexing/Partition-1/" Creator="Menaka Jayawardena">
+   <test-case name="show-indexes-2" FilePath="Indexing/Partition-1/" Creator="Menaka Jayawardena">
       <description>Show indexes after deletion.</description>
-      <query name="showIndex" date="2016-08-18"/>
-      <output-file compare="Text">showIndex2.txt</output-file>
+      <query name="showIndexes" date="2016-08-18"/>
+      <output-file compare="Text">showIndexes2.txt</output-file>
    </test-case>
    <test-case name="create-index" FilePath="Indexing/Partition-2/" Creator="Steven Jacobs">
       <description>Create Lucene Index from Collection.</description>
       <query name="createIndex" date="2016-05-26"/>
       <output-file compare="Text">createIndex.txt</output-file>
    </test-case>
-   <test-case name="show-index-1" FilePath="Indexing/Partition-2/" Creator="Menaka Jayawardena">
+   <test-case name="show-indexes-1" FilePath="Indexing/Partition-2/" Creator="Menaka Jayawardena">
       <description>Show indexes after creating index.</description>
-      <query name="showIndex" date="2016-08-18"/>
-      <output-file compare="Text">showIndex1.txt</output-file>
+      <query name="showIndexes" date="2016-08-18"/>
+      <output-file compare="Text">showIndexes1.txt</output-file>
    </test-case>
    <test-case name="use-index-1" FilePath="Indexing/Partition-2/" Creator="Steven Jacobs">
       <description>Get Collection From Lucene Index</description>
       <query name="createIndex" date="2016-05-26"/>
       <output-file compare="Text">createIndex.txt</output-file>
    </test-case>
-   <test-case name="show-index-1" FilePath="Indexing/Partition-4/" Creator="Menaka Jayawardena">
+   <test-case name="show-indexes-1" FilePath="Indexing/Partition-4/" Creator="Menaka Jayawardena">
       <description>Show indexes after creating index.</description>
-      <query name="showIndex" date="2016-08-18"/>
-      <output-file compare="Text">showIndex1.txt</output-file>
+      <query name="showIndexes" date="2016-08-18"/>
+      <output-file compare="Text">showIndexes1.txt</output-file>
    </test-case>
    <test-case name="use-index-1" FilePath="Indexing/Partition-4/" Creator="Steven Jacobs">
       <description>Get Collection From Lucene Index</description>