geode-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject incubator-geode git commit: GEODE-2023: Add Lucene documentation
Date Tue, 25 Oct 2016 16:57:06 GMT
Repository: incubator-geode
Updated Branches:
  refs/heads/develop 15a54656f -> b0d12050c

GEODE-2023: Add Lucene documentation


Branch: refs/heads/develop
Commit: b0d12050cf7f88f4e2bfc4d7187a8a10a12a27f7
Parents: 15a5465
Author: Dave Barnes <>
Authored: Fri Oct 21 14:44:37 2016 -0700
Committer: Dave Barnes <>
Committed: Tue Oct 25 09:56:31 2016 -0700

 .../source/subnavs/geode-subnav.erb             |  14 ++
 geode-docs/tools_modules/ |  13 +-
 .../              | 136 +++++++++++++++++++
 3 files changed, 158 insertions(+), 5 deletions(-)
diff --git a/geode-book/master_middleman/source/subnavs/geode-subnav.erb b/geode-book/master_middleman/source/subnavs/geode-subnav.erb
index 30ff2f9..d0eb74e 100644
--- a/geode-book/master_middleman/source/subnavs/geode-subnav.erb
+++ b/geode-book/master_middleman/source/subnavs/geode-subnav.erb
@@ -2343,6 +2343,20 @@ limitations under the License.
+                    <li class="has_submenu">
+                        <a href="/docs/tools_modules/lucene_integration.html">Apache
Lucene Integration</a>
+                        <ul>
+                            <li>
+                                <a href="/docs/tools_modules/lucene_integration.html#using-the-apache-lucene-integration">Using
the Apache Lucene Integration</a>
+                            </li>
+                            <li>
+                                <a href="/docs/tools_modules/lucene_integration.html#java-api-example">Java
API Example</a>
+                            </li>
+                            <li>
+                                <a href="/docs/tools_modules/lucene_integration.html#gfsh-api">Gfsh
+                            </li>
+                        </ul>
+                    </li>
             <li class="has_submenu">
diff --git a/geode-docs/tools_modules/ b/geode-docs/tools_modules/
index 852e3c9..a6db1d2 100644
--- a/geode-docs/tools_modules/
+++ b/geode-docs/tools_modules/
@@ -23,25 +23,28 @@ limitations under the License.
 <a id="deploy_run__section_tool_intro"></a>
--   **[gfsh (Geode SHell)](../tools_modules/gfsh/chapter_overview.html)**
+-   **[gfsh (Geode SHell)](gfsh/chapter_overview.html)**
     Geode gfsh (pronounced "jee-fish") provides a single, powerful command-line interface
from which you can launch, manage, and monitor Geode processes, data, and applications.
--   **[Gemcached](../tools_modules/gemcached/chapter_overview.html)**
+-   **[Gemcached](gemcached/chapter_overview.html)**
     Gemcached is a Geode adapter that allows Memcached clients to communicate with a Geode
server cluster, as if the servers were memcached servers. Memcached is an open-source caching
solution that uses a distributed, in-memory hash map to store key-value pairs of string or
object data.
--   **[HTTP Session Management Modules](../tools_modules/http_session_mgmt/chapter_overview.html)**
+-   **[HTTP Session Management Modules](http_session_mgmt/chapter_overview.html)**
     The Apache Geode HTTP Session Management modules provide fast, scalable, and reliable
session replication for HTTP servers without requiring application changes.
--   **[Geode Pulse](../tools_modules/pulse/chapter_overview.html)**
+-   **[Geode Pulse](pulse/chapter_overview.html)**
     Geode Pulse is a Web Application that provides a graphical dashboard for monitoring vital,
real-time health and performance of Geode clusters, members, and regions.
--   **[Geode Redis Adapter](../tools_modules/redis_adapter.html)**
+-   **[Geode Redis Adapter](redis_adapter.html)**
     The Geode Redis adapter allows Geode to function as a drop-in replacement for a Redis
data store, letting Redis applications take advantage of Geode’s scaling capabilities without
changing their client code. Redis clients connect to a Geode server in the same way they connect
to a Redis server, using an IP address and a port number.
+-   **[Apache Lucene&reg; Integration](lucene_integration.html)**
+    The Apache Lucene&reg; integration enables users to create Lucene indexes and execute
Lucene searches on data stored in Geode.
diff --git a/geode-docs/tools_modules/ b/geode-docs/tools_modules/
new file mode 100644
index 0000000..6361650
--- /dev/null
+++ b/geode-docs/tools_modules/
@@ -0,0 +1,136 @@
+title: Apache Lucene&reg; Integration
+<a id="topic_523F6DE33FE54307BBE8F83BB7D9355D"></a>
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+See the License for the specific language governing permissions and
+limitations under the License.
+Apache Lucene&reg; is a widely-used Java full-text search engine. This section describes
how the system integrates with Apache Lucene.
+We assume that the reader is familiar with Apache Lucene's indexing and search functionalities.
+The Apache Lucene integration:
+- enables users to create Lucene indexes on data stored in Geode
+- provides high availability of indexes using Geode's HA capabilities to store the indexes
in memory
+- optionally stores indexes on disk
+- updates the indexes asynchronously to minimize impacting write latency
+- provides scalability by partitioning index data
+- colocates indexes with data
+For more details, see Javadocs for the classes and interfaces that implement Apache Lucene
indexes and searches, including
+`LuceneService`, `LuceneQueryFactory`, `LuceneQuery`, and `LuceneResultStruct`.
+## <a id="using-the-apache-lucene-integration" class="no-quick-link"></a>Using
the Apache Lucene Integration
+You can create Apache Lucene indexes through a Java API, through the `gfsh` command-line
utility, or by means of
+the `cache.xml` configuration file.
+To use Apache Lucene Integration, you will need two pieces of information:
+1.  The name of the region to be indexed or searched
+2.  The names of the fields you wish to index
+### Key Points ###
+- Only top level fields of objects stored in the region can be indexed.
+- Apache Lucene indexes are supported only on Partitioned regions.
+- A single index supports a single region. Indexes do not support multiple regions.
+- Heterogeneous objects in single region are supported.
+- Join queries between regions are not supported.
+- Nested objects are not supported.
+- The index needs to be created before the region is created.
+## <a id="java-api-example" class="no-quick-link"></a>Java API Example
+``` pre
+// Get LuceneService
+LuceneService luceneService = LuceneServiceProvider.get(cache);
+// Create Index on fields with default analyzer:
+luceneService.createIndex(indexName, regionName, "field1", "field2", "field3");
+Region region = cache.createRegionFactory(RegionShutcut.PARTITION).create(regionName);
+## Search Example
+``` pre
+LuceneQuery<String, Person> query = luceneService.createLuceneQueryFactory()
+  .setResultLimit(10)
+  .create(indexName, regionName, "Main Street", "address");
+Collection<Person> results = query.findValues();
+## <a id="gfsh-api" class="no-quick-link"></a>Gfsh API
+The gfsh command-line utility supports four Apache Lucene actions:
+<dt><b>create lucene index</b></dt>
+    <dd>Create a lucene index that can be used to execute queries.</dd>
+<dt><b>describe lucene index</b></dt>
+    <dd>Display the describe of lucene indexes created for all members.</dd>
+<dt><b>list lucene indexes [with-stats]</b></dt>
+    <dd>Display the list of lucene indexes created for all members. The optional `with-stats`
qualifier shows activity on the indexes.</dd>
+<dt><b>search lucene</b></dt>
+    <dd>Search lucene index</dd>
+**Gfsh command-line examples:**
+``` pre
+// List Index
+gfsh> list lucene indexes [with-stats]
+// Create Index
+gfsh>create lucene index --name=indexName --region=/orders --field=customer,tags
+// Create Index, specifying a custom analyzer for the second field
+// Note: "null" in the first analyzer position means "use the default analyzer for the first
+gfsh>create lucene index --name=indexName --region=/orders --field=customer,tags --analyzer=null,
+// Execute Lucene query
+gfsh> lucene search --regionName=/orders -queryStrings="John*" --defaultField=field1 --limit=100
+## XML Configuration
+``` pre
+    xmlns=""
+    xmlns:lucene=""
+    xmlns:xsi=""
+    xsi:schemaLocation="
+    version="1.0">
+    <region name="region" refid="PARTITION">
+        <lucene:index name="index">
+          <lucene:field name="a" analyzer="org.apache.lucene.analysis.core.KeywordAnalyzer"/>
+          <lucene:field name="b" analyzer="org.apache.lucene.analysis.core.SimpleAnalyzer"/>
+          <lucene:field name="c" analyzer="org.apache.lucene.analysis.standard.ClassicAnalyzer"/>
+        </lucene:index>
+    </region>

View raw message