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

[th...@apache.org]

Author: thomasm
Date: Thu Feb 23 10:15:16 2017
New Revision: 1784104

URL: http://svn.apache.org/viewvc?rev=1784104&view=rev
Log:
OAK-5520 Improve index and query 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=1784104&r1=1784103&r2=1784104&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 23 10:15:16 2017
@@ -36,10 +36,27 @@ documentation page.
 * [Solr](./solr.html)
 * [Property](./property-index.html)
 
-### Customisations
+#### Reindexing
 
-* [Change Out-Of-The-Box Index Definitions](./ootb-index-change.html)
+Existing indexes need to be re-indexed if the definition is changed
+in such a way that the index is incorrect (for example adding properties to the index).
+Reindexing does not resolve other problems, such that queries not returning data.
+For such cases, it is _not_ recommended to reindex 
+(also because this can be very slow and use a lot of temporary disk space).
+If queries don't return the right data, then possibly the index is [not yet up-to-date][OAK-5159],
+or the query is incorrect, or included/excluded path settings are wrong (for Lucene indexes).
+Instead of reindexing, it is suggested to first check the log file, modify the query
+so it uses a different index or traversal and run the query again.
+One case were reindexing can help is if the query engine picks a very slow index
+for some queries because the counter index 
+[got out of sync after adding and removing lots of nodes many times (fixed in recent version)][OAK-4065].
+For this case, it is recommended to verify the contents of the counter index first,
+and upgrade Oak before reindexing.
 
+### Customisations
 
+* [Change Out-Of-The-Box Index Definitions](./ootb-index-change.html)
 
 
+[OAK-4065]: https://issues.apache.org/jira/browse/OAK-4065
+[OAK-5159]: https://issues.apache.org/jira/browse/OAK-5159