Spring configuration

picturesafe-search provides a default spring configuration which can be extended as required.

The DefaultElasticConfiguration.class contains the following standard configurations, which are described in detail below:

• DefaultClientConfiguration.class: Elasticsearch rest client settings like ‘host address’
• DefaultIndexConfiguration.class: Elasticsearch index settings like ‘index name’, ‘number of shards’ or ‘charset mappings’
• DefaultQueryConfiguration.class: Configuration of query and filter factories
• DefaultAggregationConfiguration.class: Configuration of aggregation builder factories and aggregation properties

Importing DefaultElasticConfiguration.class is equivalent to importing DefaultClientConfiguration.class, DefaultIndexConfiguration.class, DefaultQueryConfiguration.class and DefaultAggregationConfiguration.class, as shown in the following example:

Spring configuration

@Configuration
@ComponentScan(basePackages = {"de.picturesafe.search.elasticsearch"})
@Import({DefaultElasticConfiguration.class}) 
// same as @Import({DefaultClientConfiguration.class, 
//                  DefaultIndexConfiguration.class, 
//                  DefaultQueryConfiguration.class,
//                  DefaultAggregationConfiguration.class})
public class Config {

}

Default configuration

With above DefaultElasticConfiguration, only one bean needs to be defined to provide a list of field configurations. The following example defines three fields for the Elasticsearch index:

• Field ‘id’ (Elasticsearch type text, sortable)
• Field ‘fulltext’ (Elasticsearch type text)
• Field ‘title’ (Elasticsearch type text, within fulltext, aggregatable, sortable)

@Configuration
@ComponentScan(basePackages = {"de.picturesafe.search.elasticsearch"})
@Import({DefaultElasticConfiguration.class})
public class Config {

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

The above field definition results in the following Elasticsearch mapping:

{
  "default-20200307-162008-396": {
    "mappings": {
      "properties": {
        "fulltext": {
          "type": "text"
        },
        "id": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword"
            }
          }
        },
        "title": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword"
            }
          },
          "copy_to": [
            "fulltext"
          ]
        }
      }
    }
  }
}

For simple use cases, picturesafe-search can also be used without field definitions. In this case an empty list can be returned:

@Configuration
@ComponentScan(basePackages = {"de.picturesafe.search.elasticsearch"})
@Import({DefaultElasticConfiguration.class})
public class Config {

    @Bean
    List<FieldConfiguration> fieldConfigurations() {
        return Collections.emptyList();
    }
}

Configuration properties

The default configuration additionally requires a configuration file named elasticsearch.properties in the classpath.

The following properties can be configured as required:

# ============ Elasticsearch configuration for picturesafe-search =============
#
# picturesafe-search requires a configuration file named 'elasticsearch.properties' in the classpath.
# You can use the following default parameters by leaving them commented or,
# if you want to change settings, uncomment lines and change the values.


# --------------------------- Client configuration ----------------------------

## List of host addresses to connect to (blank separated, format <hostname>:<port> or <ip>:<port>)
#elasticsearch.hosts=localhost:9200

## automatically discover nodes from a running Elasticsearch cluster and add them to an existing RestClient instance
#elasticsearch.sniffer.enabled=false

# --------------------------- Index configuration -----------------------------

#elasticsearch.index.alias=default

## Index name prefix (property 'elasticsearch.index.alias' will be used when empty)
#elasticsearch.index.name_prefix=

## Index name date format ('yyyyMMdd-HHmmss-SSS' will be used when empty)
#elasticsearch.index.name_date_format=yyyyMMdd-HHmmss-SSS

## Number of shards. For more information, please refer to the Elasticsearch documentation.
#elasticsearch.index.number_of_shards=1

## Number of replicas. For more information, please refer to the Elasticsearch documentation.
#elasticsearch.index.number_of_replicas=0

##  Maximum number of fields in the index (uses Elasticsearch default setting when empty)
#elasticsearch.index.fields_limit=1000

## Maximum result window size (uses Elasticsearch default setting when empty)
#elasticsearch.index.max_result_window=10000

## Enable the built-in picturesafe-search default analyzer. If disabled the Elasticsearch standard analyzer will be used.
#elasticsearch.index.default_analyzer.enabled=true

# --------------------------- Query configuration -----------------------------

## Time zone of the machine picturesafe-search is running on
#elasticsearch.service.time_zone=Europe/Berlin

# --- Query string preprocessor ---

## Enable preprocessing of fulltext query strings (will be enabled per default when empty)
#elasticsearch.querystring_preprocessor.enabled=true

## Enable adding brackets automatically in preprocessor (will be enabled per default when empty)
#elasticsearch.querystring_preprocessor.auto_bracket=true

## Enable adding missing operators automatically in preprocessor (will be enabled per default when empty)
#elasticsearch.querystring_preprocessor.insert_missing_operators=true

## Token delimiters in preprocessor (will be set to the following default value when empty)
#elasticsearch.querystring_preprocessor.token_delimiters:, "(){}[]:=\\/^~

## Synonyms for the operator AND (separated by blank, will be set to 'and und & +' when empty)
#elasticsearch.querystring_preprocessor.synonyms.AND=and und & +

## Synonyms for the operator OR (separated by blank, will be set to 'or oder | ,' when empty)
#elasticsearch.querystring_preprocessor.synonyms.OR=or oder | ,

## Synonyms for the operator NOT (separated by blank, will be set to 'not nicht -' when empty)
#elasticsearch.querystring_preprocessor.synonyms.NOT=not nicht -

# --- Aggregations ---

## The default maximum count for aggregation buckets
##
## Terms aggregation: This is the maximum number of aggregation results that will be resolved for one field. The parameter can be overridden dynamically by
## the corresponding {@link de.picturesafe.search.parameter.aggregation.TermsAggregation} instance.
#elasticsearch.service.aggregation.max_count=10

## The max count limit for aggregation buckets
##
## Terms aggregation: This is the upper limit of the maximum number of aggregation results that will be resolved for one field.
#elasticsearch.service.aggregation.max_count_limit=20

## The shard size factor
##
## Terms aggregation: The higher the requested size is, the more accurate the results will be, but also, the more expensive
## it will be to compute the final results. The shard_size parameter can be used to minimize the extra work that comes with
## bigger requested size. When defined, it will determine how many terms the coordinating node will request from each shard.
## Once all the shards responded, the coordinating node will then reduce them to a final result which
## will be based on the size parameter - this way, one can increase the accuracy of the returned terms and avoid the overhead
## of streaming a big list of buckets back to the client.
##
## shard_size = maxCount * shardSizeFactor
#elasticsearch.service.aggregation.shard_size_factor=5

Custom configuration

All beans implemented in the default configurations can also be partially or completely implemented manually, e.g. to support multiple search indices.

If, for example, a custom index configuration has to be implemented, then only the DefaultClientConfiguration and the DefaultQueryConfiguration can be imported. The beans required for index creation can be implemented manually.

@Configuration
@ComponentScan(basePackages = {"de.picturesafe.search.elasticsearch"})
@Import({DefaultClientConfiguration.class, DefaultQueryConfiguration.class})
public class Config {
   ...
}

Central Index Definition

Field configuration