MANNING
Michael McCandless
Erik Hatcher
Otis Gospodnetic
F
OREWORD

BY
D
OUG
C
UTTING
Covers Apache Lucene 3.0
SECOND EDITION
IN ACTION
,
www.it-ebooks.info
Praise for the First Edition
This is definitely the book to have if you’re planning on using Lucene in your application, or are
interested in what Lucene can do for you.
—JavaLobby
Search powers the information age. This book is a gateway to this invaluable resource It suc-
ceeds admirably in elucidating the application programming interface (API), with many code
examples and cogent explanations, opening the door to a fine tool.
—Computing Reviews
A must-read for anyone who wants to learn about Lucene or is even considering embedding
search into their applications or just wants to learn about information retrieval in general.
Highly recommended!
—TheServerSide.com
Well thought-out thoroughly edited stands out clearly from the crowd I enjoyed reading this
book. If you have any text-searching needs, this book will be more than sufficient equipment to

—Reece Wilton, Walt Disney Internet Group
code samples as JUnit test cases are incredibly helpful.
—Norman Richards, co-author XDoclet in Action
A quick and easy guide to making Lucene work.
—Books-On-Line
A comprehensive guide The authors of this book are experts in this field they have unleashed
the power of Lucene the best guide to Lucene available so far.
—JavaReference.com
Licensed to theresa smith <[email protected]>
www.it-ebooks.info
Lucene in Action
Second Edition
MICHAEL MCCANDLESS
ERIK HATCHER
OTIS GOSPODNETIĆ
MANNING
Greenwich
(74° w. long.)
Licensed to theresa smith <[email protected]>
www.it-ebooks.info
For online information and ordering of this and other Manning books, please visit
www.manning.com. The publisher offers discounts on this book when ordered in quantity.
For more information, please contact
Special Sales Department
Manning Publications Co.
180 Broad St.
Suite 1323
Stamford, CT 06901
Email: [email protected]
©2010 by Manning Publications Co. All rights reserved.

3
■
Adding search to your application 74
4
■
Lucene’s analysis process 110
5
■
Advanced search techniques 152
6
■
Extending search 204
PART 2APPLIED LUCENE 233
7
■
Extracting text with Tika 235
8
■
Essential Lucene extensions 255
9
■
Further Lucene extensions 288
10
■
Using Lucene from other programming languages 325
11
■
Lucene administration and performance tuning 345
PART 3CASE STUDIES 381
12

Components for indexing 11
■
Components for searching 14
The rest of the search application 16
■
Where Lucene fits into your
application 18
1.4 Lucene in action: a sample application 19
Creating an index 19
■
Searching an index 23
1.5 Understanding the core indexing classes 25
IndexWriter 26
■
Directory 26
■
Analyzer 26
Document 27
■
Field 27
Licensed to theresa smith <[email protected]>
www.it-ebooks.info
CONTENTSviii
1.6 Understanding the core searching classes 28
IndexSearcher 28
■
Term 28
■
Query 29
■

■
Field option combinations 46
■
Field
options for sorting 46
■
Multivalued fields 47
2.5 Boosting documents and fields 48
Boosting documents 48
■
Boosting fields 49
■
Norms 50
2.6 Indexing numbers, dates, and times 51
Indexing numbers 51
■
Indexing dates and times 52
2.7 Field truncation 53
2.8 Near-real-time search 54
2.9 Optimizing an index 54
2.10 Other directory implementations 56
2.11 Concurrency, thread safety, and locking issues 58
Thread and multi-JVM safety 58
■
Accessing an index over a
remote file system 59
■
Index locking 61
2.12 Debugging indexing 63
2.13 Advanced indexing concepts 64

Near-real-time search 84
3.3 Understanding Lucene scoring 86
How Lucene scores 86
■
Using explain() to understand
hit scoring 88
3.4 Lucene’s diverse queries 90
Searching by term: TermQuery 90
■
Searching within a term
range: TermRangeQuery 91
■
Searching within a numeric range:
NumericRangeQuery 92
■
Searching on a string:
PrefixQuery 93
■
Combining queries: BooleanQuery 94
Searching by phrase: PhraseQuery 96
■
Searching by wildcard:
WildcardQuery 99
■
Searching for similar terms:
FuzzyQuery 100
■
Matching all documents:
MatchAllDocsQuery 101
3.5 Parsing query expressions: QueryParser 101

