geode-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From joeymcallister <...@git.apache.org>
Subject [GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation
Date Wed, 17 May 2017 22:12:03 GMT
Github user joeymcallister commented on a diff in the pull request:

    https://github.com/apache/geode/pull/518#discussion_r117122461
  
    --- 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
    --- End diff --
    
    "An invalidate operation of"


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message