You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by ca...@apache.org on 2016/11/30 18:03:33 UTC
svn commit: r1772100 [4/6] - in /jackrabbit/site/live/oak/docs/query:
flags.html lucene-old.html lucene.html ootb-index-change.html
ordered-index-migrate.html ordered-index.html property-index.html
query-engine.html query.html solr.html
Modified: jackrabbit/site/live/oak/docs/query/property-index.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/query/property-index.html?rev=1772100&r1=1772099&r2=1772100&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/query/property-index.html (original)
+++ jackrabbit/site/live/oak/docs/query/property-index.html Wed Nov 30 18:03:33 2016
@@ -1,640 +1,640 @@
-<!DOCTYPE html>
-<!--
- | Generated by Apache Maven Doxia at 2016-11-29
- | Rendered using Apache Maven Fluido Skin 1.3.0
--->
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
- <head>
- <meta charset="UTF-8" />
- <meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20161129" />
- <meta http-equiv="Content-Language" content="en" />
- <title>Jackrabbit Oak - The Property Index</title>
- <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
- <link rel="stylesheet" href="../css/site.css" />
- <link rel="stylesheet" href="../css/print.css" media="print" />
-
-
- <script type="text/javascript" src="../js/apache-maven-fluido-1.3.0.min.js"></script>
-
-
- </head>
- <body class="topBarEnabled">
-
-
-
-
-
-
- <a href="http://github.com/apache/jackrabbit-oak">
- <img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;"
- src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png"
- alt="Fork me on GitHub">
- </a>
-
-
-
-
-
- <div id="topbar" class="navbar navbar-fixed-top ">
- <div class="navbar-inner">
- <div class="container-fluid">
- <a data-target=".nav-collapse" data-toggle="collapse" class="btn btn-navbar">
- <span class="icon-bar"></span>
- <span class="icon-bar"></span>
- <span class="icon-bar"></span>
- </a>
-
- <a class="brand" href="../" title="Oak logo">
-
-
- <img src="../oak_logo.png" alt="Oak logo" />
-
- </a>
-
- <ul class="nav">
- <li class="dropdown">
- <a href="#" class="dropdown-toggle" data-toggle="dropdown">Overview <b class="caret"></b></a>
- <ul class="dropdown-menu">
-
- <li> <a href="../index.html" title="Jackrabbit Oak">Jackrabbit Oak</a>
-</li>
-
- <li> <a href="../license.html" title="License">License</a>
-</li>
-
- <li> <a href="../downloads.html" title="Downloads">Downloads</a>
-</li>
- </ul>
- </li>
- <li class="dropdown">
- <a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts and Architecture <b class="caret"></b></a>
- <ul class="dropdown-menu">
-
- <li> <a href="../architecture/overview.html" title="Overview">Overview</a>
-</li>
-
- <li> <a href="../architecture/nodestate.html" title="The Node State Model">The Node State Model</a>
-</li>
- </ul>
- </li>
- <li class="dropdown">
- <a href="#" class="dropdown-toggle" data-toggle="dropdown">Main APIs <b class="caret"></b></a>
- <ul class="dropdown-menu">
-
- <li> <a href="http://www.day.com/specs/jcr/2.0/index.html" title="JCR API">JCR API</a>
-</li>
-
- <li> <a href="../oak_api/overview.html" title="Oak API">Oak API</a>
-</li>
- </ul>
- </li>
- <li class="dropdown">
- <a href="#" class="dropdown-toggle" data-toggle="dropdown">Features and Plugins <b class="caret"></b></a>
- <ul class="dropdown-menu">
-
- <li> <a href="../features/atomic-counter.html" title="Atomic Counter">Atomic Counter</a>
-</li>
-
- <li> <a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
-</li>
-
- <li> <a href="../clustering.html" title="Clustering">Clustering</a>
-</li>
-
- <li> <a href="../nodestore/documentmk.html" title="DocumentNodeStore">DocumentNodeStore</a>
-</li>
-
- <li> <a href="../nodestore/overview.html" title="Node Storage">Node Storage</a>
-</li>
-
- <li> <a href="../nodestore/persistent-cache.html" title="Persistent Cache">Persistent Cache</a>
-</li>
-
- <li> <a href="../query/query.html" title="Query">Query</a>
-</li>
-
- <li> <a href="../security/overview.html" title="Security">Security</a>
-</li>
-
- <li> <a href="../nodestore/segment/overview.html" title="Segment Node Store">Segment Node Store</a>
-</li>
- </ul>
- </li>
- <li class="dropdown">
- <a href="#" class="dropdown-toggle" data-toggle="dropdown">Using Oak <b class="caret"></b></a>
- <ul class="dropdown-menu">
-
- <li> <a href="../use_getting_started.html" title="Getting Started">Getting Started</a>
-</li>
-
- <li> <a href="../construct.html" title="Repository Construction">Repository Construction</a>
-</li>
-
- <li> <a href="../osgi_config.html" title="Configuring Oak">Configuring Oak</a>
-</li>
-
- <li> <a href="../command_line.html" title="Command Line Tools">Command Line Tools</a>
-</li>
-
- <li> <a href="../migration.html" title="Migration">Migration</a>
-</li>
-
- <li> <a href="../differences.html" title="Differences to Jackrabbit 2">Differences to Jackrabbit 2</a>
-</li>
-
- <li> <a href="../known_issues.html" title="Known Issues">Known Issues</a>
-</li>
-
- <li> <a href="../dos_and_donts.html" title="Dos and Don'ts">Dos and Don'ts</a>
-</li>
-
- <li> <a href="../coldstandby/coldstandby.html" title="Cold Standby">Cold Standby</a>
-</li>
-
- <li> <a href="../FAQ.html" title="FAQ">FAQ</a>
-</li>
- </ul>
- </li>
- <li class="dropdown">
- <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developing Oak <b class="caret"></b></a>
- <ul class="dropdown-menu">
-
- <li> <a href="../dev_getting_started.html" title="Getting Started">Getting Started</a>
-</li>
-
- <li> <a href="../participating.html" title="Participating">Participating</a>
-</li>
-
- <li> <a href="../developing-with-git.html" title="Developing with Git">Developing with Git</a>
-</li>
-
- <li> <a href="../diagnostic-builds.html" title="Cutting diagnostic builds">Cutting diagnostic builds</a>
-</li>
-
- <li> <a href="../attribution.html" title="Attribution">Attribution</a>
-</li>
-
- <li> <a href="../release-schedule.html" title="Release Schedule">Release Schedule</a>
-</li>
- </ul>
- </li>
- <li class="dropdown">
- <a href="#" class="dropdown-toggle" data-toggle="dropdown">Links <b class="caret"></b></a>
- <ul class="dropdown-menu">
-
- <li> <a href="http://jackrabbit.apache.org/oak" title="Apache Jackrabbit Oak">Apache Jackrabbit Oak</a>
-</li>
-
- <li> <a href="http://jackrabbit.apache.org/" title="Apache Jackrabbit">Apache Jackrabbit</a>
-</li>
- </ul>
- </li>
- </ul>
-
-
-
-
- </div>
-
- </div>
- </div>
- </div>
-
- <div class="container-fluid">
- <div id="banner">
- <div class="pull-left">
- <div id="bannerLeft">
- <h2>Oak Documentation</h2>
- </div>
- </div>
- <div class="pull-right"> </div>
- <div class="clear"><hr/></div>
- </div>
-
- <div id="breadcrumbs">
- <ul class="breadcrumb">
-
-
- <li id="publishDate">Last Published: 2016-11-29</li>
- <li class="divider">|</li> <li id="projectVersion">Version: 1.6-SNAPSHOT</li>
-
-
-
-
- </ul>
- </div>
-
-
- <div class="row-fluid">
- <div id="leftColumn" class="span3">
- <div class="well sidebar-nav">
-
-
- <ul class="nav nav-list">
- <li class="nav-header">Overview</li>
-
- <li>
-
- <a href="../index.html" title="Jackrabbit Oak">
- <i class="none"></i>
- Jackrabbit Oak</a>
- </li>
-
- <li>
-
- <a href="../license.html" title="License">
- <i class="none"></i>
- License</a>
- </li>
-
- <li>
-
- <a href="../downloads.html" title="Downloads">
- <i class="none"></i>
- Downloads</a>
- </li>
- <li class="nav-header">Concepts and Architecture</li>
-
- <li>
-
- <a href="../architecture/overview.html" title="Overview">
- <i class="none"></i>
- Overview</a>
- </li>
-
- <li>
-
- <a href="../architecture/nodestate.html" title="The Node State Model">
- <i class="none"></i>
- The Node State Model</a>
- </li>
- <li class="nav-header">Main APIs</li>
-
- <li>
-
- <a href="http://www.day.com/specs/jcr/2.0/index.html" class="externalLink" title="JCR API">
- <i class="none"></i>
- JCR API</a>
- </li>
-
- <li>
-
- <a href="../oak_api/overview.html" title="Oak API">
- <i class="none"></i>
- Oak API</a>
- </li>
- <li class="nav-header">Features and Plugins</li>
-
- <li>
-
- <a href="../features/atomic-counter.html" title="Atomic Counter">
- <i class="none"></i>
- Atomic Counter</a>
- </li>
-
- <li>
-
- <a href="../plugins/blobstore.html" title="Blob Storage">
- <i class="none"></i>
- Blob Storage</a>
- </li>
-
- <li>
-
- <a href="../clustering.html" title="Clustering">
- <i class="none"></i>
- Clustering</a>
- </li>
-
- <li>
-
- <a href="../nodestore/documentmk.html" title="DocumentNodeStore">
- <i class="none"></i>
- DocumentNodeStore</a>
- </li>
-
- <li>
-
- <a href="../nodestore/overview.html" title="Node Storage">
- <i class="none"></i>
- Node Storage</a>
- </li>
-
- <li>
-
- <a href="../nodestore/persistent-cache.html" title="Persistent Cache">
- <i class="none"></i>
- Persistent Cache</a>
- </li>
-
- <li>
-
- <a href="../query/query.html" title="Query">
- <i class="none"></i>
- Query</a>
- </li>
-
- <li>
-
- <a href="../security/overview.html" title="Security">
- <i class="none"></i>
- Security</a>
- </li>
-
- <li>
-
- <a href="../nodestore/segment/overview.html" title="Segment Node Store">
- <i class="none"></i>
- Segment Node Store</a>
- </li>
- <li class="nav-header">Using Oak</li>
-
- <li>
-
- <a href="../use_getting_started.html" title="Getting Started">
- <i class="none"></i>
- Getting Started</a>
- </li>
-
- <li>
-
- <a href="../construct.html" title="Repository Construction">
- <i class="none"></i>
- Repository Construction</a>
- </li>
-
- <li>
-
- <a href="../osgi_config.html" title="Configuring Oak">
- <i class="none"></i>
- Configuring Oak</a>
- </li>
-
- <li>
-
- <a href="../command_line.html" title="Command Line Tools">
- <i class="none"></i>
- Command Line Tools</a>
- </li>
-
- <li>
-
- <a href="../migration.html" title="Migration">
- <i class="none"></i>
- Migration</a>
- </li>
-
- <li>
-
- <a href="../differences.html" title="Differences to Jackrabbit 2">
- <i class="none"></i>
- Differences to Jackrabbit 2</a>
- </li>
-
- <li>
-
- <a href="../known_issues.html" title="Known Issues">
- <i class="none"></i>
- Known Issues</a>
- </li>
-
- <li>
-
- <a href="../dos_and_donts.html" title="Dos and Don'ts">
- <i class="none"></i>
- Dos and Don'ts</a>
- </li>
-
- <li>
-
- <a href="../coldstandby/coldstandby.html" title="Cold Standby">
- <i class="none"></i>
- Cold Standby</a>
- </li>
-
- <li>
-
- <a href="../FAQ.html" title="FAQ">
- <i class="none"></i>
- FAQ</a>
- </li>
- <li class="nav-header">Developing Oak</li>
-
- <li>
-
- <a href="../dev_getting_started.html" title="Getting Started">
- <i class="none"></i>
- Getting Started</a>
- </li>
-
- <li>
-
- <a href="../participating.html" title="Participating">
- <i class="none"></i>
- Participating</a>
- </li>
-
- <li>
-
- <a href="../developing-with-git.html" title="Developing with Git">
- <i class="none"></i>
- Developing with Git</a>
- </li>
-
- <li>
-
- <a href="../diagnostic-builds.html" title="Cutting diagnostic builds">
- <i class="none"></i>
- Cutting diagnostic builds</a>
- </li>
-
- <li>
-
- <a href="../attribution.html" title="Attribution">
- <i class="none"></i>
- Attribution</a>
- </li>
-
- <li>
-
- <a href="../release-schedule.html" title="Release Schedule">
- <i class="none"></i>
- Release Schedule</a>
- </li>
- <li class="nav-header">Links</li>
-
- <li>
-
- <a href="http://jackrabbit.apache.org/oak" class="externalLink" title="Apache Jackrabbit Oak">
- <i class="none"></i>
- Apache Jackrabbit Oak</a>
- </li>
-
- <li>
-
- <a href="http://jackrabbit.apache.org/" class="externalLink" title="Apache Jackrabbit">
- <i class="none"></i>
- Apache Jackrabbit</a>
- </li>
- </ul>
-
-
-
- <hr class="divider" />
-
- <div id="poweredBy">
-
- <script type="text/javascript" src="https://apis.google.com/js/plusone.js"></script>
-
-
- <div class="g-plusone" data-href="http://jackrabbit.apache.org/oak/docs/" data-size="tall" ></div>
-
- <div class="clear"></div>
- <div class="clear"></div>
- <div class="clear"></div>
- <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
- <img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" />
- </a>
- </div>
- </div>
- </div>
-
-
- <div id="bodyColumn" class="span9" >
-
- <!-- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License. --><div class="section">
-<h2>The Property Index<a name="The_Property_Index"></a></h2>
-<p>Is useful whenever there is a query with a property constraint that is not full-text:</p>
-
-<div class="source">
-<pre>SELECT * FROM [nt:base] WHERE [jcr:uuid] = $id
-</pre></div>
-<p>To define a property index, you have to add an index definition node that:</p>
-
-<ul>
-
-<li>Must be a child node of <tt>/oak:index</tt>.</li>
-
-<li>Must be of type <tt>oak:QueryIndexDefinition</tt>.</li>
-
-<li><tt>type</tt> (String) must have the property set to “property”.</li>
-
-<li><tt>propertyNames</tt> (Name, multi-valued): the property to be indexed. This is a multi-valued property, and must not be empty. It usually contains only <i>one</i> property name. All nodes that have <i>any</i> of those properties are stored in this index.</li>
-
-<li><tt>includedPaths</tt> (String, multi-valued): the paths that are included (‘/’ if not set). The index is only used if the query has a path restriction that is not excluded, and part of the included paths.</li>
-
-<li><tt>excludedPaths</tt> (String, multi-valued): the paths where this index is excluded (none if not set). The index is only used if the query has a path restriction that is not excluded, and part of the included paths.</li>
-</ul>
-<p>It is recommended to index one property per index. (If multiple properties are indexed within one index, then the index contains all nodes that has either one of the properties, which can make the query less efficient, and can make the query pick the wrong index.)</p>
-<p>Optionally you can specify:</p>
-
-<ul>
-
-<li><tt>declaringNodeTypes</tt> (Name, multi-valued): the index only applies to a certain node type.</li>
-
-<li><tt>unique</tt> (Boolean): if set to <tt>true</tt>, a uniqueness constraint on this property is added. Ensure you set declaringNodeTypes, otherwise all nodes of the repository are affected (which is most likely not what you want), and you are not able to version the node.</li>
-
-<li><tt>entryCount</tt> (Long): the estimated number of path entries in the index, to override the cost estimation (a high entry count means a high cost).</li>
-
-<li><tt>keyCount</tt> (Long), the estimated number of keys in the index, to override the cost estimation (a high key count means a lower cost and a low key count means a high cost when searching for specific keys; has no effect when searching for “is not null”).</li>
-
-<li><tt>reindex</tt> (Boolean): if set to <tt>true</tt>, the full content is re-indexed. This can take a long time, and is run synchronously with storing the index (except with an async index). See “Reindexing” below for details.</li>
-</ul>
-<p>Example:</p>
-
-<div class="source">
-<pre>{
- NodeBuilder index = root.child("oak:index");
- index.child("uuid")
- .setProperty("jcr:primaryType", "oak:QueryIndexDefinition", Type.NAME)
- .setProperty("type", "property")
- .setProperty("propertyNames", "jcr:uuid")
- .setProperty("declaringNodeTypes", "mix:referenceable")
- .setProperty("unique", true)
- .setProperty("reindex", true);
-}
-</pre></div>
-<p>or to simplify you can use one of the existing <tt>IndexUtils#createIndexDefinition</tt> helper methods:</p>
-
-<div class="source">
-<pre>{
- NodeBuilder index = IndexUtils.getOrCreateOakIndex(root);
- IndexUtils.createIndexDefinition(index, "myProp", true, false, ImmutableList.of("myProp"), null);
-}
-</pre></div>
-<div class="section">
-<div class="section">
-<h4>Reindexing<a name="Reindexing"></a></h4>
-<p>Usually, reindexing is only needed if the configuration of an index is changed, such that the index should contain more or different data. For example, reindexing is needed if the property to be indexed is changed, if a nodetype is added to <b><tt>declaringNodeTypes</tt></b>, or if <b><tt>includedPaths</tt></b> is changed. It is not strictly needed if less data is to be indexed, for example if a nodetype is removed. However, to save space, it might make sense to reindex even in that case. Typically, if a query does not return the expected result, reindexing does not help; more likely, the reason in somewhere else to be found, and disabling the index should be tried first.</p>
-<p>Reindexing a property index happens synchronously by setting the <b><tt>reindex</tt></b> flag to <b><tt>true</tt></b>. This means that the first #save call will generate a full repository traversal with the purpose of building the index content and it might take a long time.</p>
-<p>Asynchronous reindexing of a property index is available as of OAK-1456. The way this works is by pushing the property index updates to a background job and when the indexing process is done, the property definition will be switched back to a synchronous updates mode. To enable this async reindex behaviour you need to first set the <b><tt>reindex-async</tt></b> and <b><tt>reindex</tt></b> flags to <b><tt>true</tt></b> (call #save). You can verify the initial setup worked by refreshing the index definition node and looking for the <b><tt>async</tt></b> = <b><tt>async-reindex</tt></b> property. Next you need to start the dedicated background job via a jmx call to the <b><tt>PropertyIndexAsyncReindex#startPropertyIndexAsyncReindex</tt></b> MBean.</p>
-<p>Example:</p>
-
-<div class="source">
-<pre>{
- NodeBuilder index = root.child("oak:index");
- index.child("property")
- .setProperty("reindex-async", true)
- .setProperty("reindex", true);
-}
-</pre></div></div>
-<div class="section">
-<h4>Cost Estimation<a name="Cost_Estimation"></a></h4>
-<p>When running a query, the property index reports its estimated cost to the query engine, and then the query engine picks the index with the lowest cost (cost-based query optimization). The algorithm to calculate the estimated cost is roughly as follows (a bit simplified):</p>
-
-<ul>
-
-<li>The cost is infinity (so the index is never used) if the condition contains a fulltext constraint, no applicable restriction, the wrong nodetype, or if the path filtering (<tt>includedPaths</tt> / <tt>excludedPaths</tt>) does not match the query.</li>
-
-<li>For the nodetype index, the cost is the sum of the cost for the <tt>jcr:primaryType</tt> lookup (if the primary type is known), plus the cost for the <tt>jcr:mixinTypes</tt> lookup (if that is known).</li>
-
-<li>Otherwise, the cost is based on the overhead (which is 2), plus the estimated number of entries.</li>
-
-<li>For an “x is not null” condition, the estimated number of entries is either the configured <tt>entryCount</tt> or, if not set, the approximate number of entries in the index. The approximation is an “order of magnitude” estimation (Morris’ algorithm).</li>
-
-<li>For a unique index and “x = 1” condition, the estimated number of entries is either 0 or 1 (depending on whether the key is found).</li>
-
-<li>For a non-unique index and a “x = 1” condition, if the <tt>entryCount</tt> and <tt>keyCount</tt> are set, those setting are used to estimate the number of entries. If not, the approximate number of entries for the key is read (maintained using Morris’ algorithm). In addition to that, the path condition is used to scale down the estimated count depending on the approximate number of nodes in that subtree versus the approximate number of entries in the repository, using approximation available via the <tt>counter</tt> index.</li>
-</ul>
-<p>For example, for a query with path restriction “/content/products/t-shirts” and property restriction “color = ‘red’”, if there is an index for the property “color”, then the entry count approximation is read from the index. Let’s say it is 10’000 for this value. Then the approximate number of nodes in the subtree “/content/products/t-shirts” is read (let’s say it is 20’000), and the approximate number of nodes in the repository (let’s say it is 1 million). Therefore, the estimated number of entries is scaled down (divided by 50) from 10’000 to 200. The estimated cost is therefore 202, due to the overhead of 2.</p></div></div></div>
- </div>
- </div>
- </div>
-
- <hr/>
-
- <footer>
- <div class="container-fluid">
- <div class="row span12">Copyright © 2012-2016
- <a href="http://www.apache.org/">The Apache Software Foundation</a>.
- All Rights Reserved.
-
- </div>
-
-
-
-
-
-
-
- <div id="ohloh" class="pull-right">
- <script type="text/javascript" src="http://www.ohloh.net/p/jackrabbit-oak/widgets/project_thin_badge.js"></script>
- </div>
- </div>
- </footer>
- </body>
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 2016-11-30
+ | Rendered using Apache Maven Fluido Skin 1.3.0
+-->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta name="Date-Revision-yyyymmdd" content="20161130" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Jackrabbit Oak - The Property Index</title>
+ <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
+ <link rel="stylesheet" href="../css/site.css" />
+ <link rel="stylesheet" href="../css/print.css" media="print" />
+
+
+ <script type="text/javascript" src="../js/apache-maven-fluido-1.3.0.min.js"></script>
+
+
+ </head>
+ <body class="topBarEnabled">
+
+
+
+
+
+
+ <a href="http://github.com/apache/jackrabbit-oak">
+ <img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;"
+ src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png"
+ alt="Fork me on GitHub">
+ </a>
+
+
+
+
+
+ <div id="topbar" class="navbar navbar-fixed-top ">
+ <div class="navbar-inner">
+ <div class="container-fluid">
+ <a data-target=".nav-collapse" data-toggle="collapse" class="btn btn-navbar">
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ </a>
+
+ <a class="brand" href="../" title="Oak logo">
+
+
+ <img src="../oak_logo.png" alt="Oak logo" />
+
+ </a>
+
+ <ul class="nav">
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Overview <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="../index.html" title="Jackrabbit Oak">Jackrabbit Oak</a>
+</li>
+
+ <li> <a href="../license.html" title="License">License</a>
+</li>
+
+ <li> <a href="../downloads.html" title="Downloads">Downloads</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts and Architecture <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="../architecture/overview.html" title="Overview">Overview</a>
+</li>
+
+ <li> <a href="../architecture/nodestate.html" title="The Node State Model">The Node State Model</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Main APIs <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="http://www.day.com/specs/jcr/2.0/index.html" title="JCR API">JCR API</a>
+</li>
+
+ <li> <a href="../oak_api/overview.html" title="Oak API">Oak API</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Features and Plugins <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="../features/atomic-counter.html" title="Atomic Counter">Atomic Counter</a>
+</li>
+
+ <li> <a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
+</li>
+
+ <li> <a href="../clustering.html" title="Clustering">Clustering</a>
+</li>
+
+ <li> <a href="../nodestore/documentmk.html" title="DocumentNodeStore">DocumentNodeStore</a>
+</li>
+
+ <li> <a href="../nodestore/overview.html" title="Node Storage">Node Storage</a>
+</li>
+
+ <li> <a href="../nodestore/persistent-cache.html" title="Persistent Cache">Persistent Cache</a>
+</li>
+
+ <li> <a href="../query/query.html" title="Query">Query</a>
+</li>
+
+ <li> <a href="../security/overview.html" title="Security">Security</a>
+</li>
+
+ <li> <a href="../nodestore/segment/overview.html" title="Segment Node Store">Segment Node Store</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Using Oak <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="../use_getting_started.html" title="Getting Started">Getting Started</a>
+</li>
+
+ <li> <a href="../construct.html" title="Repository Construction">Repository Construction</a>
+</li>
+
+ <li> <a href="../osgi_config.html" title="Configuring Oak">Configuring Oak</a>
+</li>
+
+ <li> <a href="../command_line.html" title="Command Line Tools">Command Line Tools</a>
+</li>
+
+ <li> <a href="../migration.html" title="Migration">Migration</a>
+</li>
+
+ <li> <a href="../differences.html" title="Differences to Jackrabbit 2">Differences to Jackrabbit 2</a>
+</li>
+
+ <li> <a href="../known_issues.html" title="Known Issues">Known Issues</a>
+</li>
+
+ <li> <a href="../dos_and_donts.html" title="Dos and Don'ts">Dos and Don'ts</a>
+</li>
+
+ <li> <a href="../coldstandby/coldstandby.html" title="Cold Standby">Cold Standby</a>
+</li>
+
+ <li> <a href="../FAQ.html" title="FAQ">FAQ</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developing Oak <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="../dev_getting_started.html" title="Getting Started">Getting Started</a>
+</li>
+
+ <li> <a href="../participating.html" title="Participating">Participating</a>
+</li>
+
+ <li> <a href="../developing-with-git.html" title="Developing with Git">Developing with Git</a>
+</li>
+
+ <li> <a href="../diagnostic-builds.html" title="Cutting diagnostic builds">Cutting diagnostic builds</a>
+</li>
+
+ <li> <a href="../attribution.html" title="Attribution">Attribution</a>
+</li>
+
+ <li> <a href="../release-schedule.html" title="Release Schedule">Release Schedule</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Links <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="http://jackrabbit.apache.org/oak" title="Apache Jackrabbit Oak">Apache Jackrabbit Oak</a>
+</li>
+
+ <li> <a href="http://jackrabbit.apache.org/" title="Apache Jackrabbit">Apache Jackrabbit</a>
+</li>
+ </ul>
+ </li>
+ </ul>
+
+
+
+
+ </div>
+
+ </div>
+ </div>
+ </div>
+
+ <div class="container-fluid">
+ <div id="banner">
+ <div class="pull-left">
+ <div id="bannerLeft">
+ <h2>Oak Documentation</h2>
+ </div>
+ </div>
+ <div class="pull-right"> </div>
+ <div class="clear"><hr/></div>
+ </div>
+
+ <div id="breadcrumbs">
+ <ul class="breadcrumb">
+
+
+ <li id="publishDate">Last Published: 2016-11-30</li>
+ <li class="divider">|</li> <li id="projectVersion">Version: 1.6-SNAPSHOT</li>
+
+
+
+
+ </ul>
+ </div>
+
+
+ <div class="row-fluid">
+ <div id="leftColumn" class="span3">
+ <div class="well sidebar-nav">
+
+
+ <ul class="nav nav-list">
+ <li class="nav-header">Overview</li>
+
+ <li>
+
+ <a href="../index.html" title="Jackrabbit Oak">
+ <i class="none"></i>
+ Jackrabbit Oak</a>
+ </li>
+
+ <li>
+
+ <a href="../license.html" title="License">
+ <i class="none"></i>
+ License</a>
+ </li>
+
+ <li>
+
+ <a href="../downloads.html" title="Downloads">
+ <i class="none"></i>
+ Downloads</a>
+ </li>
+ <li class="nav-header">Concepts and Architecture</li>
+
+ <li>
+
+ <a href="../architecture/overview.html" title="Overview">
+ <i class="none"></i>
+ Overview</a>
+ </li>
+
+ <li>
+
+ <a href="../architecture/nodestate.html" title="The Node State Model">
+ <i class="none"></i>
+ The Node State Model</a>
+ </li>
+ <li class="nav-header">Main APIs</li>
+
+ <li>
+
+ <a href="http://www.day.com/specs/jcr/2.0/index.html" class="externalLink" title="JCR API">
+ <i class="none"></i>
+ JCR API</a>
+ </li>
+
+ <li>
+
+ <a href="../oak_api/overview.html" title="Oak API">
+ <i class="none"></i>
+ Oak API</a>
+ </li>
+ <li class="nav-header">Features and Plugins</li>
+
+ <li>
+
+ <a href="../features/atomic-counter.html" title="Atomic Counter">
+ <i class="none"></i>
+ Atomic Counter</a>
+ </li>
+
+ <li>
+
+ <a href="../plugins/blobstore.html" title="Blob Storage">
+ <i class="none"></i>
+ Blob Storage</a>
+ </li>
+
+ <li>
+
+ <a href="../clustering.html" title="Clustering">
+ <i class="none"></i>
+ Clustering</a>
+ </li>
+
+ <li>
+
+ <a href="../nodestore/documentmk.html" title="DocumentNodeStore">
+ <i class="none"></i>
+ DocumentNodeStore</a>
+ </li>
+
+ <li>
+
+ <a href="../nodestore/overview.html" title="Node Storage">
+ <i class="none"></i>
+ Node Storage</a>
+ </li>
+
+ <li>
+
+ <a href="../nodestore/persistent-cache.html" title="Persistent Cache">
+ <i class="none"></i>
+ Persistent Cache</a>
+ </li>
+
+ <li>
+
+ <a href="../query/query.html" title="Query">
+ <i class="none"></i>
+ Query</a>
+ </li>
+
+ <li>
+
+ <a href="../security/overview.html" title="Security">
+ <i class="none"></i>
+ Security</a>
+ </li>
+
+ <li>
+
+ <a href="../nodestore/segment/overview.html" title="Segment Node Store">
+ <i class="none"></i>
+ Segment Node Store</a>
+ </li>
+ <li class="nav-header">Using Oak</li>
+
+ <li>
+
+ <a href="../use_getting_started.html" title="Getting Started">
+ <i class="none"></i>
+ Getting Started</a>
+ </li>
+
+ <li>
+
+ <a href="../construct.html" title="Repository Construction">
+ <i class="none"></i>
+ Repository Construction</a>
+ </li>
+
+ <li>
+
+ <a href="../osgi_config.html" title="Configuring Oak">
+ <i class="none"></i>
+ Configuring Oak</a>
+ </li>
+
+ <li>
+
+ <a href="../command_line.html" title="Command Line Tools">
+ <i class="none"></i>
+ Command Line Tools</a>
+ </li>
+
+ <li>
+
+ <a href="../migration.html" title="Migration">
+ <i class="none"></i>
+ Migration</a>
+ </li>
+
+ <li>
+
+ <a href="../differences.html" title="Differences to Jackrabbit 2">
+ <i class="none"></i>
+ Differences to Jackrabbit 2</a>
+ </li>
+
+ <li>
+
+ <a href="../known_issues.html" title="Known Issues">
+ <i class="none"></i>
+ Known Issues</a>
+ </li>
+
+ <li>
+
+ <a href="../dos_and_donts.html" title="Dos and Don'ts">
+ <i class="none"></i>
+ Dos and Don'ts</a>
+ </li>
+
+ <li>
+
+ <a href="../coldstandby/coldstandby.html" title="Cold Standby">
+ <i class="none"></i>
+ Cold Standby</a>
+ </li>
+
+ <li>
+
+ <a href="../FAQ.html" title="FAQ">
+ <i class="none"></i>
+ FAQ</a>
+ </li>
+ <li class="nav-header">Developing Oak</li>
+
+ <li>
+
+ <a href="../dev_getting_started.html" title="Getting Started">
+ <i class="none"></i>
+ Getting Started</a>
+ </li>
+
+ <li>
+
+ <a href="../participating.html" title="Participating">
+ <i class="none"></i>
+ Participating</a>
+ </li>
+
+ <li>
+
+ <a href="../developing-with-git.html" title="Developing with Git">
+ <i class="none"></i>
+ Developing with Git</a>
+ </li>
+
+ <li>
+
+ <a href="../diagnostic-builds.html" title="Cutting diagnostic builds">
+ <i class="none"></i>
+ Cutting diagnostic builds</a>
+ </li>
+
+ <li>
+
+ <a href="../attribution.html" title="Attribution">
+ <i class="none"></i>
+ Attribution</a>
+ </li>
+
+ <li>
+
+ <a href="../release-schedule.html" title="Release Schedule">
+ <i class="none"></i>
+ Release Schedule</a>
+ </li>
+ <li class="nav-header">Links</li>
+
+ <li>
+
+ <a href="http://jackrabbit.apache.org/oak" class="externalLink" title="Apache Jackrabbit Oak">
+ <i class="none"></i>
+ Apache Jackrabbit Oak</a>
+ </li>
+
+ <li>
+
+ <a href="http://jackrabbit.apache.org/" class="externalLink" title="Apache Jackrabbit">
+ <i class="none"></i>
+ Apache Jackrabbit</a>
+ </li>
+ </ul>
+
+
+
+ <hr class="divider" />
+
+ <div id="poweredBy">
+
+ <script type="text/javascript" src="https://apis.google.com/js/plusone.js"></script>
+
+
+ <div class="g-plusone" data-href="http://jackrabbit.apache.org/oak/docs/" data-size="tall" ></div>
+
+ <div class="clear"></div>
+ <div class="clear"></div>
+ <div class="clear"></div>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" />
+ </a>
+ </div>
+ </div>
+ </div>
+
+
+ <div id="bodyColumn" class="span9" >
+
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License. --><div class="section">
+<h2>The Property Index<a name="The_Property_Index"></a></h2>
+<p>Is useful whenever there is a query with a property constraint that is not full-text:</p>
+
+<div class="source">
+<pre>SELECT * FROM [nt:base] WHERE [jcr:uuid] = $id
+</pre></div>
+<p>To define a property index, you have to add an index definition node that:</p>
+
+<ul>
+
+<li>Must be a child node of <tt>/oak:index</tt>.</li>
+
+<li>Must be of type <tt>oak:QueryIndexDefinition</tt>.</li>
+
+<li><tt>type</tt> (String) must have the property set to “property”.</li>
+
+<li><tt>propertyNames</tt> (Name, multi-valued): the property to be indexed. This is a multi-valued property, and must not be empty. It usually contains only <i>one</i> property name. All nodes that have <i>any</i> of those properties are stored in this index.</li>
+
+<li><tt>includedPaths</tt> (String, multi-valued): the paths that are included (‘/’ if not set). The index is only used if the query has a path restriction that is not excluded, and part of the included paths.</li>
+
+<li><tt>excludedPaths</tt> (String, multi-valued): the paths where this index is excluded (none if not set). The index is only used if the query has a path restriction that is not excluded, and part of the included paths.</li>
+</ul>
+<p>It is recommended to index one property per index. (If multiple properties are indexed within one index, then the index contains all nodes that has either one of the properties, which can make the query less efficient, and can make the query pick the wrong index.)</p>
+<p>Optionally you can specify:</p>
+
+<ul>
+
+<li><tt>declaringNodeTypes</tt> (Name, multi-valued): the index only applies to a certain node type.</li>
+
+<li><tt>unique</tt> (Boolean): if set to <tt>true</tt>, a uniqueness constraint on this property is added. Ensure you set declaringNodeTypes, otherwise all nodes of the repository are affected (which is most likely not what you want), and you are not able to version the node.</li>
+
+<li><tt>entryCount</tt> (Long): the estimated number of path entries in the index, to override the cost estimation (a high entry count means a high cost).</li>
+
+<li><tt>keyCount</tt> (Long), the estimated number of keys in the index, to override the cost estimation (a high key count means a lower cost and a low key count means a high cost when searching for specific keys; has no effect when searching for “is not null”).</li>
+
+<li><tt>reindex</tt> (Boolean): if set to <tt>true</tt>, the full content is re-indexed. This can take a long time, and is run synchronously with storing the index (except with an async index). See “Reindexing” below for details.</li>
+</ul>
+<p>Example:</p>
+
+<div class="source">
+<pre>{
+ NodeBuilder index = root.child("oak:index");
+ index.child("uuid")
+ .setProperty("jcr:primaryType", "oak:QueryIndexDefinition", Type.NAME)
+ .setProperty("type", "property")
+ .setProperty("propertyNames", "jcr:uuid")
+ .setProperty("declaringNodeTypes", "mix:referenceable")
+ .setProperty("unique", true)
+ .setProperty("reindex", true);
+}
+</pre></div>
+<p>or to simplify you can use one of the existing <tt>IndexUtils#createIndexDefinition</tt> helper methods:</p>
+
+<div class="source">
+<pre>{
+ NodeBuilder index = IndexUtils.getOrCreateOakIndex(root);
+ IndexUtils.createIndexDefinition(index, "myProp", true, false, ImmutableList.of("myProp"), null);
+}
+</pre></div>
+<div class="section">
+<div class="section">
+<h4>Reindexing<a name="Reindexing"></a></h4>
+<p>Usually, reindexing is only needed if the configuration of an index is changed, such that the index should contain more or different data. For example, reindexing is needed if the property to be indexed is changed, if a nodetype is added to <b><tt>declaringNodeTypes</tt></b>, or if <b><tt>includedPaths</tt></b> is changed. It is not strictly needed if less data is to be indexed, for example if a nodetype is removed. However, to save space, it might make sense to reindex even in that case. Typically, if a query does not return the expected result, reindexing does not help; more likely, the reason in somewhere else to be found, and disabling the index should be tried first.</p>
+<p>Reindexing a property index happens synchronously by setting the <b><tt>reindex</tt></b> flag to <b><tt>true</tt></b>. This means that the first #save call will generate a full repository traversal with the purpose of building the index content and it might take a long time.</p>
+<p>Asynchronous reindexing of a property index is available as of OAK-1456. The way this works is by pushing the property index updates to a background job and when the indexing process is done, the property definition will be switched back to a synchronous updates mode. To enable this async reindex behaviour you need to first set the <b><tt>reindex-async</tt></b> and <b><tt>reindex</tt></b> flags to <b><tt>true</tt></b> (call #save). You can verify the initial setup worked by refreshing the index definition node and looking for the <b><tt>async</tt></b> = <b><tt>async-reindex</tt></b> property. Next you need to start the dedicated background job via a jmx call to the <b><tt>PropertyIndexAsyncReindex#startPropertyIndexAsyncReindex</tt></b> MBean.</p>
+<p>Example:</p>
+
+<div class="source">
+<pre>{
+ NodeBuilder index = root.child("oak:index");
+ index.child("property")
+ .setProperty("reindex-async", true)
+ .setProperty("reindex", true);
+}
+</pre></div></div>
+<div class="section">
+<h4>Cost Estimation<a name="Cost_Estimation"></a></h4>
+<p>When running a query, the property index reports its estimated cost to the query engine, and then the query engine picks the index with the lowest cost (cost-based query optimization). The algorithm to calculate the estimated cost is roughly as follows (a bit simplified):</p>
+
+<ul>
+
+<li>The cost is infinity (so the index is never used) if the condition contains a fulltext constraint, no applicable restriction, the wrong nodetype, or if the path filtering (<tt>includedPaths</tt> / <tt>excludedPaths</tt>) does not match the query.</li>
+
+<li>For the nodetype index, the cost is the sum of the cost for the <tt>jcr:primaryType</tt> lookup (if the primary type is known), plus the cost for the <tt>jcr:mixinTypes</tt> lookup (if that is known).</li>
+
+<li>Otherwise, the cost is based on the overhead (which is 2), plus the estimated number of entries.</li>
+
+<li>For an “x is not null” condition, the estimated number of entries is either the configured <tt>entryCount</tt> or, if not set, the approximate number of entries in the index. The approximation is an “order of magnitude” estimation (Morris’ algorithm).</li>
+
+<li>For a unique index and “x = 1” condition, the estimated number of entries is either 0 or 1 (depending on whether the key is found).</li>
+
+<li>For a non-unique index and a “x = 1” condition, if the <tt>entryCount</tt> and <tt>keyCount</tt> are set, those setting are used to estimate the number of entries. If not, the approximate number of entries for the key is read (maintained using Morris’ algorithm). In addition to that, the path condition is used to scale down the estimated count depending on the approximate number of nodes in that subtree versus the approximate number of entries in the repository, using approximation available via the <tt>counter</tt> index.</li>
+</ul>
+<p>For example, for a query with path restriction “/content/products/t-shirts” and property restriction “color = ‘red’”, if there is an index for the property “color”, then the entry count approximation is read from the index. Let’s say it is 10’000 for this value. Then the approximate number of nodes in the subtree “/content/products/t-shirts” is read (let’s say it is 20’000), and the approximate number of nodes in the repository (let’s say it is 1 million). Therefore, the estimated number of entries is scaled down (divided by 50) from 10’000 to 200. The estimated cost is therefore 202, due to the overhead of 2.</p></div></div></div>
+ </div>
+ </div>
+ </div>
+
+ <hr/>
+
+ <footer>
+ <div class="container-fluid">
+ <div class="row span12">Copyright © 2012-2016
+ <a href="http://www.apache.org/">The Apache Software Foundation</a>.
+ All Rights Reserved.
+
+ </div>
+
+
+
+
+
+
+
+ <div id="ohloh" class="pull-right">
+ <script type="text/javascript" src="http://www.ohloh.net/p/jackrabbit-oak/widgets/project_thin_badge.js"></script>
+ </div>
+ </div>
+ </footer>
+ </body>
</html>
\ No newline at end of file