Github user joeymcallister commented on a diff in the pull request:
https://github.com/apache/geode/pull/518#discussion_r117123398
--- 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:
+
+``` pre
+[error 2017/05/02 15:19:26.018 PDT <main> tid=0x1]
java.lang.IllegalStateException:
+ Must create Lucene index full_index on region /data because it is defined
in another member.
+Exception in thread "main" java.lang.IllegalStateException:
+ Must create Lucene index full_index on region /data because it is defined
in another member.
+at
org.apache.geode.internal.cache.CreateRegionProcessor$CreateRegionMessage.handleCacheDistributionAdvisee(CreateRegionProcessor.java:478)
+at
org.apache.geode.internal.cache.CreateRegionProcessor$CreateRegionMessage.process(CreateRegionProcessor.java:379)
+```
+- An invalidate of a region entry does not invalidate a corresponding
+Lucene index entry.
+A query on a Lucene index that contains values which
+have been invalidated can return results that no longer exist.
+Therefore, do not combine entry invalidation with queries on Lucene
indexes.
+- Lucene indexes are not supported for regions that have eviction
configured
+with a local destroy.
+Eviction can be configured with overflow to disk,
+but only the region data is overflowed to disk,
+not the Lucene index.
+On an attempt to create a region with eviction configured to do local
destroy
+(with a Lucene index),
+an `UnsupportedOperationException` will be thrown,
+issuing an error message simlar to:
+
+``` pre
+[error 2017/05/02 16:12:32.461 PDT <main> tid=0x1]
java.lang.UnsupportedOperationException:
+ Lucene indexes on regions with eviction and action local destroy are not
supported
+Exception in thread "main" java.lang.UnsupportedOperationException:
+ Lucene indexes on regions with eviction and action local destroy are not
supported
+at
org.apache.geode.cache.lucene.internal.LuceneRegionListener.beforeCreate(LuceneRegionListener.java:85)
+at
org.apache.geode.internal.cache.GemFireCacheImpl.invokeRegionBefore(GemFireCacheImpl.java:3154)
+at
org.apache.geode.internal.cache.GemFireCacheImpl.createVMRegion(GemFireCacheImpl.java:3013)
+at
org.apache.geode.internal.cache.GemFireCacheImpl.basicCreateRegion(GemFireCacheImpl.java:2991)
+```
+- Be aware that the same field name used in different objects
+where the field has a different data type
+may have unexpected consequences.
+For example, if an index on the field SSN has the following entries
+ - `Object_1 object_1` has String SSN = "1111"
+ - `Object_2 object_2` has Integer SSN = 1111
+ - `Object_3 object_3` has Float SSN = 1111.0
+
+ Integers and floats will not be converted into strings.
+ They remain as `IntPoint` and `FloatPoint` within Lucene.
+ The standard analyzer will not try to tokenize these values.
+ The standard analyzer will only try to break up string values.
+ So, a string search for "SSN: 1111" will return `object_1`.
+ An `IntRangeQuery` for `upper limit : 1112` and `lower limit : 1110`
+will return `object_2`.
+ And, a `FloatRangeQuery` with `upper limit : 1111.5` and `lower limit
: 1111.0`
+will return `object_3`.
+- Backups should only be made for regions with Lucene indexes
+when there are no puts, updates, or deletes are in progress.
--- End diff --
"or deletes in progress."
---
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.
---
