Tuesday, March 22, 2016

Starting Search with Apache Lucene 5.3.x/5.4.x

Before we delve into Apache Lucene, the following are the most important terms that you need to be familiar with. This will also help you clarify a few terms before getting into 'search' or 'information retrieval':

Let us get ahead with Apache Lucene 5.3.x/5.4.y; The most important aspects of Lucene is mentioned under each of the headings.

1. Lucene Introduction (Usage)
  • Apache Lucene is a high-performance, full-featured text search engine library written entirely in Java. It is a technology suitable for nearly any application that requires full-text search, especially cross-platform.
  • Apache Lucene is an open source project available for free download
  • Scalable, High-Performance Indexing
  • Powerful, Accurate and Efficient Search Algorithms
  • Cross-Platform Solution
2. LuceneTerms (Concepts)
  • Inverted Index
    Inverted Index is used to get traverse from the string or search term to the document id's or locations of these terms. If we were to visualize this in terms of an 'index' - it would be 'inverted', as we would be using the term as a handle to retrieve 'id' or 'locations' - reverse of the popular usage of an index.

  • Index
    Index is an handle (information) that can be used to get further related information from a file, database or any other source of data. Usually, Index is also accompanied by compression, check-sum, hash or location of the remaining data. Index contains multiple Documents.

  • Document
    Document is a collection of Fields and the Values against each of the Fields. It is more like saying "Employee Name" - "Sumith Puri" | "Employee Desingation" - "Software Architect" | "Employee Age" - "33" | "Employee ID" - "067X" forms a document. The Lucene Indexing Process adds multiple documents to an Index. The entire set of Documents is called the Corpus.
  • Field
    contains Terms and are simply 'Sets of Tokens' of information. The Lucene Indexing process take care to Identify (or Process) Fields and Index them. Fields belong to a Document always.

  • Terms
    Terms are nothing but a 'Token' or 'String' of Information. This 'Term' is the smallest piece of Information that will be Indexed to form the Inverted Index. Set of Distince Terms is called the Vocabulary.

  • String
    String is simply a 'Token' or the English Language String.

  • Segment
    Segment is a fragmented or chunked part of the entire Index, for better storage and faster retrieval.

3. Lucene Segment (Indexing)

Each segment index maintains the following:

Field Names: This contains the set of field names used in the index.

Stored Field Values: This contains, for each document, a list of attribute-value pairs, where the attributes are field names. These are used to store auxiliary information about the document, such as its title, url, or an identifier to access a database. The set of stored fields are what is returned for each hit when searching. This is keyed by document number.   

Term Dictionary: A dictionary containing all of the terms used in all of the indexed fields of all of the documents. The dictionary also contains the number of documents which contain the term, and pointers to the term's frequency and proximity data.

Term Frequency Data: For each term in the dictionary, the numbers of all the documents that contain that term, and the frequency of the term in that document, unless frequencies are omitted (IndexOptions.DOCS_ONLY)

Term Proximity Data: For each term in the dictionary, the positions that the term occurs in each document. Note that this will not exist if all fields in all documents omit position data.

Normalization Factors: For each field in each document, a value is stored that is multiplied into the score for hits on that field.

Term Vectors: For each field in each document, the term vector (sometimes called document vector) may be stored. A term vector consists of term text and term frequency. To add Term Vectors to your index see the Field constructors

Deleted Documents: An optional file indicating which documents are deleted. 

4. Lucene Internals (Architecture)

    Fig. 1: Lucene Architectural Layers [Non-Copyrighted Image]

Fig. 2: Lucene Segment Search [Freely Available Image]

     Fig. 3: Lucene Real-World Application Typical Data Flow  [Freely Available Image]

5. Lucene Analysis (Analysis/Process)
Pre-Tokenization: Stripping HTML Markup, Transforming or Removing Text Matching Arbitrary Patterns or Sets of Fixed Strings

Stemming – Replacing words with their stems. For instance with English stemming "bikes" is replaced with "bike"; now query "bike" can find both documents containing "bike" and those containing "bikes".
Stop Words Filtering – Common words like "the", "and" and "a" rarely add any value to a search. Removing them shrinks the index size and increases performance. It may also reduce some "noise" and actually improve search quality.
Text Normalization – Stripping accents and other character markings can make for better searching.
Synonym Expansion – Adding in synonyms at the same token position as the current word can mean better matching when users search with words in the synonym set. 

Fig. 4: Lucene Analysis of a Text/Sentence 

6. Lucene on Maven (Build)

 Fig. 5: Apache Lucene Maven Typical Dependencies (Without Hibernate Search) 

7. Lucene Sample (Indexing)
Some notable points before you start indexing and searching  using Apache Lucene:

- Multiple types of data that can be indexed such as Files or Database 
- Index to multiple storage modes such as directly to Filesystem or to Memory
- Multiple types of Queries suiting every need such as TermQuery and PrefixQuery
- Use it as Standalone or Inside Application or Web Server
- Multiple ways to Analyze Data suiting your Application including default StandardAnalyzer
- Integrated/Merged with many existing frameworks like Hibernate to form Hibernate Search
- Adapted to multiple Programming Languages and Frameworks including Java, JEE and .NET


Fig. 6: Indexing Sample (Without Hibernate Search) 

8. Lucene Sample (Searching)

Fig. 7: Searching Sample (Without Hibernate Search) 

9. Lucene Synchronization (Re-Indexing)

I will shortly be uploading the best way to re-index without causing any downtime to applications. This is for Applications with SLA of 99.99% or Close.

A. Lucene Queries (Important Types - Points to JavaDoc or Definition Directly)
Term Query
Prefix Query
Phrase Query
Wildcard Query
Fuzzy Query
Boolean Query 
The best practices when using Apache Lucene for indexing and searching, also include the following. These are directly from the Apache Lucene Wiki, with some modification/addition.

Best Practices for Indexing using Apache Lucene 5.3.x/5.4.y
Best Practices for Searching using Apache Lucene 5.3.x/5.4.y

You can download the entire sample project (eclipse) with its source code from here This simple-file-search is also called 'brahmashira' [the 4x exponentially stronger weapon than brahmastra from brahma]. Include it directly in your projects and start indexing, searching.

 Fig. A: Sample File Search Engine (Indexing Files in RAM Directory) - Search Page

[You can download  and deploy on Apache Tomcat 8.0.x and run the search engine at http://localhost:8080/simple-file-search and then use search terms from static data on display there. Modify the content file and try re-indexing and searching again.]