svn commit: r1572508 - /jackrabbit/oak/trunk/oak-doc/src/site/markdown/query.md

[th...@apache.org]

Author: thomasm
Date: Thu Feb 27 11:05:53 2014
New Revision: 1572508

URL: http://svn.apache.org/r1572508
Log:
OAK-1325 Support native pass-through queries (e.g. Lucene)

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=1572508&r1=1572507&r2=1572508&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query.md Thu Feb 27 11:05:53 2014
@@ -26,6 +26,8 @@ Query Indices are defined under the `oak
 
 ### Compatibility
 
+#### Quoting
+
 The query parser is now generally more strict about invalid syntax.
 The following query used to work in Jackrabbit 2.x, but not in Oak,
 because multiple way to quote the path are used at the same time:
@@ -38,6 +40,15 @@ Instead, the query now needs to be:
     SELECT * FROM [nt:base] AS s 
     WHERE ISDESCENDANTNODE(s, [/libs/sling/config])
     
+#### Equality for Path Constraints
+
+In Jackrabbit 2.x, the following condition was interpreted as a LIKE condition:
+
+    SELECT * FROM nt:base WHERE jcr:path = '/abc/%'
+    
+Therefore, the query behaves exactly the same as if LIKE was used.
+In Oak, this is no longer the case, and such queries search for an exact path match.
+    
 ### Slow Queries and Read Limits
 
 Slow queries are logged as follows:
@@ -59,6 +70,33 @@ with an UnsupportedOperationException sa
 "The query read or traversed more than 10000 nodes. To avoid affecting other tasks, processing was stopped.".
 As a workaround, this limit can be changed using the system property "oak.queryLimitReads".
 
+### Native Queries
+
+To take advantage of features that are available in full-text index implementations
+such as Apache Lucene and Apache Lucene Solr, so called `native` constraints are supported.
+Such constraints are passed directly to the full-text index. This is supported
+for both XPath and SQL-2. For XPath queries, the name of the function is `rep:native`,
+and for SQL-2, it is `native`. The first parameter is the index type (currently supported
+are `solr` and `lucene`). The second parameter is the native search query expression.
+For SQL-2, the selector name (if needed) is the first parameter, just before the language.
+Examples:
+
+    //*[rep:native('solr', 'name:(Hello OR World)')]
+    
+    select [jcr:path] from [nt:base] 
+    where native('solr', 'name:(Hello OR World)')
+
+    select [jcr:path] from [nt:base] as a 
+    where native(a, 'solr', 'name:(Hello OR World)')
+
+This also allows to use the Solr [MoreLikeThis](http://wiki.apache.org/solr/MoreLikeThis)
+feature. An example query is:
+
+    select [jcr:path] from [nt:base] 
+    where native('solr', 'mlt?q=id:UTF8TEST&mlt.fl=manu,cat&mlt.mindf=1&mlt.mintf=1')
+
+If no full-text implementation is available, those queries will fail.
+
 ### XPath to SQL2 Transformation
 
 To support the XPath query language, such queries are internally converted to SQL2. 
@@ -76,6 +114,10 @@ Every conversion is logged in `debug` le
 
 _Each transformed SQL2 query contains the original XPath query as a comment._
 
+When converting from XPath to SQL-2, `or` conditions are automatically converted to
+`union` queries, so that indexes can be used for conditions of the form 
+`a = 'x' or b = 'y'`.
+
 ### Query Processing
 
 Internally, the query engine uses a cost based query optimizer that asks all the available