[jira] [Updated] (GEODE-2913) Update Lucene documentation
[
https://issues.apache.org/jira/browse/GEODE-2913?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Anthony Baker updated GEODE-2913:
-
Fix Version/s: 1.2.0
> Update Lucene documentation
> ---
>
> Key: GEODE-2913
> URL: https://issues.apache.org/jira/browse/GEODE-2913
> Project: Geode
> Issue Type: Bug
> Components: docs
>Reporter: Karen Smoler Miller
>Assignee: Karen Smoler Miller
> Fix For: 1.2.0
>
>
> Improvements to the code base that need to be reflected in the docs:
> * Change LuceneService.createIndex to use a factory pattern
> {code:java}
> luceneService.createIndex(region, index, ...)
> {code}
> changes to
> {code:java}
> luceneService.createIndexFactory()
> .addField("field1name")
> .addField("field2name")
> .create()
> {code}
> * Lucene indexes will *NOT* be stored in off-heap memory.
> * Document how to configure an index on accessors - you still need to create
> the Lucene index before creating the region, even though this member does not
> hold any region data.
> If the index is not defined on the accessor, an exception like this will be
> thrown while attempting to create the region:
> {quote}
> [error 2017/05/02 15:19:26.018 PDT 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)
> {quote}
> * Do not need to create a Lucene index on a client with a Proxy cache. The
> Lucene search will always be done on the server. Besides, _you can't create
> an index on a client._
> * If you configure Invalidates for region entries (alone or as part of
> expiration), these will *NOT* invalidate the Lucene indexes.
> The problem with this is the index contains the keys, but the region doesn't,
> so the query produces results that don't exist.
> In this test, the first time the query is run, it produces N valid results.
> The second time it is run it produces N empty results:
> ** load entries
> ** run query
> ** invalidate entries
> ** run query again
> * Destroying a region will *NOT* automatically destroy any Lucene index
> associated with that region. Instead, attempting to destroy a region with a
> Lucene index will throw a colocated region exception.
> An IllegalStateException is thrown:
> {quote}
> java.lang.IllegalStateException: The parent region [/data] in colocation
> chain cannot be destroyed, unless all its children
> [[/cusip_index#_data.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)
> {quote}
> * The process to change a Lucene index using gfsh:
> 1. export region data
> 2. destroy Lucene index, destroy region
> 3. create new index, create new region without user-defined business
> logic callbacks
> 4. import data with option to turn on callbacks (to invoke Lucene Async
> Event Listener to index the data)
> 5. alter region to add user-defined business logic callbacks
> * Make sure there are no references to replicated regions as they are not
> supported.
> * Document security implementation and defaults. If a user has security
> configured for their cluster, creating a Lucene index requires DATA:MANAGE
> privilege (similar to OQL), but doing Lucene queries requires DATA:WRITE
> privilege because a function is called (different from OQL which requires
> only DATA:READ privilege). Here are all the required privileges for the gfsh
> commands:
> ** create index requires DATA:MANAGE:region
> ** describe index requires CLUSTER:READ
> ** list indexes requires CLUSTER:READ
> ** search index requires DATA:WRITE
> ** destroy index requires DATA:MANAGE:region
> * A user cannot create a Lucene index on a region that has eviction
> configured with local destroy. If using Lucene indexing, eviction can only be
> configured with overflow to disk. In this case, only the region data is
> overflowed to disk, *NOT* the Lucene index. An UnsupportedOperationException
> is thrown:
> {quote}
> [error 2017/05/02 16:12:32.461 PDT tid=0x1]
> java.lang.UnsupportedOperationException:
[jira] [Updated] (GEODE-2913) Update Lucene documentation
[
https://issues.apache.org/jira/browse/GEODE-2913?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Diane Hardman updated GEODE-2913:
-
Description:
Improvements to the code base that need to be reflected in the docs:
* Change LuceneService.createIndex to use a factory pattern
{code:java}
luceneService.createIndex(region, index, ...)
{code}
changes to
{code:java}
luceneService.createIndexFactory()
.setXXX()
.setYYY()
.create()
{code}
* Lucene indexes will *NOT* be stored in off-heap memory.
* Document how to configure an index on accessors - you still need to create
the Lucene index before creating the region, even though this member does not
hold any region data.
If the index is not defined on the accessor, an exception like this will be
thrown while attempting to create the region:
{quote}
[error 2017/05/02 15:19:26.018 PDT 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)
{quote}
* Do not need to create a Lucene index on a client with a Proxy cache. The
Lucene search will always be done on the server. Besides, _you can't create an
index on a client._
* If you configure Invalidates for region entries (alone or as part of
expiration), these will *NOT* invalidate the Lucene indexes.
The problem with this is the index contains the keys, but the region doesn't,
so the query produces results that don't exist.
In this test, the first time the query is run, it produces N valid results. The
second time it is run it produces N empty results:
** load entries
** run query
** invalidate entries
** run query again
* Destroying a region will *NOT* automatically destroy any Lucene index
associated with that region. Instead, attempting to destroy a region with a
Lucene index will throw a colocated region exception.
An IllegalStateException is thrown:
{quote}
java.lang.IllegalStateException: The parent region [/data] in colocation chain
cannot be destroyed, unless all its children [[/cusip_index#_data.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)
{quote}
* The process to change a Lucene index using gfsh:
1. export region data
2. destroy Lucene index, destroy region
3. create new index, create new region without user-defined business
logic callbacks
4. import data with option to turn on callbacks (to invoke Lucene Async
Event Listener to index the data)
5. alter region to add user-defined business logic callbacks
* Make sure there are no references to replicated regions as they are not
supported.
* Document security implementation and defaults. If a user has security
configured for their cluster, creating a Lucene index requires DATA:MANAGE
privilege (similar to OQL), but doing Lucene queries requires DATA:WRITE
privilege because a function is called (different from OQL which requires only
DATA:READ privilege). Here are all the required privileges for the gfsh
commands:
** create index requires DATA:MANAGE:region
** describe index requires CLUSTER:READ
** list indexes requires CLUSTER:READ
** search index requires DATA:WRITE
** destroy index requires DATA:MANAGE:region
* A user cannot create a Lucene index on a region that has eviction configured
with local destroy. If using Lucene indexing, eviction can only be configured
with overflow to disk. In this case, only the region data is overflowed to
disk, *NOT* the Lucene index. An UnsupportedOperationException is thrown:
{quote}
[error 2017/05/02 16:12:32.461 PDT 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
