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 Summary

Fields

Modifier and Type	Field and Description
static String	REGION_VALUE_FIELD A special field name that indicates that the entire region value should be indexed.

Method Summary

Modifier and Type	Method and Description
LuceneIndexFactory	createIndexFactory() Get a factory for creating a Lucene index on this member.
LuceneQueryFactory	createLuceneQueryFactory() Create a factory for building a Lucene query.
void	destroyIndex(String indexName, String regionPath) Destroy the Lucene index
void	destroyIndexes(String regionPath) Destroy all the Lucene indexes for the region
Collection<LuceneIndex>	getAllIndexes() get all the Lucene indexes.
Cache	getCache() returns the cache to which the LuceneService belongs
LuceneIndex	getIndex(String indexName, String regionPath) Get the Lucene index object specified by region name and index name
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.
boolean	waitUntilFlushed(String indexName, String regionPath, long timeout, TimeUnit unit) Wait until the current entries in cache are indexed.

Field Detail

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:

Constant Field Values

Method Detail

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.