svn commit: r1881460 - in /jackrabbit/oak/trunk/oak-doc/src/site/markdown/query: grammar-sql2.md.vm grammar-xpath.md.vm

[th...@apache.org]

Author: thomasm
Date: Fri Sep  4 16:01:29 2020
New Revision: 1881460

URL: http://svn.apache.org/viewvc?rev=1881460&view=rev
Log:
OAK-8910 Improve OAK Lucene Index Documentation

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

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=1881460&r1=1881459&r2=1881460&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 Fri Sep  4 16:01:29 2020
@@ -59,6 +59,11 @@ All queries should have a path restricti
 
 "union" combines the result of this query with the results of another query,
 where "union all" does not remove duplicates.
+Note that for fulltext queries, it is problematic to use union, 
+because scoring is done for each subquery individually.
+The score is not useful to compare results of different subqueries,
+so that the union of multiple fulltext queries won't be ordered by score
+as one might expect.
 
 "order by" may use an index.
 If there is no index for the given sort order, 
@@ -215,6 +220,11 @@ As a special case, sorting by "jcr:score
 (and if no fulltext index is used, then the score doesn't apply).
 If for some reason you want to enforce sorting by "jcr:score", then
 you can use the workaround to order by "LOWER([jcr:score]) DESC".
+Note that for fulltext queries, it is problematic to use union, 
+because scoring is done for each subquery individually.
+The score is not useful to compare results of different subqueries,
+so that the union of multiple fulltext queries won't be ordered by score
+as one might expect.
 
 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=1881460&r1=1881459&r2=1881460&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 Fri Sep  4 16:01:29 2020
@@ -93,6 +93,11 @@ It is supported only for compatibility.
 Queries using the construct `(filter1 | filter2)' are converted to union,
 that is, one query is generated for each filter, and the result of both
 queries is combined.
+Note that for fulltext queries, it is problematic to use union, 
+because scoring is done for each subquery individually.
+The score is not useful to compare results of different subqueries,
+so that the union of multiple fulltext queries won't be ordered by score
+as one might expect.
 
 Examples:
 
@@ -265,6 +270,11 @@ As a special case, sorting by "jcr:score
 (and if no fulltext index is used, then the score doesn't apply).
 If for some reason you want to enforce sorting by "jcr:score", then
 you can use the workaround to order by "fn:lowercase(@jcr:score) descending".
+Note that for fulltext queries, it is problematic to use union, 
+because scoring is done for each subquery individually.
+The score is not useful to compare results of different subqueries,
+so that the union of multiple fulltext queries won't be ordered by score
+as one might expect.
 
 Examples: