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
