If the FTS base project is included as base project in the application, and the cuba.fts.enabled property is enabled, then each time when an indexable entity is being saved to the database its identifier gets added to the indexing queue - SYS_FTS_QUEUE table.

A separate asynchronous process periodically extracts identifiers of changed entities from the queue, loads entity instances and indexes them. Indexing is performed using the Apache Lucene library. Lucene document contains the following fields:

Indexed attributes are the attributes of the entity and related entities (if any), which are declared in the FTS descriptor.

Index is stored in the file system; by default it is located in the ftsindex subfolder of the application work folder (defined by the cuba.dataDir property); for a standard deployment this folder is tomcat/work/app-core/ftsindex. Index location can be changed using the cuba.fts.indexDir property.

Search is performed according to the following rules:

For Russian and English languages search accounts for word forms.

Search algorithm contains two stages:

Let us consider the simple case of linked Order and Customer entities mentioned above.

In this case, if all object attributes are indexed, indexing of two related instances of Order and Customer will create two Lucene documents with approximately the following content:

id: Order.id = "b671dbfc-c431-4586-adcc-fe8b84ca9617"
all: Order.number + Order.date + Order.amount = "001^2013-11-14^1000"
links: Customer.id = "f18e32bb-32c7-477a-980f-06e9cc4e7f40"

id: Customer.id = "f18e32bb-32c7-477a-980f-06e9cc4e7f40"
all: Customer.name + Customer.email = "John Doe^john.doe@mail.com"

Let’s assume our search string is "john":

Once the steps above are completed, full text search functionality will be added to the application and ready to work. If you log out of the system and then log in again, a search field will appear in the top right panel of the main application window. However, search will not produce any results because the data has not been indexed yet.

To start one-off indexing of the current state of the database (i.e. the entities listed in the FTS configuration file by default), open the app-core.fts:type=FtsManager JMX bean again and consequently invoke reindexAll() first and then processQueue(). After this, searching the "adm" string should give the following results:

You can use the platform’s scheduled tasks mechanism (see Application Development Guide -> CUBA Scheduled tasks) to invoke indexing process on a scheduled basis.

First, you will need to activate the task starting functionality itself. Add the following property to the app.properties file of the project core module:

cuba.schedulingActive = true

Restart the application server, log into the system as admin, open the JMX Console screen, find and open the app-core.cuba:type=Scheduling JMX bean and make sure that the Active attribute is set to true.

Then open the Administration -> Scheduled Tasks screen, click Create and fill in the following attribute values for a new task:

Save the task, select it in the table and click Activate. From now on, the system will start indexing changed entities every 30 seconds.

Create the fts.xml file with the following content in the source text directory of the core module:

<fts-config>
    <entities>

        <entity class="com.sample.library.entity.Author">
            <include re=".*"/>
        </entity>

        <entity class="com.sample.library.entity.Book">
            <include re=".*"/>
        </entity>

        <entity class="com.sample.library.entity.BookInstance">
            <include re=".*"/>
        </entity>

        <entity class="com.sample.library.entity.BookPublication">
            <include re=".*"/>
        </entity>

        <entity class="com.sample.library.entity.LibraryDepartment">
            <include re=".*"/>
        </entity>

        <entity class="com.sample.library.entity.LiteratureType">
            <include re=".*"/>
        </entity>

        <entity class="com.sample.library.entity.Publisher">
            <include re=".*"/>
        </entity>

        <entity class="com.sample.library.entity.Town">
            <include re=".*"/>
        </entity>

    </entities>
</fts-config>

This is the FTS configuration file, which in our case enables indexing of all domain model entities with all their attributes.

Add the following property to the app.properties file of the application core module:

cuba.ftsConfig = cuba-fts.xml fts.xml

As a result, indexing will include both the entities defined in the platform's cuba-fts.xml and the project’s fts.xml files.

Restart the application server. From now on, full text search should work for all entities of the application model as well as entities of the platform security subsystem: Role, Group, User.

Take the following steps to see the example of uploaded files content search: add the workflow base project, add EBook entity to the project and create and complete the book scanning workflow as described in the Workflow subsystem guide (see the section called “Additional Materials”). Further in this section it is assumed that the application already has an instance of EBook and that a file with the original book has already been uploaded as a result of the Book scanning process execution.

Add the following elements to the project’s fts.xml file:

...
        <entity class="com.sample.library.entity.EBook">
            <include name="publication.book"/>
            <include name="attachments.file"/>
        </entity>

        <entity class="com.haulmont.workflow.core.entity.CardAttachment" show="false">
            <include re=".*"/>
            <exclude name="card"/>

            <searchables>
                searchables.add(entity.card)
            </searchables>
        </entity>

    </entities>
</fts-config>

In order for search results screen to display the EBook instances properly, you should add @NamePattern annotation to the EBook class:

@NamePattern("%s|publication")
public class EBook extends Card {
...

After that, restart the application server. Open the JMX Console screen, open the app-core.fts:type=FtsManager JMX bean and invoke sequentially reindexAll() and processQueue() to re-index the existing instances in the database and files according to the new search configuration. All new and changed data will be indexed automatically with a delay depending on the scheduled task interval, i.e. not longer than 30 seconds.

As a result, if the database contains a book called Alice's Adventures with an original PDF available, search results for "alice" will look like this:

Search results for "rabbit" will look like this: