Search module

The Search module allows you to have basic full text search functionalities to your JPA Model. It is based on Lucene, and requires a real file system to store its indexes.

Version

Search module versions 2.x require playframework version 1.1.

What’s new

Enable the module

In the /conf/application.conf file, enable the Search module by adding this line:

# The search module
module.search=${play.path}/modules/search

Indexing your objects

Use the @Indexed annotation to mark your Model, and then use the @Field to mark the fields to be indexed.

@Indexed
public class Folder extends Model {
    @Field
    @Column(unique=true)
    public Integer poseidonNumber; 
    @Field
    public String object;

The @Field annotation currently supports only primitive types.

Search the objects

Use the Search helper to build your queries:

Search.search("object:dogs", Folder.class)

The first parameter is a lucene query and the second is your Model class. You may want to refer to the Lucene query documentation at this point, knowing that the Search maintains a separated index per class and adds the properties marked with @Field as a Lucene Field.

The Search.search returns a query object that you can tweak:

Query q = Search.search("object:dogs", Folder.class);
q.orderBy("object")
    .page(2,5)
    .reverse();
    

To finish your query, if you wish to retrieve your Model objects, use

List<Folder> folders = q.fetch();
    

or to get only ids (to use in a JPA query by example...):

List<Long> folderIds = q.fetchIds();
    

To get full informations (like relevance), you would use:

List<QueryResult> results = q.executeQuery();
    

Maintaining the indexes

Each time you create, update or delete your Model objects, the corresponding index is automatically updated.

Should you need to re-index your objects (like if you have manually modified your database), you will reboot your application with:

play.search.reindex=enabled

or

play.search.reindex=true

Embedded console

There is an embedded console exposed at /@search . It is turned on in dev mode with default password “search” (without quotes), and only available in production mode if you have set a password in your configuration file :

play.search.password=mysecretpassword

In your conf/application.conf. Don’t forget to remove it after!

Here are all the configuration keys you can tweak related to the console :

play.search.login=search
play.search.password=search
play.search.auth.method=http

play.search.login Login used to authenticate on the console. Default is search
play.search.password Password used to authenticate on the console. Default is search
play.search.auth.method Authentication method to access console. http|session

Since version 1.1, the create/update/delete of a JPA object is synchronous. It means that once you made a change to an object, the corresponding reader will automaticly be re-opened to reflect the changes. This behaviour should be ok most of the time, but should you want to increase performances, like for large updates, you could use the property

play.search.synch=false

To have the auto re-opening suspended. Use Search.dirtyReader with a className to re-open when you’re done with your massive updates.

Misc configuration

You can use the following properties in your conf/application.conf file:

play.search.path=/tmp/myDevApplication
play.search.analyser=org.apache.lucene.analysis.standard.StandardAnalyzer
play.search.lucene.version=30
play.search.defaultSearchField=allfield

play.search.path is where the module stores its indexes
play.search.analyser is the lucene analyzer class used for indexation.
play.search.lucene.version is the lucene’s version (for compatibility mode). Default: 30
play.search.defaultSearchField is the default field name used when parsing queries. Default : allfield (special field containing all other fields)

Lucene Version

The Lucene version is a compatibility mode (see Lucene Version Enum in the Lucene's documentation). The value stands for the version of Lucene (30 means Lucene 3.0.x, 23 means Lucene 2.3.x, which was the version used in play-search <= 1.4). If you want to use your previous indexes without rebuilding them, you can set this property to 23. The default value is 30.