Parsing vs. analysis: when an analyzer isn’t appropriate 114
4.2 What’s inside an analyzer? 115
What’s in a token? 116
■
TokenStream uncensored 117
Visualizing analyzers 120
■
TokenFilter order can be
significant 125
4.3 Using the built-in analyzers 127
StopAnalyzer 127
■
StandardAnalyzer 128
■
Which core
analyzer should you use? 128
Licensed to theresa smith <[email protected]>
www.it-ebooks.info
CONTENTSx
4.4 Sounds-like querying 129
4.5 Synonyms, aliases, and words that mean the same 131
Creating SynonymAnalyzer 132
■
Visualizing token
positions 137
4.6 Stemming analysis 138
StopFilter leaves holes 138
■
Combining stemming and
stop-word removal 139

relevance 158
■
Sorting by index order 159
■
Sorting by
a field 160
■
Reversing sort order 161
■
Sorting by multiple
fields 161
■
Selecting a sorting field type 163
■
Using a
nondefault locale for sorting 163
5.3 Using MultiPhraseQuery 163
5.4 Querying on multiple fields at once 166
5.5 Span queries 168
Building block of spanning, SpanTermQuery 170
■
Finding
spans at the beginning of a field 172
■
Spans near one
another 173
■
Excluding span overlap from matches 174
SpanOrQuery 175
■

■
Boosting recently modified
documents using function queries 187
5.8 Searching across multiple Lucene indexes 189
Using MultiSearcher 189
■
Multithreaded searching
using ParallelMultiSearcher 191
5.9 Leveraging term vectors 191
Books like this 192
■
What category? 195
TermVectorMapper 198
5.10 Loading fields with FieldSelector 200
5.11 Stopping a slow search 201
5.12 Summary 202
6
Extending search 204
6.1 Using a custom sort method 205
Indexing documents for geographic sorting 205
■
Implementing
custom geographic sort 206
■
Accessing values used in custom
sorting 209
6.2 Developing a custom Collector 210
The Collector base class 211
■
Custom collector:

Retrieving payloads via TermPositions 230
6.6 Summary 231
Licensed to theresa smith <[email protected]>
www.it-ebooks.info
CONTENTSxii
PART 2APPLIED LUCENE 233
7
Extracting text with Tika 235
7.1 What is Tika? 236
7.2 Tika’s logical design and API 238
7.3 Installing Tika 240
7.4 Tika’s built-in text extraction tool 240
7.5 Extracting text programmatically 242
Indexing a Lucene document 242
■
The Tika utility class 245
Customizing parser selection 246
7.6 Tika’s limitations 246
7.7 Indexing custom XML 247
Parsing using SAX 248
■
Parsing and indexing using
Apache Commons Digester 250
7.8 Alternatives 253
7.9 Summary 254
8
Essential Lucene extensions 255
8.1 Luke, the Lucene Index Toolbox 256
Overview: seeing the big picture 257
■

Presenting the result to the user 281
Some ideas to improve spell checking 281
8.6 Fun and interesting Query extensions 283
MoreLikeThis 283
■
FuzzyLikeThisQuery 284
BoostingQuery 284
■
TermsFilter 284
■
DuplicateFilter 285
RegexQuery 285
Licensed to theresa smith <[email protected]>
www.it-ebooks.info
CONTENTS xiii
8.7 Building contrib modules 286
Get the sources 286
■
Ant in the contrib directory 286
8.8 Summary 287
9
Further Lucene extensions 288
9.1 Chaining filters 289
9.2 Storing an index in Berkeley DB 292
9.3 Synonyms from WordNet 294
Building the synonym index 295
■
Tying WordNet synonyms
into an analyzer 297
9.4 Fast memory-based indices 298

API compatibility 334
■
Index compatibility 335
10.4 KinoSearch and Lucy (Perl) 335
KinoSearch 336
■
Lucy 338
■
Other Perl options 338
10.5 Ferret (Ruby) 338
10.6 PHP 340
Zend Framework 340
■
PHP Bridge 341
Licensed to theresa smith <[email protected]>
www.it-ebooks.info
CONTENTSxiv
10.7 PyLucene (Python) 341
API compatibility 342
■
Other Python options 343
10.8 Solr (many programming languages) 343
10.9 Summary 344
11
Lucene administration and performance tuning 345
11.1 Performance tuning 346
Simple performance-tuning steps 347
■
Testing approach 348
Tuning for index-to-search delay 349

