Github user joeymcallister commented on a diff in the pull request:
https://github.com/apache/geode/pull/518#discussion_r117122942
--- Diff: geode-docs/tools_modules/lucene_integration.html.md.erb ---
@@ -135,4 +117,164 @@ gfsh> lucene search --regionName=/orders
-queryStrings="John*" --defaultField=fi
</region>
</cache>
```
+## <a id="lucene-index-query" class="no-quick-link"></a>Queries
+### <a id="gfsh-query-example" class="no-quick-link"></a>Gfsh Example to
Query using a Lucene Index
+
+For details, see the [gfsh search
lucene](gfsh/command-pages/search.html#search_lucene") command reference page.
+
+``` pre
+gfsh> lucene search --regionName=/orders -queryStrings="John*"
--defaultField=field1 --limit=100
+```
+
+### <a id="api-query-example" class="no-quick-link"></a>Java API Example
to Query using a Lucene Index
+
+``` pre
+LuceneQuery<String, Person> query =
luceneService.createLuceneQueryFactory()
+ .setResultLimit(10)
+ .create(indexName, regionName, "name:John AND zipcode:97006",
defaultField);
+
+Collection<Person> results = query.findValues();
+```
+
+## <a id="lucene-index-destroy" class="no-quick-link"></a>Destroying an
Index
+
+Since a region destroy operation does not cause the destruction
+of any Lucene indexes,
+destroy any Lucene indexes prior to destroying the associated region.
+
+### <a id="API-destroy-example" class="no-quick-link"></a>Java API Example
to Destroy a Lucene Index
+
+``` pre
+luceneService.destroyIndex(indexName, regionName);
+```
+An attempt to destroy a region with a Lucene index will result in
+an `IllegalStateException`,
+issuing an error message similar to:
+
+``` pre
+java.lang.IllegalStateException: The parent region [/orders] in colocation
chain cannot be destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+at
org.apache.geode.internal.cache.PartitionedRegion.checkForColocatedChildren(PartitionedRegion.java:7231)
+at
org.apache.geode.internal.cache.PartitionedRegion.destroyRegion(PartitionedRegion.java:7243)
+at
org.apache.geode.internal.cache.AbstractRegion.destroyRegion(AbstractRegion.java:308)
+at
DestroyLuceneIndexesAndRegionFunction.destroyRegion(DestroyLuceneIndexesAndRegionFunction.java:46)
+```
+### <a id="gfsh-destroy-example" class="no-quick-link"></a>Gfsh Example to
Destroy a Lucene Index
+
+For details, see the [gfsh destroy lucene
index](gfsh/command-pages/destroy.html#destroy_lucene_index") command reference
page.
+
+The error message that results from an attempt to destroy a region
+prior to destroying its associated Lucene index
+issues an error message similar to:
+
+``` pre
+Error occurred while destroying region "orders".
+ Reason: The parent region [/orders] in colocation chain cannot be
destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+```
+
+## <a id="lucene-index-change" class="no-quick-link"></a>Changing an Index
+
+Changing an index requires rebuilding it.
+Implement these steps in `gfsh` to change an index.
+
+1. Export all region data
+2. Destroy the Lucene index
+3. Destroy the region
+4. Create a new index
+5. Create a new region without the user-defined business logic callbacks
+6. Import the region data with the option to turn on callbacks.
+The callbacks will be to invoke a Lucene async event listener to index
+the data.
+7. Alter the region to add the user-defined business logic callbacks
+
+## <a id="addl-gfsh-api" class="no-quick-link"></a>Additional Gfsh Commands
+
+See the [gfsh describe lucene
index](gfsh/command-pages/describe.html#describe_lucene_index") command
reference page for the command that prints details about
+a specific index.
+
+See the [gfsh list lucene
index](gfsh/command-pages/list.html#list_lucene_index") command reference page
+for the command that prints details about the
+Lucene indexes created for all members.
+
+# <a id="LuceneRandC" class="no-quick-link"></a>Requirements and Caveats
+
+- Join queries between regions are not supported.
+- Nested objects are not supported.
+- Lucene indexes will not be stored within off-heap memory.
+- Lucene queries from within transactions are not supported.
+On an attempt to query from within a transaction,
+a `LuceneQueryException` is thrown, issuing an error message
+on the client (accessor) similar to:
+
+``` pre
+Exception in thread "main"
org.apache.geode.cache.lucene.LuceneQueryException:
+ Lucene Query cannot be executed within a transaction
+at
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findTopEntries(LuceneQueryImpl.java:124)
+at
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findPages(LuceneQueryImpl.java:98)
+at
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findPages(LuceneQueryImpl.java:94)
+at TestClient.executeQuerySingleMethod(TestClient.java:196)
+at TestClient.main(TestClient.java:59)
+```
+- If the Lucene index is not created prior to creating the region,
+an exception will be thrown while attempting to create the region,
+issuing an error message simlar to:
--- End diff --
"similar"
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
