Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id 1D31E200CED for ; Fri, 18 Aug 2017 11:35:42 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id 1ABAB16C8D9; Fri, 18 Aug 2017 09:35:42 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id BE1F316C8D7 for ; Fri, 18 Aug 2017 11:35:39 +0200 (CEST) Received: (qmail 26836 invoked by uid 500); 18 Aug 2017 09:35:38 -0000 Mailing-List: contact commits-help@jackrabbit.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@jackrabbit.apache.org Delivered-To: mailing list commits@jackrabbit.apache.org Received: (qmail 26821 invoked by uid 99); 18 Aug 2017 09:35:37 -0000 Received: from Unknown (HELO svn01-us-west.apache.org) (209.188.14.144) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 18 Aug 2017 09:35:37 +0000 Received: from svn01-us-west.apache.org (localhost [127.0.0.1]) by svn01-us-west.apache.org (ASF Mail Server at svn01-us-west.apache.org) with ESMTP id 4B5753A258F for ; Fri, 18 Aug 2017 09:35:34 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1805397 [2/3] - in /jackrabbit/site/live/oak/docs: ./ architecture/ coldstandby/ features/ nodestore/ nodestore/document/ nodestore/segment/ oak-mongo-js/ oak_api/ plugins/ query/ security/ security/accesscontrol/ security/authentication/ ... Date: Fri, 18 Aug 2017 09:35:30 -0000 To: commits@jackrabbit.apache.org From: thomasm@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20170818093534.4B5753A258F@svn01-us-west.apache.org> archived-at: Fri, 18 Aug 2017 09:35:42 -0000 Modified: jackrabbit/site/live/oak/docs/query/query-engine.html URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/query/query-engine.html?rev=1805397&r1=1805396&r2=1805397&view=diff ============================================================================== --- jackrabbit/site/live/oak/docs/query/query-engine.html (original) +++ jackrabbit/site/live/oak/docs/query/query-engine.html Fri Aug 18 09:35:29 2017 @@ -1,13 +1,13 @@ - + Jackrabbit Oak – The Query Engine @@ -131,7 +131,7 @@ + +
+

Query Option Index Tag

+

@since Oak 1.7.4 (OAK-937)

+

By default, queries will use the index with the lowest expected cost (as in relational databases). But in rare cases, it is needed to specify which index(es) should be considered for a query:

+ +
    + +
  • If there are multiple Lucene fulltext indexes with different aggregation rules, and the index data overlaps. In the query, you want to specify which aggregation rule to use.
    • + +
  • To temporarily work around limitations of the index implementation, for example incorrect cost estimation.
    • +
+

Using index tags should be the exception, and should only be used temporarily. To use index tags, add tags (a multi-valued String property) to the index(es) of choice, for example:

+ +
+
/oak:index/lucene/tags = [x, y]
+
+

Note each index can have multiple tags, and the same tag can be used in multiple indexes. The syntax to limit a query to a certain tag is: <query> option(index tag <tagName>):

+ +
+
/jcr:root/content//element(*, nt:file)[jcr:contains(., 'test')] option(index tag x)
+
+select * from [nt:file] 
+where ischildnode('/content')
+and contains(*, 'test')
+option(index tag [x])
+
+

The query will only consider the indexes that contain the specified tag (that is, possibly multiple indexes). Each query supports one tag only.

+

Limitations:

+ +
    + +
  • This is currently supported in indexes of type lucene compatVersion 2, and type property.
    • + +
  • For indexes of type lucene, when adding adding or changing the property tags, you need to also set the property refresh to true (Boolean), so that the change is applied. No indexing is required.
    • + +
  • Solr indexes, and the reference index, don’t support tags yet. That means they still might return a low cost, even if the tag does not match.
    • + +
  • 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.
    • +

Compatibility

@@ -488,8 +601,8 @@ for (FacetResult.Facet facet : facets) {

Nodes/Rows can still be retrieved from within the QueryResult object the usual way.

-

XPath to SQL2 Transformation

-

To support the XPath query language, such queries are internally converted to SQL2.

+

XPath to SQL-2 Transformation

+

To support the XPath query language, such queries are internally converted to SQL-2.

Every conversion is logged in debug level under the org.apache.jackrabbit.oak.query.QueryEngineImpl logger:

@@ -501,7 +614,7 @@ org.apache.jackrabbit.oak.query.QueryEng /* xpath: //element(*)[@sling:resourceType = 'slingevent:Lock' and @lock.created < xs:dateTime('2013-09-02T15:44:05.920+02:00')] */
-

Each transformed SQL2 query contains the original XPath query as a comment.

+

Each transformed SQL-2 query contains the original XPath query as a comment.

When converting from XPath to SQL-2, or conditions are automatically converted to union queries, so that indexes can be used for conditions of the form a = 'x' or b = 'y'.

The Node Type Index

@@ -510,21 +623,21 @@ org.apache.jackrabbit.oak.query.QueryEng

Temporarily Disabling an Index

To temporarily disable an index (for example for testing), set the index type to disabled. Please note that while the index type is not set, the index is not updated, so if you enable it again, it might not be correct. This is specially important for synchronous indexes.

-

The Ordered Index (deprecated since 1.1.8)

+

The Deprecated Ordered Index

This index has been deprecated in favour of Lucene Property index. Please refer to Lucene Index documentation for details.

For help on migrating to a Lucece index please refer to: Migrate ordered index

For historical information around the index please refer to: Ordered Index.

-

Index storage and manual inspection

+

Index Storage and Manual Inspection

Sometimes there is a need to inspect the index content for debugging (or pure curiosity). The index content is generally stored as content under the index definition as hidden nodes (this doesn’t apply to the solr index). In order to be able to browse down into an index content you need a low level repository tool that allows NodeStore level access. There are currently 2 options: the oak-console (command line tool, works will all existing NodeStore implementations) and the oak-explorer (gui based on java swing, works only with the SegmentNodeStore), both available as run modes of the oak-run module

The structure of the index is specific to each implementation and is subject to change. What is worth mentioning is that all the *PropertyIndex flavors store the content as unstructured nodes (clear readable text), the Lucene index is stored as binaries, so one would need to export the entire Lucene directory to the local file system and browse it using a dedicated tool.

-

SQL2 Optimisation

+

SQL-2 Optimisation

@since 1.3.9 with -Doak.query.sql2optimisation
-

Enabled by default in 1.3.11 it will perform a round of optimisation on the Query object obtained after parsing a SQL2 statement. It will for example attempt a conversion of OR conditions into UNION OAK-1617.

+

Enabled by default in 1.3.11 it will perform a round of optimisation on the Query object obtained after parsing a SQL-2 statement. It will for example attempt a conversion of OR conditions into UNION OAK-1617.

To disable it provide -Doak.query.sql2optimisation=false at the start-up.

Additional XPath and SQL-2 Features

Modified: jackrabbit/site/live/oak/docs/query/query-troubleshooting.html URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/query/query-troubleshooting.html?rev=1805397&r1=1805396&r2=1805397&view=diff ============================================================================== --- jackrabbit/site/live/oak/docs/query/query-troubleshooting.html (original) +++ jackrabbit/site/live/oak/docs/query/query-troubleshooting.html Fri Aug 18 09:35:29 2017 @@ -1,13 +1,13 @@ - + Jackrabbit Oak – Query Troubleshooting @@ -131,7 +131,7 @@