About Ilias Tsagklis

Ilias is a senior software engineer working in the telecom domain. He is an applications developer in a wide variety of applications/services, currently the technical lead in a in-house PCRF solution. Particularly interested in multi-tier architecture, middleware services and mobile development (contact). Ilias Tsagklis is co-founder and Executive Editor at Java Code Geeks.

An Introduction to Apache Lucene for Full-Text Search

In this tutorial I would like to talk a bit about Apache Lucene. Lucene is an open-source project that provides Java-based indexing and search technology. Using its API, it is easy to implement full-text search. I will deal with the Lucene Java version, but bear in mind that there is also a .NET port available under the name Lucene.NET, as well as several helpful sub-projects.

I recently read a great tutorial about this project, but there was no actual code presented. Thus, I decided to provide some sample code to help you getting started with Lucene. The application we will build will allow you to index your own source code files and search for specific keywords.

First things first, let’s download the latest stable version from one of the Apache Download Mirrors. The version I will use is 3.0.1 so I downloaded the lucene-3.0.1.tar.gz bundle (note that the .tar.gz versions are significantly smaller than the corresponding .zip ones). Extract the tarball and locate the lucene-core-3.0.1.jar file which will be used later. Also, make sure the Lucene API JavaDoc page is open at your browser (the docs are also included in the tarball for offline usage). Next, setup a new Eclipse project, let’s say under the name “LuceneIntroProject” and make sure the aforementioned JAR is included in the project’s classpath.

Before we begin running search queries, we need to build an index, against which the queries will be executed. This will be done with the help of a class named IndexWriter, which is the class that creates and maintains an index. The IndexWriter receives Documents as input, where documents are the unit of indexing and search. Each Document is actually a set of Fields and each field has a name and a textual value. To create an IndexWriter, an Analyzer is required. This class is abstract and the concrete implementation that we will use is SimpleAnalyzer.

Enough talking already, let’s create a class named “SimpleFileIndexer” and make sure a main method is included. Here is the source code for this class:

Let’s talk a bit about this class. We provide the location of the index, i.e. where the index data will be saved on the disk (“c:/index/”). Then we provide the data directory, i.e. the directory which will be recursively scanned for input files. I have chosen my whole Eclipse workspace for this (“C:/programs/eclipse/workspace/”). Since we wish to index only for Java source code files, I also added a suffix field. You can obviously adjust those values to your search needs. The “index” method takes into account the previous parameters and uses a new instance of IndexWriter to perform the directory indexing. The “indexDirectory” method uses a simple recursion algorithm to scan all the directories for files with .java suffix. For each file that matches the criteria, a new Document is created in the “indexFileWithIndexWriter” and the appropriate fields are populated. If you run the class as a Java application via Eclipse, the input directory will be indexed and the output directory will look like the one in the following image: OK, we are done with the indexing, let’s move on to the searching part of the equation. For this, an IndexSearcher class is needed, which is a class that implements the main search methods. For each search, a new Query object is needed (SQL anyone?) and this can be obtained from a QueryParser instance. Note that the QueryParser has to be created using the same type of Analyzer that the index was created with, in our case using a SimpleAnalyzer. A Version is also used as constructor argument and is a class that is “Used by certain classes to match version compatibility across releases of Lucene”, according to the JavaDocs. The existence of something like that kind of confuses me, but whatever, let’s use the appropriate version for our application (Lucene_30). When the search is performed by the IndexSearcher, a TopDocs object is returned as a result of the execution. This class just represents search hits and allows us to retrieve ScoreDoc objects. Using the ScoreDocs we find the Documents that match our search criteria and from those Documents we retrieve the wanted information. Let’s see all of these in action. Create a class named “SimpleSearcher” and make sure a main method is included. The source code for this class is the following:

We provide the index directory, the search query string and the maximum number of hits and then call the “searchIndex” method. In that method, we create an IndexSearcher, a QueryParser and a Query object. Note that QueryParser uses the name of the field that we used to create the Documents with IndexWriter (“contents”) and again that the same type of Analyzer is used (SimpleAnalyzer). We perform the search and for each Document that a match has been found, we extract the value of the field that holds the name of the file (“filename”) and we print it. That’s it, let’s perform the actual search. Run it as a Java application and you will see the names of the files that contain the query string you provided.

The Eclipse project for this tutorial, including the dependency library, can be downloaded here.

how do i search contents of file irrespective of their extention or suffix? in the above example , you provided siuffux as “java”. How do i search in all files in a directory without specifying the suffix? what modification do I need to make?

If you want all extensions, instead of just “java”, then you can leave out that parameter. This would change the ‘index’, ‘indexDirectory’, and ‘indexFileWithIndexWriter’ constructors to not have the parameter passed in. Finally, you would want to remove:

if (suffix!=null && !f.getName().endsWith(suffix)) { return; }

from the ‘indexFileWithIndexWriter’ constructor so that it does not check for extensions.

Hi, good example, i understood the stuff pretty well, now i am trying to execute the Lucene on my machine, and i am facing problem with creating object ‘indexWriter’ and the SimpleAnalyzer causing me error ‘ The constructor SimpleAnalyzer() is undefined’

Hi, thanks for your tutorial. As the question of Vishruth, in the new versions of Lucene (4.6 for me as example), there are no class SimpleAnalyzer, (or I don’t know how to find it). So please help me to find a way to create an indexWriter. Thank you!

Newsletter

Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

Email address:

Join Us

With 1,043,221 monthly unique visitors and over 500 authors we are placed among the top Java related sites around. Constantly being on the lookout for partners; we encourage you to join us. So If you have a blog with unique and interesting content then you should check out our JCG partners program. You can also be a guest writer for Java Code Geeks and hone your writing skills!

Disclaimer

All trademarks and registered trademarks appearing on Examples Java Code Geeks are the property of their respective owners. Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries. Examples Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.