Author: thomasm
Date: Thu Apr  5 08:53:05 2018
New Revision: 1828403

URL: http://svn.apache.org/viewvc?rev=1828403&view=rev
Log:
OAK-5051 Document XPath (and SQL-2) syntax as supported by Oak

Modified:
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-sql2.md.vm
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-xpath.md.vm
    
jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-troubleshooting.md

Modified: 
jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-sql2.md.vm
URL: 
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-sql2.md.vm?rev=1828403&r1=1828402&r2=1828403&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-sql2.md.vm 
(original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-sql2.md.vm Thu 
Apr  5 08:53:05 2018
@@ -271,6 +271,7 @@ The traversal option can be used to chan
 "index tag": by default, queries will use the index with the lowest expected 
cost (as in relational databases).
 To only consider some of the indexes, add tags (a multi-valued String 
property) to the index(es) of choice,
 and specify this tag in the query.
+See <a href="query-engine.html#Query_Option_Index_Tag">Query Option Index 
Tag</a>.
 
 Examples:
 

Modified: 
jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-xpath.md.vm
URL: 
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-xpath.md.vm?rev=1828403&r1=1828402&r2=1828403&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-xpath.md.vm 
(original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-xpath.md.vm 
Thu Apr  5 08:53:05 2018
@@ -313,6 +313,7 @@ The traversal option can be used to chan
 "index tag": by default, queries will use the index with the lowest expected 
cost (as in relational databases).
 To only consider some of the indexes, add tags (a multi-valued String 
property) to the index(es) of choice,
 and specify this tag in the query.
+See <a href="query-engine.html#Query_Option_Index_Tag">Query Option Index 
Tag</a>.
 
 Examples:
 

Modified: 
jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-troubleshooting.md
URL: 
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-troubleshooting.md?rev=1828403&r1=1828402&r2=1828403&view=diff
==============================================================================
--- 
jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-troubleshooting.md 
(original)
+++ 
jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-troubleshooting.md 
Thu Apr  5 08:53:05 2018
@@ -199,3 +199,60 @@ So in this case, only the fulltext restr
 but this might already be sufficient. If it is not, then the fulltext index 
might
 be changed to also index `commerceType`, or possibly 
 to use `evaluatePathRestrictions`.
+
+#### Queries With Many OR or UNION Conditions
+
+Queries that contain many "or" conditions, or with many "union" subqueries,
+can be slow as they have to read a lot of data.
+Example query:
+
+    /jcr:root/content/(a|b|c|d|e)//element(*, cq:Page)[
+    jcr:contains(@jcr:title, 'some text') 
+    or jcr:contains(jcr:content/@keywords, 'some text')
+    or jcr:contains(jcr:content/@cq:tags, 'some text')
+    or jcr:contains(jcr:content/@team, 'some text')
+    or jcr:contains(jcr:content/@topics, 'some text')
+    or jcr:contains(jcr:content/@jcr:description, 'some text')]
+
+This query will be internally converted into 5 subqueries, due to the "union" 
clause (a|b|c|d|e).
+Then, each of the 5 subqueries will run 6 subqueries: one for each 
jcr:contains condition.
+So, the index will be contacted 30 times.
+
+To avoid this overhead, the index could be changed (or a new index created) to 
do aggregation
+on the required properties (here: jcr:title, jcr:content/keywords,...).
+This will simplify the query to:
+
+    /jcr:root/content/(a|b|c|d|e)//element(*, cq:Page)[jcr:contains(., 'some 
text')]
+
+This should resolve most problems.
+To further speed up the query by avoiding to running 5 subqueries, 
+it might be better to use a less specific path constraint,
+but instead use a different way to filter results, such as:
+
+    /jcr:root/content//element(*, cq:Page)[jcr:contains(., 'some text') and 
@category='x']
+    
+#### Ordering by Score Combined With OR / UNION Conditions
+
+Queries that expect results to be sorted by score ("order by @jcr:score 
descending"),
+and use "union" or "or" conditions, may not return the result in the expected 
order,
+depending on the index(es) used. Example:
+
+    /jcr:root/conent/products/(indoor|outdoor)//*[jcr:contains(., 'test')] 
+    order by @jcr:score descending
+
+Here, the query is converted to a "union", and the result of both subqueries 
is combined.
+If the score for each subquery is not comparable (which is often the case for 
Lucene indexes),
+then the order of the results may not match the expected order.
+Instead of using path restrictions as above, it is most likely better to use a 
an additional
+condition in the query, and index that:
+
+    /jcr:root/content/products//*[jcr:contains(., 'test') and 
+    (@productTag='indoor' or @productTag='outdoor')] 
+    order by @jcr:score descending
+
+If this is not possible, then try to avoid using "union", and use an "or" 
condition as follows.
+This will only work for SQL-2 queries however:
+
+    select * from [nt:base] as a where contains(*, 'test') and issamenode(a, 
'/content') and 
+    ([jcr:path] like '/content/x800/%' or [jcr:path] like '/content/y900/%') 
+    order by [jcr:score] desc


Reply via email to