svn commit: r1811207 - in /jackrabbit/oak/trunk: oak-core/src/main/java/org/apache/jackrabbit/oak/query/QueryEngineSettingsService.java oak-doc/src/site/markdown/query/query-engine.md

[th...@apache.org]

Author: thomasm
Date: Thu Oct  5 13:26:19 2017
New Revision: 1811207

URL: http://svn.apache.org/viewvc?rev=1811207&view=rev
Log:
OAK-6623 Document QueryEngineSettings.FastQuerySize / QueryEngineSettingsService

Modified:
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/query/QueryEngineSettingsService.java
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md

Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/query/QueryEngineSettingsService.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/query/QueryEngineSettingsService.java?rev=1811207&r1=1811206&r2=1811207&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/query/QueryEngineSettingsService.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/query/QueryEngineSettingsService.java Thu Oct  5 13:26:19 2017
@@ -62,8 +62,10 @@ public class QueryEngineSettingsService
 
         @AttributeDefinition(
                 name = "Fast result size",
-                description = "Whether the query result size should return an estimation (or -1 if disabled) " +
-                        "for large queries"
+                description = "Whether the query result size (QueryResult.getSize()) should return an estimation for queries that return many nodes. " +
+                        "The estimate will be larger or equal the actual result size, as it includes unindexed properties and nodes that are not accessible. " +
+                        "If diabled, for such cases -1 is returned. " +
+                        "Note: even if enabled, getSize may still return -1 if the index used does not support the feature." 
         )
         boolean fastQuerySize() default false;
     }

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md?rev=1811207&r1=1811206&r2=1811207&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md Thu Oct  5 13:26:19 2017
@@ -200,19 +200,16 @@ Limitations:
 #### Result Size
 
 For NodeIterator.getSize(), some versions of Jackrabbit 2.x returned the estimated (raw)
-Lucene result set size, including nodes that are not accessible. 
-By default, Oak does not do this; it either returns the correct result size, or -1.
+Lucene result set size, including nodes that are not accessible.
 
+By default, Oak does not do this; it either returns the correct result size, or -1.
 Oak 1.2.x and newer supports a compatibility flag so that it works in the same way
-as Jackrabbit 2.x, by returning an estimate. See also OAK-2926.
-This is best configured as described in OAK-2977:
-When using Apache Sling, since Oak 1.3.x, 
-add the following line to the file `conf/sling.properties`,
-and then restart the application:
-
-    oak.query.fastResultSize=true
+as Jackrabbit 2.x, by returning an estimate (see OAK-2926).
+The estimate will be larger or equal the actual result size, 
+as it includes unindexed properties and nodes that are not accessible. 
 
-Please note this only works with the Lucene `compatVersion=2` right now.
+This only works with the Lucene `compatVersion=2` right now,
+so even if enabled, getSize may still return -1 if the index used does not support the feature.
 Example code to show how this work (where `test` is a common word in the index):
 
     String query = "//element(*, cq:Page)[jcr:contains(., 'test')]";
@@ -220,6 +217,13 @@ Example code to show how this work (wher
     QueryResult result = query.execute();
     long size = result.getRows().getSize();
 
+This is best configured via OSGi configuration (since Oak 1.6.x),
+or as described in OAK-2977, since Oak 1.3.x:
+When using Apache Sling, add the following line to the file `conf/sling.properties`,
+and then restart the application:
+
+    oak.query.fastResultSize=true
+
 #### Quoting
 
 The query parser is now generally more strict about invalid syntax.