Package org.apache.geode.cache.lucene

Interface LuceneService

public interface LuceneService
The LuceneService provides the capability to create Lucene indexes and execute lucene queries on data stored in Geode regions. The Lucene indexes are automatically maintained by Geode whenever entries are updated in the associated regions.

To obtain an instance of LuceneService, use LuceneServiceProvider.get(GemFireCache cache).

Lucene indexes can be created using gfsh, xml, or the java API. Below is an example of creating a Lucene index with the java API. The Lucene index should be created on each member that has the region that is being indexed. 

 {
   @code
       luceneService.createIndexFactory()
        .addField("name")
        .addField("zipcode")
        .addField("email", new KeywordAnalyzer())
        .create(indexName, regionName);
 }

You can also specify what Analyzer to use for each field. In the example above, email is being tokenized with the KeywordAnalyzer so it is treated as a single word. The default analyzer if none is specified is the StandardAnalyzer.

Indexes should be created on all peers that host the region being indexed. Clients do not need to define the index, they can directly execute queries using this service.

Queries on this service can return either the region keys, values, or both that match a Lucene query expression. To execute a query, start with the createLuceneQueryFactory() method. 

 {
   @code
   LuceneQuery query = luceneService.createLuceneQueryFactory().setLimit(200).create(indexName,
       regionName, "name:John AND zipcode:97006", defaultField);
   Collection results = query.findValues();
 }

The Lucene index data is colocated with the region that is indexed. This means that the index data will be partitioned, copied, or persisted using the same configuration options you provide for the region that is indexed. Queries will automatically be distributed in parallel to cover all partitions of a partitioned region.

Indexes are maintained asynchronously, so changes to regions may not be immediately reflected in the index. This means that queries executed using this service may return stale results. Use the waitUntilFlushed(String, String, long, TimeUnit) method if you need to wait for your changes to be indexed before executing a query, however this method should be used sparingly because it is an expensive operation.

Currently, only partitioned regions are supported. Creating an index on a region with DataPolicy.REPLICATE will fail.

  • Field Details

    • REGION_VALUE_FIELD

      static final String REGION_VALUE_FIELD
      A special field name that indicates that the entire region value should be indexed. This will only work if the region value is a String or Number, in which case a Lucene document will be created with a single field with this name.
      See Also:

  • Method Details

    • createIndexFactory

      LuceneIndexFactory createIndexFactory()
      Get a factory for creating a Lucene index on this member.
      Returns:
      a factory for creating a Lucene index on this member

    • destroyIndex

      void destroyIndex(String indexName, String regionPath)
      Destroy the Lucene index
      Parameters:
      indexName - the name of the index to destroy
      regionPath - the path of the region whose index to destroy

    • destroyIndexes

      void destroyIndexes(String regionPath)
      Destroy all the Lucene indexes for the region
      Parameters:
      regionPath - The path of the region on which to destroy the indexes

    • getIndex

      LuceneIndex getIndex(String indexName, String regionPath)
      Get the Lucene index object specified by region name and index name
      Parameters:
      indexName - index name
      regionPath - region name
      Returns:
      LuceneIndex object

    • getAllIndexes

      Collection<LuceneIndex> getAllIndexes()
      get all the Lucene indexes.
      Returns:
      all index objects in a Collection

    • createLuceneQueryFactory

      LuceneQueryFactory createLuceneQueryFactory()
      Create a factory for building a Lucene query.
      Returns:
      a factory for building a Lucene query

    • getCache

      Cache getCache()
      returns the cache to which the LuceneService belongs
      Returns:
      the cache to which the LuceneService belongs

    • waitUntilFlushed

      boolean waitUntilFlushed(String indexName, String regionPath, long timeout, TimeUnit unit) throws InterruptedException
      Wait until the current entries in cache are indexed. Lucene indexes are maintained asynchronously. This means that updates to the region will not be immediately reflected in the Lucene index. This method will either timeout or wait until any data put into the region before this method call is flushed to the lucene index. This method is an expensive operation, so using it before every query is highly discouraged.
      Parameters:
      indexName - index name
      regionPath - region name
      timeout - max wait time
      unit - Time unit associated with the max wait time
      Returns:
      true if entries are flushed within timeout, false if the timeout has elapsed
      Throws:
      InterruptedException - if the thread is interrupted

    • isIndexingInProgress

      boolean isIndexingInProgress(String indexName, String regionPath)
      Returns if the indexing process is in progress Before executing a lucene query, it can be checked if the indexing operation is in progress. Queries executed during the indexing process will get a LuceneIndexCreationInProgressException
      Parameters:
      indexName - index name
      regionPath - region name
      Returns:
      true if the indexing operation is in progress otherwise false.