12.1 Introducing Krugle 384
12.2 Appliance architecture 385
12.3 Search performance 386
12.4 Parsing source code 387
12.5 Substring searching 388
12.6 Query vs. search 391
12.7 Future improvements 391
FieldCache memory usage 392
■
Combining indexes 392
12.8 Summary 392
Licensed to theresa smith <[email protected]>
www.it-ebooks.info
CONTENTS xv
13
Case study 2: SIREn
Searching semistructured documents with SIREn 394
13.1 Introducing SIREn 395
13.2 SIREn’s benefits 396
Searching across all fields 398
■
A single efficient lexicon 398
Flexible fields 398
■
Efficient handling of multivalued
fields 398
13.3 Indexing entities with SIREn 399
Data model 399
■
Implementation issues 400

IndexReaders 423
■
Comparison with Lucene near-real-time
search 424
■
Distributed search 425
14.3 Summary 427
appendix a Installing Lucene 428
appendix b Lucene index format 433
appendix c Lucene/contrib benchmark 443
appendix d Resources 465
index 469
Licensed to theresa smith <[email protected]>
www.it-ebooks.info
Licensed to theresa smith <[email protected]>
www.it-ebooks.info
xvii
foreword
Lucene started as a self-serving project. In late 1997, my job uncertain, I sought some-
thing of my own to market. Java was the hot new programming language, and I
needed an excuse to learn it. I already knew how to write search software, and thought
I might fill a niche by writing search software in Java. So I wrote Lucene.
In 2000, I realized that I didn’t like to market stuff. I had no interest in negotiating
licenses and contracts, and I didn’t want to hire people and build a company. I liked
writing software, not selling it. So I tossed Lucene up on SourceForge, to see if open
source might let me keep doing what I liked.
A few folks started using Lucene right away. In 2001, folks at Apache offered to
adopt Lucene. The number of daily messages on the Lucene mailing lists grew
steadily. Code contributions started to trickle in. Most were additions around the
edges of Lucene: I was still the only active developer who fully grokked its core. Still,

every new release Lucene is getting better, more mature, more feature-rich, and faster.
Since the first edition of Lucene in Action was published in 2004, Lucene internals
and its
API have gone through radical changes that called for more than just minor
book updates. In this totally revised second edition, the authors bring you up to speed
on the latest improvements and new
APIs in Lucene.
Armed with the second edition of Lucene in Action, you too are now a member of
the Lucene community, and it’s up to you to take Lucene to new places. Bon voyage!

D
OUG CUTTING
FOUNDER OF LUCENE,
N
UTCH, AND HADOOP

Licensed to theresa smith <[email protected]>
www.it-ebooks.info
xix
preface
I first started with Lucene about a year after the first edition of Lucene in Action was
published. I already had experience building search engines, but didn’t know much
about Lucene in particular. So, I picked up a copy of Lucene in Action by Erik and Otis
and read it, cover to cover, and I was hooked!
As I used Lucene, I found small improvements here and there, so I started contrib-
uting small patches, updating javadocs, discussing topics on Lucene’s mailing lists,
and so forth. I eventually became an active core committer and
PMC member, com-
mitting many changes over the years.
It has now been five-and-a-half years since the first edition of Lucene in Action was

