[jackrabbit-oak] branch trunk updated: OAK-9587 Add an attribute to enforce a strict index tag check (selectionPolicy)

[th...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

thomasm pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/jackrabbit-oak.git


The following commit(s) were added to refs/heads/trunk by this push:
     new ef9daef  OAK-9587 Add an attribute to enforce a strict index tag check (selectionPolicy)
ef9daef is described below

commit ef9daefb52340dd26a5513e0432c8016211ea9b8
Author: Thomas Mueller <th...@apache.org>
AuthorDate: Tue Feb 15 11:20:10 2022 +0100

    OAK-9587 Add an attribute to enforce a strict index tag check (selectionPolicy)
---
 oak-doc/src/site/markdown/query/lucene.md       | 10 ++++++++++
 oak-doc/src/site/markdown/query/query-engine.md | 26 +++++++++++++++++++++++--
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/oak-doc/src/site/markdown/query/lucene.md b/oak-doc/src/site/markdown/query/lucene.md
index 34d7b5e..465a46d 100644
--- a/oak-doc/src/site/markdown/query/lucene.md
+++ b/oak-doc/src/site/markdown/query/lucene.md
@@ -208,6 +208,14 @@ excludedPaths
 : List of paths which should be excluded from indexing.
   See [Path Includes/Excludes](#include-exclude) for details.
 
+tags
+: Optional multi value property. Defaults to empty.
+: List of [tags of this index][index-tags].
+
+selectionPolicy
+: Optional string property. Defaults to empty.
+: The [selection policy of this index][index-selection-policy].
+
 [maxFieldLength][OAK-2469]
 : Numbers of terms indexed per field. Defaults to 10000
 
@@ -2198,3 +2206,5 @@ SELECT rep:facet(title) FROM [app:Asset] WHERE [title] IS NOT NULL
 [score-explanation]: https://lucene.apache.org/core/4_6_0/core/org/apache/lucene/search/IndexSearcher.html#explain%28org.apache.lucene.search.Query,%20int%29
 [oak-lucene]: http://www.javadoc.io/doc/org.apache.jackrabbit/oak-lucene/
 [synchronous-lucene-property-indexes]: http://jackrabbit.apache.org/archive/wiki/JCR/Synchronous-Lucene-Property-Indexes_115513516.html
+[index-tags]: https://jackrabbit.apache.org/oak/docs/query/query-engine.html#Query_Option_Index_Tag
+[index-selection-policy]: https://jackrabbit.apache.org/oak/docs/query/query-engine.html#Index_Selection_Policy
diff --git a/oak-doc/src/site/markdown/query/query-engine.md b/oak-doc/src/site/markdown/query/query-engine.md
index 3c351c3..13d47dc 100644
--- a/oak-doc/src/site/markdown/query/query-engine.md
+++ b/oak-doc/src/site/markdown/query/query-engine.md
@@ -28,6 +28,7 @@ grep "^#.*$" src/site/markdown/query/query-engine.md | sed 's/#/    /g' | sed 's
     * [Query Options](#Query_Options)
         * [Query Option Traversal](#Query_Option_Traversal)
         * [Query Option Index Tag](#Query_Option_Index_Tag)
+        * [Index Selection Policy](#Index_Selection_Policy)
     * [Compatibility](#Compatibility)
         * [Result Size](#Result_Size)
         * [Quoting](#Quoting)
@@ -199,8 +200,29 @@ Limitations:
 * The nodetype index only partially supports this feature: if a tag is specified in the query, then the nodetype index
   is not used. However, tags in the nodetype index itself are ignored currently.
 * There is currently no way to disable traversal that way.
-  So if the expected cost of traversal is very low, the query will traverse.
-  Note that traversal is never used for fulltext queries.
+  So if the expected cost of traversal is very low (lower than the cost of any index),
+  the query will traverse.
+  To avoid traversal, note that indexes support cost overrides,
+  and traversal is never used for fulltext queries.
+
+#### Index Selection Policy
+
+`@since Oak 1.42.0 (OAK-9587)`
+
+To ensure an index is only used if the `option(index tag <tagName>)` is specified,
+certain index types support the `selectionPolicy`.
+If set to the value `tag`, an index is only used for queries
+that specify `option(index tag x)`, where `x` is one of the tags of this index.
+
+This feature allows to safely add an index, without risking that existing queries
+that don't specify the index tag will switch to this new index.
+
+Limitations:
+
+* This is currently supported in indexes of type `lucene` compatVersion 2, and type `property`.
+* For indexes of type `lucene`, when adding or changing the property `selectionPolicy`,
+  you need to also set the property `refresh` to `true` (Boolean),
+  so that the change is applied. No indexing is required.
 
 ### Compatibility