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 Summary

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

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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​(java.lang.String indexName, java.lang.String regionPath)
      Destroy the Lucene index
      void destroyIndexes​(java.lang.String regionPath)
      Destroy all the Lucene indexes for the region
      java.util.Collection<LuceneIndex> getAllIndexes()
      get all the Lucene indexes.
      org.apache.geode.cache.Cache getCache()
      returns the cache to which the LuceneService belongs
      LuceneIndex getIndex​(java.lang.String indexName, java.lang.String regionPath)
      Get the Lucene index object specified by region name and index name
      boolean isIndexingInProgress​(java.lang.String indexName, java.lang.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​(java.lang.String indexName, java.lang.String regionPath, long timeout, java.util.concurrent.TimeUnit unit)
      Wait until the current entries in cache are indexed.

    • Field Detail

      • REGION_VALUE_FIELD

        static final java.lang.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​(java.lang.String indexName,
                  java.lang.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​(java.lang.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​(java.lang.String indexName,
                     java.lang.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

        java.util.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

        org.apache.geode.cache.Cache getCache()
        returns the cache to which the LuceneService belongs
        Returns:
        the cache to which the LuceneService belongs

      • waitUntilFlushed

        boolean waitUntilFlushed​(java.lang.String indexName,
                         java.lang.String regionPath,
                         long timeout,
                         java.util.concurrent.TimeUnit unit)
                  throws java.lang.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:
        java.lang.InterruptedException - if the thread is interrupted

      • isIndexingInProgress

        boolean isIndexingInProgress​(java.lang.String indexName,
                             java.lang.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.