idly. I was intrigued with the idea of developing a system to manage the pictures so
that I could attach meta-data to each picture, such as keywords and date taken, and, of
course, locate the pictures easily in any dimension I chose. In the late 1990s, I proto-
typed a filesystem-based approach using Microsoft technologies, including Microsoft
Index Server, Active Server Pages, and a third
COM component for image manipula-
tion. At the time, my professional life was consumed with these same technologies. I
was able to cobble together a compelling application in a couple of days of spare-time
hacking.
My professional life shifted toward Java technologies, and my computing life con-
sisted of less and less Microsoft Windows. In an effort to reimplement my personal
photo archive and search engine in Java technologies in an operating system–agnostic
way, I came across Lucene. Lucene’s ease of use far exceeded my expectations—I had
experienced numerous other open-source libraries and tools that were far simpler
conceptually yet far more complex to use.
Licensed to theresa smith <[email protected]>
www.it-ebooks.info
PREFACE TO THE FIRST EDITION xxi
In 2001, Steve Loughran and I began writing Java Development with Ant (Manning).
We took the idea of an image search engine application and generalized it as a docu-
ment search engine. This application example is used throughout the Ant book and
can be customized as an image search engine. The tie to Ant comes not only from a
simple compile-and-package build process but also from a custom Ant task, <index>,
we created that indexes files during the build process using Lucene. This Ant task now
lives in Lucene’s Sandbox and is described in section 8.4 of the first edition.
This Ant task is in production use for my custom blogging system, which I call
BlogScene (http://www.blogscene.org/erik). I run an Ant build process, after creat-
ing a blog entry, which indexes new entries and uploads them to my server. My blog
server consists of a servlet, some Velocity templates, and a Lucene index, allowing for
rich queries, even syndication of queries. Compared to other blogging systems, Blog-

Licensed to theresa smith <[email protected]>
www.it-ebooks.info
PREFACE TO THE FIRST EDITIONxxii
high-quality information from online newsletters, journals, newspapers, and maga-
zines. In addition to my own software, which consisted of large sets of Perl modules
and scripts, Infojump utilized a web crawler called Webinator and a full-text search
product called Texis. The service provided by Infojump in 1998 was much like that of
FindArticles.com today.
Although WebPh, Populus, and Infojump served their purposes and were fully
functional, they all had technical limitations. The missing piece in each of them was a
powerful information-retrieval library that would allow full-text searches backed by
inverted indexes. Instead of trying to reinvent the wheel, I started looking for a solu-
tion that I suspected was out there. In early 2000, I found Lucene, the missing piece
I’d been looking for, and I fell in love with it.
I joined the Lucene project early on when it still lived at SourceForge and, later, at
the Apache Software Foundation when Lucene migrated there in 2002. My devotion
to Lucene stems from its being a core component of many ideas that had queued up
in my mind over the years. One of those ideas was Simpy, my latest pet project. Simpy
is a feature-rich personal web service that lets users tag, index, search, and share infor-
mation found online. It makes heavy use of Lucene, with thousands of its indexes, and
is powered by Nutch, another project of Doug Cutting’s (see chapter 10 of the first
edition). My active participation in the Lucene project resulted in an offer from Man-
ning to co-author Lucene in Action with Erik Hatcher.
Lucene in Action is the most comprehensive source of information about Lucene.
The information contained in the chapters encompasses all the knowledge you need
to create sophisticated applications built on top of Lucene. It’s the result of a very
smooth and agile collaboration process, much like that within the Lucene community.
Lucene and Lucene in Action exemplify what people can achieve when they have simi-
lar interests, the willingness to be flexible, and the desire to contribute to the global
knowledge pool, despite the fact that they have yet to meet in person.

me to start and finish this book.
I would never have been part of this book without Doug having the initial itch,
technical strength, and generosity to open-source his idea, without a vibrant commu-
nity relentlessly pushing Lucene forward, without a forward-looking
IBM supporting
my involvement with Lucene and this book, and without Erik and Otis writing the
first edition.
My four kids—Mia, Kyra, Joel, Kyle—always inspire me, with everything they do.
Their boundless energy, free thinking, infinite series of insightful questions, amazing
happiness, insatiable curiosity, gentle persistence, free sense of humor, sheer passion,
temper tantrums, and sharp minds keep me very young at heart and inspire me to
tackle big projects like this. You should strive, always, to remain a child.
I thank my wife, Jane, for convincing me to pursue this when Manning came
knocking, and for her unmatched skills in efficiently running our busy family.
Remarkably, she has made lots of time for me to work, write this book and still pursue
all my crazy hobbies, and I can see that this ability is very rare.
My parents, all four of them, raised me with the courage to always stretch myself in
what I try to tackle, but also with the discipline and persistence to finish what I start.
They taught me integrity: if you commit to do something, you do it well. Always under-
promise and overdeliver. They also led by example, showing me that individuals can
do big things when they work hard. More importantly, they taught me that you should
spend your life doing the things you love. Life is far too short to do otherwise.
Erik Hatcher
First, and really only, heartfelt thanks go to none other than Mike McCandless. He has
pretty much single-handedly revised this book from its 1.0 release to the current spiffy
“3.0” state. Mike approaches Lucene, this book, and life in general enthusiastically,
with eagerness to tackle any task at hand. The first edition acknowledgments also very
much apply here, as these influences are timelessly felt.
I personally thank Otis for his efforts with this book. Although we’ve yet to meet in
person, Otis has been a joy to work with. He and I have gotten along well and have