svn commit: r1662453 - /jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query.md

[th...@apache.org]

Author: thomasm
Date: Thu Feb 26 14:21:41 2015
New Revision: 1662453

URL: http://svn.apache.org/r1662453
Log:
OAK-301 : oak documentation

Modified:
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query.md

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query.md?rev=1662453&r1=1662452&r2=1662453&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query.md Thu Feb 26 14:21:41 2015
@@ -190,8 +190,15 @@ To define a property index on a subtree
 
 * must be of type `oak:QueryIndexDefinition`
 * must have the `type` property set to __`property`__
-* contains the `propertyNames` property that indicates what properties will be stored in the index.
-  `propertyNames` can be a list of properties, and it is optional.in case it is missing, the node name will be used as a property name reference value
+* contains the `propertyNames` property.
+    This is a multi-valued property, and must not be empty.
+    It usually contains only one property name.
+    All nodes that have any of those properties are stored in this index.
+    
+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.)
 
 _Optionally_ you can specify
 
@@ -225,17 +232,6 @@ or to simplify you can use one of the ex
       IndexUtils.createIndexDefinition(index, "myProp", true, false, ImmutableList.of("myProp"), null);
     }
 
-(Not sure if this is correct) 
-__Note on `propertyNames`__ Adding a property index definition that contains two or more properties will only
-include nodes that have _all_ specified properties present. This is different than adding a dedicated property
-index for each and letting the query engine make use of them.
-
-(Not sure if this is correct) 
-__Note__ Is is currently not possible to add more than one property index on the same property name, even if it
-might be used in various combinations with other property names. This rule is not enforced in any way, but the
-behavior is undefined, one of the defined indexes will be updated while the others will simply be ignored by the
-indexer which can result in empty result sets at query time.
-
 #### Reindexing
 
 Reindexing a property index happens synchronously by setting the __`reindex`__ flag to __`true`__. This means that the