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/feature/GEM-983 Commit: b0d12050cf7f88f4e2bfc4d7187a8a10a12a27f7 Parents: 15a5465 Author: Dave Barnes <[email protected]> Authored: Fri Oct 21 14:44:37 2016 -0700 Committer: Dave Barnes <[email protected]> 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â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® 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> +``` +
