Search parameter

When executing a search, a SearchParameter instance must be passed to define the general conditions of the search. For simple use cases SearchParameter.DEFAULT can be used:

SearchResult searchResult = singleIndexElasticsearchService
    .search(new FulltextExpression("query word"), SearchParameter.DEFAULT);

The attributes of SearchParameter affect various aspects of the search execution and the search result. The different parameter attributes can be defined via the SearchParameter builder:

SearchParameter searchParameter = SearchParameter.builder()
    .maxResults(1000)
    .maxTrackTotalHits(10000L)
    .pageSize(20)
    .pageIndex(1)
    .sortOptions(SortOption.desc("id"), SortOption.asc("title"))
    .language("de")
    .fieldsToResolve("id", "title", "caption", "city")
    .aggregations(DefaultAggregation.field("city"))
    .optimizeExpressions(true).build();
    
 SearchResult searchResult = singleIndexElasticsearchService
    .search(new FulltextExpression("query word"), searchParameter);    

Overview

Parameter	Description	Default
maxResults	Maximum number of results	10000
maxTrackTotalHits	Maximum number of total hits to track. If exceeded, tracking will be stopped and total hits count will be marked as not exact.	Elasticsearch server setting
pageSize	Pagination page size	100
pageIndex	Pagination page index (starts with 1)	1
sortOptions	Result sort options (in descending priority)	unsorted
language	Language for multilingual fields	language of user account
fieldsToResolve	Names of fields to be resolved in search result	all fields
aggregations	Aggregations of fields to build facets on	no aggregations
optimizeExpressions	Should expressions be optimized?	true

Description

maxResults

Sets the maximum number of results that can be paginated (default = 10000).

maxTrackTotalHits

Sets the maximum number of total hits to track. If this number is exceeded by the number of current search hits, tracking will be stopped and the total hits count will be marked as not exact.

See also the Elasticsearch documentation.

pageSize

Sets the pagination page size (default = 100).

The default page size and the default max page size can be overridden in elasticsearch.properties:

elasticsearch.service.default_page_size=100

elasticsearch.service.max_page_size=2000

pageIndex

Sets the pagination page index (starts with 1).

To get the next (or any other) page of a search result, the previous search must be executed again with the new page index.

A pagination sample can be found here.

sortOptions

Sets the result sort options (in descending priority).

Sort by field

The following example sorts first by id in descending order, then by title in ascending order:

SearchParameter searchParameter = SearchParameter.builder()
    .sortOptions(SortOption.desc("id"), SortOption.asc("title"))
    .build();

Fields can only be sorted if they have been configured as sortable in the corresponding field configuration.

@Bean
List<FieldConfiguration> fieldConfigurations() {
    return Arrays.asList(
            FieldConfiguration.ID_FIELD,
            // same as: 
            // StandardFieldConfiguration.builder("id", ElasticsearchType.TEXT)
            //   .sortable(true).build()
            FieldConfiguration.FULLTEXT_FIELD,
            StandardFieldConfiguration.builder("title", ElasticsearchType.TEXT)
                .copyToFulltext(true).sortable(true).build()
    );
}

Sort by relevance

Search results may be sorted by the relevance of the search hits:

SearchParameter searchParameter = SearchParameter.builder()
    .sortOptions(SortOption.relevance())
    .build();

The relevance of a search hit is calculated by Elasticsearch’s internal scoring algorithm.

A sort by relevance sample can be found here.

Sort by array values

To sort by fields which contain multiple values (arrays), an array mode may be set:

SearchParameter searchParameter = SearchParameter.builder()
    .sortOptions(SortOption.desc("quantities").arrayMode(SortOption.ArrayMode.SUM))
    .build();

Array mode	Description
MIN	Use the lowest value.
MAX	Use the highest value.
SUM	Use the sum of all values. May only be used on number based array fields.
AVG	Use the average of all values. May only be used for for number based array fields.
MEDIAN	Use the median of all values. May only be used for number based array fields.

A sort by array mode sample can be found here.

language

Sets the request language for multilingual fields (default = language of user account). This affects searching, sorting and faceting.

SearchParameter searchParameter = SearchParameter.builder()
    .language("de").build();

A prerequisite is that the query refers to a field that has been defined as multilingual:

@Bean
List<FieldConfiguration> fieldConfigurations() {
    return Arrays.asList(
            StandardFieldConfiguration.builder("title", ElasticsearchType.TEXT)
                .multilingual(true).build()
    );
}

A multilingual search sample can be found here.

fieldsToResolve

Sets the names of the fields to be resolved in the search result (default = all fields).

If an index document has many fields and not all fields are required in the result, the fields to be resolved (returned) can be specified:

// only values of 'id', 'title' and 'caption' required in the result
SearchParameter searchParameter = SearchParameter.builder()
    .fieldsToResolve("id", "title", "caption")
    .build();

aggregations

Sets the aggregations of fields to build facets on (default = no aggregations).

// return aggregations (facets) for the fields 'city' and 'keyword'
SearchParameter searchParameter = SearchParameter.builder()
    .aggregations(TermsAggregation.field("city")
        , TermsAggregation.field("keyword").maxCount(5))
    .build();

A prerequisite is that the fields have been defined as aggregatable:

@Bean
List<FieldConfiguration> fieldConfigurations() {
    return Arrays.asList(
        StandardFieldConfiguration.builder("city", ElasticsearchType.TEXT)
            .aggregatable(true).build(),
        StandardFieldConfiguration.builder("keyword", ElasticsearchType.TEXT)
            .aggregatable(true).build()
    );
}

optimizeExpressions

Sets if expressions should be optimized (default = true).

If true, the passed expression is optimized internally and if necessary the complexity is reduced. For debugging it can sometimes be helpful to set optimizeExpressions to false:

SearchParameter searchParameter = SearchParameter.builder()
    .optimizeExpressions(false).build();

The Expression optimizer can generally be enabled/disabled via elasticsearch.properties (default = true).

elasticsearch.service.optimize_expressions.enabled=true

If the Expression optimizer is disabled in elasticsearch.properties, the search parameter optimizeExpressions is ignored.

Expressions

Searching