jackrabbit-oak-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From thom...@apache.org
Subject svn commit: r1525522 - /jackrabbit/oak/trunk/oak-doc/src/site/markdown/query.md
Date Mon, 23 Sep 2013 07:53:31 GMT
Author: thomasm
Date: Mon Sep 23 07:53:31 2013
New Revision: 1525522

URL: http://svn.apache.org/r1525522
Log:
OAK-301 Document Oak - more query docs

Modified:
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/query.md

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/query.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query.md?rev=1525522&r1=1525521&r2=1525522&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query.md Mon Sep 23 07:53:31 2013
@@ -15,50 +15,65 @@
    limitations under the License.
   -->
 
-## The query engine
+## The Query Engine
 
-Oak does not index content by default as does Jackrabbit 2. You need to create custom indexes
when
-necessary, much like in traditional RDBMSs. If there is no index for a specific query then
the
-repository will be traversed. That is, the query will still work but probably be very slow.
+Oak does not index content by default as does Jackrabbit 2. You need to create custom 
+indexes when necessary, much like in traditional RDBMSs. If there is no index for a 
+specific query, then the repository will be traversed. That is, the query will still 
+work but probably be very slow.
 
 Query Indices are defined under the `oak:index` node.
 
-### Xpath to SQL2 transformation
+### XPath to SQL2 Transformation
 
-In an effort to support the `XPath` language, there is a mechanism that handles the automatic
conversion to `SQL2`. 
+To support the XPath query language, such queries are internally converted to SQL2. 
 
-Every conversion is logged as `debug` under the `org.apache.jackrabbit.oak.query.QueryEngineImpl`
logger:
+Every conversion is logged in `debug` level under the 
+`org.apache.jackrabbit.oak.query.QueryEngineImpl` logger:
 
-    org.apache.jackrabbit.oak.query.QueryEngineImpl Parsing xpath statement: //element(*)[@sling:resourceType
= 'slingevent:Lock')]
-    org.apache.jackrabbit.oak.query.QueryEngineImpl XPath > SQL2: select [jcr:path], [jcr:score],
* from [nt:base] as a where [sling:resourceType] = 'slingevent:Lock' /* xpath: //element(*)[@sling:resourceType
= 'slingevent:Lock' and @lock.created < xs:dateTime('2013-09-02T15:44:05.920+02:00')] */
+    org.apache.jackrabbit.oak.query.QueryEngineImpl Parsing xpath statement: 
+        //element(*)[@sling:resourceType = 'slingevent:Lock')]
+    org.apache.jackrabbit.oak.query.QueryEngineImpl XPath > SQL2: 
+        select [jcr:path], [jcr:score], * from [nt:base] as a 
+        where [sling:resourceType] = 'slingevent:Lock' 
+        /* xpath: //element(*)[@sling:resourceType = 'slingevent:Lock' 
+        and @lock.created < xs:dateTime('2013-09-02T15:44:05.920+02:00')] */
 
-_Note that each transformed `SQL2` query contains the original `XPath` query as a comment._
+_Each transformed SQL2 query contains the original XPath query as a comment._
 
-### Cost calculation
+### Query Processing
 
-Each query index is expected to estimate the worst-case cost to query with the given filter.

-The returned value is between 1 (very fast; lookup of a unique node) and the estimated number
of entries to traverse, if the cursor would be fully read, and if there could in theory be
one network round-trip or disk read operation per node (this method may return a lower number
if the data is known to be fully in memory).
+Internally, the query engine uses a cost based query optimizer that asks all the available
+query indexes for the estimated cost to process the query. It then uses the index with the

+lowest cost.
 
-The returned value is supposed to be an estimate and doesn't have to be very accurate. Please
note this method is called on each index whenever a query is run, so the method should be
reasonably fast (not read any data itself, or at least not read too much data).
+By default, the following indexes are available:
 
-If an index implementation can not query the data, it has to return `Double.POSITIVE_INFINITY`.
+* A property index for each indexed property.
+* A full-text index which is based on Apache Lucene / Solr.
+* A node type index (which is based on an property index for the properties
+  jcr:primaryType and jcr:mixins).
+* A traversal index that iterates over a subtree.
 
-TODO Traversal warnings
+If no index can efficiently process the filter condition, the nodes in the repository are

+traversed at the given subtree.
+
+Usually, data is read from the index and repository while traversing over the query 
+result. There are exceptions however, where all data is read in memory when the query
+is executed: when using a full-text index, and when using an "order by" clause.
 
-### The property index
+### The Property Index
 
 Is useful whenever there is a query with a property constraint that is not full-text:
 
     SELECT * FROM [nt:base] WHERE [jcr:uuid] = $id
 
-
 To define a property index on a subtree you have to add an index definition node that:
 
 * must be of type `oak:queryIndexDefinition`
 * must have the `type` property set to __`property`__
 * contains the `propertyNames` property that indicates what properties will be stored in
the index.
-
-    `propertyNames` can be a list of properties, and it is optional.in case it is missing,
the node name will be used as a property name reference value
+  `propertyNames` can be a list of properties, and it is optional.in case it is missing,
the node name will be used as a property name reference value
 
 _Optionally_ you can specify
 
@@ -87,13 +102,7 @@ or to simplify you can use one of the ex
     }
 
 
-### The node type index
-
-The `NodeTypeIndex` implements a `QueryIndex` using `PropertyIndexLookup`s on `jcr:primaryType`
`jcr:mixinTypes` to evaluate a node type restriction on the filter.
-The cost for this index is the sum of the costs of the `PropertyIndexLookup` for queries
on `jcr:primaryType` and `jcr:mixinTypes`.
-
-
-### The Lucene full-text index
+### The Lucene Full-Text Index
 
 The full-text index handles only the 'contains' type of queries.
 
@@ -136,6 +145,23 @@ Example:
     }
 
 
-### The Solr full-text index
+### The Solr Full-Text Index
 
 `TODO`
+
+### The Node Type Index
+
+The `NodeTypeIndex` implements a `QueryIndex` using `PropertyIndexLookup`s on `jcr:primaryType`
`jcr:mixinTypes` to evaluate a node type restriction on the filter.
+The cost for this index is the sum of the costs of the `PropertyIndexLookup` for queries
on `jcr:primaryType` and `jcr:mixinTypes`.
+
+### Cost Calculation
+
+Each query index is expected to estimate the worst-case cost to query with the given filter.

+The returned value is between 1 (very fast; lookup of a unique node) and the estimated number
of entries to traverse, if the cursor would be fully read, and if there could in theory be
one network round-trip or disk read operation per node (this method may return a lower number
if the data is known to be fully in memory).
+
+The returned value is supposed to be an estimate and doesn't have to be very accurate. Please
note this method is called on each index whenever a query is run, so the method should be
reasonably fast (not read any data itself, or at least not read too much data).
+
+If an index implementation can not query the data, it has to return `Double.POSITIVE_INFINITY`.
+
+TODO Traversal warnings
+



Mime
View raw message