Hibernate ORM gives your application code pretty much everything it needs to interact with the database. However, you probably still use some sort of SQL client to manually work with your database outside the context of your application code.
Likewise, it can be useful to explore a Lucene index manually without having to write code for the task. Luke (http://code.google.com/p/luke) is a very useful utility that fills this role for Lucene. You can use Luke to browse your indexes, test queries, and perform helpful tasks such as removing index locks that did not cleanly release.
The Luke download is a monolithic executable JAR file. Double-clicking the JAR, or otherwise executing it from a console prompt, brings up a graphical interface and a prompt for your index location, as shown in the following screenshot:
The previous screenshot shows Luke at startup. Unfortunately, Luke can only access filesystem-based indexes, not the RAM-based index used in this chapter. So in these examples, Luke points to the chapter5 code file directory's Maven project workspace. The App entity index is located under target/luceneIndex/com.packtpub.hibernatesearch.domain.App.
Notice the Force unlock, if locked checkbox near the top of the open-index dialog box. If you have an index for which a file lock did not cleanly release (refer to the Locking strategy section), then you can fix the problem by checking this box and opening the index.
Once you have opened a Lucene index, Luke displays an assortment of information about the number of indexed documents (that is, entities), the current state of optimization (that is, fragmentation), and other details, as shown in the following screenshot:
From the Tools menu at the top of the utility, you have options for performing basic maintenance tasks such as checking the index for corruption, or manual optimization (that is, defragmenting). These operations are best performed during off-peak hours, or during a full outage window.
The Documents tab allows you to browse through entities one by one, which may have some limited use. Much more interesting is the Search tab, which allows you to explore your index using free-form Lucene queries, as shown in the following screenshot:
The full-blown Lucene API is beyond the scope of this book, but here are some basics to get you started:
- Search expressions are in the form of a field name and a desired value, separated by a colon. For example, to search for apps in the
businesscategory, use the search expressioncategory:business. - Associated items may be specified with the entity field name, followed by a period, followed by the field name within the associated item. In the above screenshot, we are searching for all apps supported on the
xPhonedevice, by using the search expressionsupportedDevices.name:xphone. - Remember that the default analyzer converts terms into lower case during the indexing process. So if you wanted to search on
xPhonefor example, be sure to type it asxphone.
If you double-click on one of the search results found, then Luke flips over to the Documents tab with the relevant document loaded. Click on the Reconstruct & Edit button to examine that entity's fields, as shown in the following screenshot:
Browsing this data will give you a feel for how the analyzer parses your entities. Words will be filtered out, and text will be tokenized unless you configured the @Field annotation to the contrary (as we did with sorting_name). If a Hibernate Search query doesn't return the results that you expect, browsing field data in Luke can help you spot the issue.