Getting started

Only a few steps are necessary to get started with a standard configuration. Several code examples can be found here.

Start Elasticsearch

picturesafe-search requires a running Elasticsearch server from version 7.x.

Local installation of Elasticsearch

For a new application an Elasticsearch server must be installed first:

  • Download and unpack the Elasticsearch official distribution.
  • Run bin/elasticsearch on Linux or macOS. Run bin\elasticsearch.bat on Windows.

Some features of picturesafe-search (for example sorting documents in a language-specific word order) require the ICU Analysis Plugin for Elasticsearch:

  • Run bin/elasticsearch-plugin install analysis-icu on Linux or macOS. Run bin\elasticsearch-plugin install analysis-icu on Windows.

Run Elasticsearch in a Docker container

As an alternative to installing Elasticsearch you can run it in a Docker container. To do this you can use the provided Docker Compose file.

  • Install Docker and Docker Compose.
  • Clone the picturesafe-search GitHub repository.
  • Run docker-compose -f src/test/docker/docker-compose.yml up -d from the project directory to start Elasticsearch.
  • To stop Elasticsearch run docker-compose -f src/test/docker/docker-compose.yml stop from the project directory.

Include java library

Add the current version of the picturesafe-search library to your project.

Maven dependency



Configuration bean

Implement a configuration class that imports the DefaultElasticConfiguration.class. This configuration can be extended later.

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)
  • Field ‘count’ (Elasticsearch type integer, sortable)

Spring configuration

@ComponentScan(basePackages = {""})
public class Config {

    List<FieldConfiguration> fieldConfigurations() {
        return Arrays.asList(
                    "title", ElasticsearchType.TEXT).copyToFulltext(true).sortable(true).build(),
                    "count", ElasticsearchType.INTEGER).sortable(true).build()

Configuration properties

Add a file to the classpath of your application and define the following key (this configuration can be extended later):

Property file


Service implementation

Inject the SingleIndexElasticsearchService and implement an expression-based search:

  • Create an Elasticsearch index with alias
  • Add some documents to the index
  • Create an OperationExpression with two terms
  • Run the search query
  • Delete the Elasticsearch index

If you want to implement searches for more than one index, please use ElasticsearchService instead of SingleIndexElasticsearchService.

Spring service implementation

public class GettingStarted {

    private static final Logger LOGGER = LoggerFactory.getLogger(GettingStarted.class);

    private SingleIndexElasticsearchService singleIndexElasticsearchService;

    public static void main(String[] args) {
        final AnnotationConfigApplicationContext ctx
            = new AnnotationConfigApplicationContext(GettingStarted.class);
        final GettingStarted gettingStarted = ctx.getBean(GettingStarted.class);;

    private void run() {

        singleIndexElasticsearchService.addToIndex(DataChangeProcessingMode.BLOCKING, Arrays.asList(
      "title", "This is a test title").put("count", 101).build(),
      "title", "This is another test title").put("count", 102).build(),
      "title", "This is one more test title").put("count", 103).build()

        final Expression expression = OperationExpression.and(
                new FulltextExpression("test title"),
                new ValueExpression("count", ValueExpression.Comparison.GE, 102));

        final SearchResult searchResult = singleIndexElasticsearchService
            .search(expression, SearchParameter.DEFAULT);;


With implementations of the picturesafe-search Expression-Interface complex terms of different search conditions can be easily defined.

Here are some examples:

Simple fulltext search

Expression expression = new FulltextExpression("test title");

Simple field search

Expression expression = new ValueExpression("title", "test");

Simple field search with comparison operator

Expression expression = new ValueExpression("count", ValueExpression.Comparison.GE, 102);

Search with two terms

Expression expression = OperationExpression.and(
    new FulltextExpression("test title"),
    new ValueExpression("count", ValueExpression.Comparison.GE, 102));

In addition there are further Expressions like InExpression, MustNotExpression, RangeValueExpression, DayExpression, …