Hibernate Search
Apache Lucene™
Integration
Reference Guide
3.4.0.Final
iii
Preface ............................................................................................................................ vii
1. Getting started ............................................................................................................. 1
1.1. System Requirements ......................................................................................... 1
1.2. Using Maven ...................................................................................................... 2
1.3. Configuration ...................................................................................................... 3
1.4. Indexing ............................................................................................................. 7
1.5. Searching ........................................................................................................... 7
1.6. Analyzer ............................................................................................................. 8
1.7. What's next ...................................................................................................... 10
2. Architecture ............................................................................................................... 11
2.1. Overview .......................................................................................................... 11
2.2. Back end .......................................................................................................... 12
2.2.1. Back end types ...................................................................................... 12
2.2.2. Work execution ...................................................................................... 14
2.3. Reader strategy ................................................................................................ 14
2.3.1. Shared .................................................................................................. 14
2.3.2. Not-shared ............................................................................................. 15
2.3.3. Custom .................................................................................................. 15
3. Configuration ............................................................................................................. 17
3.1. Enabling Hibernate Search and automatic indexing ............................................. 17
3.1.1. Enabling Hibernate Search ..................................................................... 17
3.1.2. Automatic indexing ................................................................................. 17
3.2. Directory configuration ....................................................................................... 17
3.3. Sharding indexes .............................................................................................. 23
3.4. Sharing indexes ................................................................................................ 25
3.5. Worker configuration ......................................................................................... 25
3.6. JMS Master/Slave configuration ......................................................................... 28
3.6.1. Slave nodes ........................................................................................... 29
3.6.2. Master node .......................................................................................... 30
3.7. JGroups Master/Slave configuration ................................................................... 31
3.7.1. Slave nodes ........................................................................................... 31
3.7.2. Master node .......................................................................................... 32
3.7.3. JGroups channel configuration ................................................................ 32
3.8. Infinispan Directory configuration ....................................................................... 33
3.8.1. Requirements ......................................................................................... 34
3.8.2. Architecture ............................................................................................ 34
3.8.3. Infinispan Configuration .......................................................................... 35
3.9. Reader strategy configuration ............................................................................ 36
3.10. Tuning Lucene indexing performance ............................................................... 36
3.11. LockFactory configuration ................................................................................ 41
3.12. Exception Handling Configuration ..................................................................... 42
4. Mapping entities to the index structure ..................................................................... 45
4.1. Mapping an entity ............................................................................................. 45
4.1.1. Basic mapping ....................................................................................... 45
Hibernate Search
iv
4.1.2. Mapping properties multiple times ........................................................... 49
4.1.3. Embedded and associated objects .......................................................... 49
4.2. Boosting ........................................................................................................... 53
4.2.1. Static index time boosting ....................................................................... 53
4.2.2. Dynamic index time boosting .................................................................. 54
4.3. Analysis ............................................................................................................ 55
4.3.1. Default analyzer and analyzer by class .................................................... 55
4.3.2. Named analyzers ................................................................................... 56
4.3.3. Dynamic analyzer selection (experimental) ............................................... 62
4.3.4. Retrieving an analyzer ............................................................................ 63
4.4. Bridges ............................................................................................................. 64
4.4.1. Built-in bridges ....................................................................................... 64
4.4.2. Custom bridges ...................................................................................... 66
4.5. Providing your own id ....................................................................................... 71
4.5.1. The ProvidedId annotation ...................................................................... 71
4.6. Programmatic API ............................................................................................. 72
4.6.1. Mapping an entity as indexable ............................................................... 73
4.6.2. Adding DocumentId to indexed entity ...................................................... 74
4.6.3. Defining analyzers .................................................................................. 74
4.6.4. Defining full text filter definitions .............................................................. 76
4.6.5. Defining fields for indexing ...................................................................... 77
4.6.6. Programmatically defining embedded entities ........................................... 78
4.6.7. Contained In definition ............................................................................ 79
4.6.8. Date/Calendar Bridge ............................................................................. 81
4.6.9. Defining bridges ..................................................................................... 82
4.6.10. Mapping class bridge ............................................................................ 83
4.6.11. Mapping dynamic boost ........................................................................ 84
5. Querying .................................................................................................................... 85
5.1. Building queries ................................................................................................ 87
5.1.1. Building a Lucene query using the Lucene API ......................................... 87
5.1.2. Building a Lucene query with the Hibernate Search query DSL .................. 87
5.1.3. Building a Hibernate Search query .......................................................... 94
5.2. Retrieving the results ...................................................................................... 101
5.2.1. Performance considerations .................................................................. 102
5.2.2. Result size ........................................................................................... 102
5.2.3. ResultTransformer ................................................................................ 103
5.2.4. Understanding results ........................................................................... 103
5.3. Filters ............................................................................................................. 104
5.3.1. Using filters in a sharded environment ................................................... 108
5.4. Faceting ......................................................................................................... 110
5.4.1. Creating a faceting request ................................................................... 112
5.4.2. Applying a faceting request ................................................................... 113
5.4.3. Restricting query results ....................................................................... 114
5.5. Optimizing the query process ........................................................................... 115
v
5.5.1. Caching index values: FieldCache ......................................................... 115
6. Manual index changes ............................................................................................. 117
6.1. Adding instances to the index .......................................................................... 117
6.2. Deleting instances from the index .................................................................... 117
6.3. Rebuilding the whole index .............................................................................. 118
6.3.1. Using flushToIndexes() ......................................................................... 118
6.3.2. Using a MassIndexer ............................................................................ 119
7. Index Optimization ................................................................................................... 123
7.1. Automatic optimization ..................................................................................... 123
7.2. Manual optimization ........................................................................................ 124
7.3. Adjusting optimization ...................................................................................... 124
8. Monitoring ................................................................................................................ 125
8.1. JMX ............................................................................................................... 125
8.1.1. StatisticsInfoMBean .............................................................................. 125
8.1.2. IndexControlMBean .............................................................................. 125
8.1.3. IndexingProgressMonitorMBean ............................................................ 125
9. Advanced features ................................................................................................... 127
9.1. Accessing the SearchFactory ........................................................................... 127
9.2. Accessing a Lucene Directory .......................................................................... 127
9.3. Using an IndexReader ..................................................................................... 127
9.4. Use external services in Hibernate Search components (experimental) ............... 128
9.4.1. Exposing a service ............................................................................... 129
9.4.2. Using a service .................................................................................... 130
9.5. Customizing Lucene's scoring formula .............................................................. 131
10. Further reading ...................................................................................................... 133
