Getting Started with Search

This guide shows how to start using Search in your application.

Let’s consider that you want to add a couple of entities into your application and set up searching among their attributes.

First, do the following:

  1. Add Search to your project according to the installation section.

  2. Configure a connection to Elasticsearch depending on the service location.

Create Data Model and Screens

Let’s create the following classes:

  1. The Status enumeration with the SILVER and GOLD values.

  2. The Customer entity with the fields:

    • firstName with String type.

    • lastName with String type.

    • status with Status type.

    • card with FileRef type.

  3. The Order entity with the fields:

    • number with String type.

    • amount with Integer type.

    • product with String type.

    • customer with association to Customer, many-to-one cardinality.

Create edit and browse screens for the Customer and Order entities.

Create Index Definition Interface

Then, you need to create Index Definition - an interface that describes what entities and attributes should be indexed. Let’s assume that we are going to search orders by their number, product name, customer status or customer last name. Within Index Definition we will create a method to define the necessary attributes.

@JmixEntitySearchIndex(entity = Order.class)
public interface OrderIndexDefinition {

    @AutoMappedField(includeProperties =
            {"number", "product", "customer.status", "customer.lastName"})
    void orderMapping();
}

  1. The interface should be annotated with @JmixEntitySearchIndex with the mandatory parameter entity.

  2. The interface can have any name.

  3. The @AutoMappedField annotation automatically maps requested properties. In our case we will use includeProperties parameter and specify names of the attributes that should be indexed.

  4. The method can have any name.

Configure Index Naming

By default, indexes created in the project have the search_index_ prefix. In the future, you may use the same Elasticsearch service in multiple projects. So, to ensure that the index names will be unique let’s change the default prefix. Add the following property to your application.properties file:

jmix.search.search-index-name-prefix = sample_prefix_

Configure Indexing Queue Processing

Jmix application tracks data changes but does not pass them to Elasticsearch automatically. To update Elasticsearch indexes regularly, include Quartz in your project as described in the Quartz Job Scheduler Setup section. As soon as the application has Quartz on the classpath, the Search add-on will use it for periodic processing of the indexing queue.

Create Search Screen

  1. Create a blank screen using Studio templates with the Search screen name.

  2. Add the xmlns:search="http://jmix.io/schema/search/ui namespace to the root element of the screen XML descriptor:

    <window xmlns="http://jmix.io/schema/ui/window"
        xmlns:search="http://jmix.io/schema/search/ui"
        caption="msg://searchScreen.caption">

  3. Add the searchField component inside the layout element:

    <layout>
    <search:searchField id="mySearchField"/>
</layout>

Now, the screen contains a text field for entering the search term and the button to run search.

Test Searching in Application

Now, we are ready to run and test the application.

First, add some instances of the Customer and Order entities.

Open the Search screen and let’s find customers with the Silver status.

search screen

The search results will be displayed in another screen.

search result

By clicking on one of the results, the editor screen will be opened.

customer editor