You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@geode.apache.org by db...@apache.org on 2016/10/25 16:57:06 UTC
incubator-geode git commit: GEODE-2023: Add Lucene documentation
Repository: incubator-geode
Updated Branches:
refs/heads/develop 15a54656f -> b0d12050c
GEODE-2023: Add Lucene documentation
Project: http://git-wip-us.apache.org/repos/asf/incubator-geode/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-geode/commit/b0d12050
Tree: http://git-wip-us.apache.org/repos/asf/incubator-geode/tree/b0d12050
Diff: http://git-wip-us.apache.org/repos/asf/incubator-geode/diff/b0d12050
Branch: refs/heads/develop
Commit: b0d12050cf7f88f4e2bfc4d7187a8a10a12a27f7
Parents: 15a5465
Author: Dave Barnes <db...@pivotal.io>
Authored: Fri Oct 21 14:44:37 2016 -0700
Committer: Dave Barnes <db...@pivotal.io>
Committed: Tue Oct 25 09:56:31 2016 -0700
----------------------------------------------------------------------
.../source/subnavs/geode-subnav.erb | 14 ++
geode-docs/tools_modules/book_intro.html.md.erb | 13 +-
.../lucene_integration.html.md.erb | 136 +++++++++++++++++++
3 files changed, 158 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/b0d12050/geode-book/master_middleman/source/subnavs/geode-subnav.erb
----------------------------------------------------------------------
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>
</ul>
</li>
+ <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 API</a>
+ </li>
+ </ul>
+ </li>
</ul>
</li>
<li class="has_submenu">
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/b0d12050/geode-docs/tools_modules/book_intro.html.md.erb
----------------------------------------------------------------------
diff --git a/geode-docs/tools_modules/book_intro.html.md.erb b/geode-docs/tools_modules/book_intro.html.md.erb
index 852e3c9..a6db1d2 100644
--- a/geode-docs/tools_modules/book_intro.html.md.erb
+++ b/geode-docs/tools_modules/book_intro.html.md.erb
@@ -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\u2019s 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® Integration](lucene_integration.html)**
+
+ The Apache Lucene® integration enables users to create Lucene indexes and execute Lucene searches on data stored in Geode.
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/b0d12050/geode-docs/tools_modules/lucene_integration.html.md.erb
----------------------------------------------------------------------
diff --git a/geode-docs/tools_modules/lucene_integration.html.md.erb b/geode-docs/tools_modules/lucene_integration.html.md.erb
new file mode 100644
index 0000000..6361650
--- /dev/null
+++ b/geode-docs/tools_modules/lucene_integration.html.md.erb
@@ -0,0 +1,136 @@
+---
+title: Apache Lucene® 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
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+Apache Lucene® 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 field"
+gfsh>create lucene index --name=indexName --region=/orders --field=customer,tags --analyzer=null,org.apache.lucene.analysis.bg.BulgarianAnalyzer
+
+// Execute Lucene query
+gfsh> lucene search --regionName=/orders -queryStrings="John*" --defaultField=field1 --limit=100
+```
+
+
+## XML Configuration
+
+``` pre
+<cache
+ xmlns="http://geode.apache.org/schema/cache"
+ xmlns:lucene="http://geode.apache.org/schema/lucene"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://geode.apache.org/schema/cache
+ http://geode.apache.org/schema/cache/cache-1.0.xsd
+ http://geode.apache.org/schema/lucene
+ http://geode.apache.org/schema/lucene/lucene-1.0.xsd"
+ 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>
+</cache>
+```
+