Author: alexparvulescu Date: Mon Sep 2 14:24:16 2013 New Revision: 1519448
URL: http://svn.apache.org/r1519448 Log: OAK-301 Document Oak - tweaked the query docs Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md jackrabbit/oak/trunk/oak-doc/src/site/markdown/query.md jackrabbit/oak/trunk/oak-doc/src/site/site.xml Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md?rev=1519448&r1=1519447&r2=1519448&view=diff ============================================================================== --- jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md (original) +++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md Mon Sep 2 14:24:16 2013 @@ -71,7 +71,7 @@ Oak does not index content by default as 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. -See the [query overview page](/query/) for how to create a custom index. +See the [query overview page](query.html) for how to create a custom index. Observation ----------- 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=1519448&r1=1519447&r2=1519448&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 2 14:24:16 2013 @@ -15,7 +15,7 @@ limitations under the License. --> -## Query +## 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 @@ -23,6 +23,17 @@ repository will be traversed. That is, t Query Indices are defined under the `oak:index` node. +### Xpath to SQL2 transformation + +In an effort to support the `XPath` language, there is a mechanism that handles the automatic conversion to `SQL2`. + +Every conversion is logged as `debug` 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')] */ + +_Note that each transformed `SQL2` query contains the original `XPath` query as a comment._ + ### Cost calculation Each query index is expected to estimate the worst-case cost to query with the given filter. @@ -32,7 +43,14 @@ The returned value is supposed to be an If an index implementation can not query the data, it has to return `Double.POSITIVE_INFINITY`. -### Property index +TODO Traversal warnings + +### 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: @@ -69,17 +87,24 @@ or to simplify you can use one of the ex } -### Node type index +### 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`. -### Lucene full-text index +### The Lucene full-text index + +The full-text index handles only the 'contains' type of queries. + + //*[jcr:contains(., 'text')] + +Not having a full-text index means that the full-text queries will not be able to work properly. Currently the query engine has a basic verification in place for full-text conditions, but that is brittle and can miss hits. The full-text index update is asynchronous via a background thread, see `Oak#withAsyncIndexing`. +This means that some full-text searches will not work for a small window of time: the background thread runs every 5 seconds, plus the time is takes to run the diff and to run the text-extraction process. -This means that some full-text searches will not work for a small window of time: the background thread runs every 5 seconds, plus the time is takes to run the diff and to run the text-extraction process. The async update status is now reflected on the `oak:index` node with the help of a few properties, see [OAK-980](https://issues.apache.org/jira/browse/OAK-980) +The async update status is now reflected on the `oak:index` node with the help of a few properties, see [OAK-980](https://issues.apache.org/jira/browse/OAK-980) TODO Node aggregation [OAK-828](https://issues.apache.org/jira/browse/OAK-828) @@ -111,6 +136,6 @@ Example: } -### Solr full-text index +### The Solr full-text index `TODO` Modified: jackrabbit/oak/trunk/oak-doc/src/site/site.xml URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/site.xml?rev=1519448&r1=1519447&r2=1519448&view=diff ============================================================================== --- jackrabbit/oak/trunk/oak-doc/src/site/site.xml (original) +++ jackrabbit/oak/trunk/oak-doc/src/site/site.xml Mon Sep 2 14:24:16 2013 @@ -33,8 +33,8 @@ under the License. <menu name="Concepts and architecture"> <item href="overview.html" name="Overview" /> <item href="nodestate.html" name="Understanding the node state model" /> - <item href="query.html" name="Query" /> <item href="microkernel.html" name="Microkernel" /> + <item href="query.html" name="The query engine" /> </menu> <menu name="Using Oak"> <item href="use_getting_started.html" name="Getting Started" />
