Expressions

Expressions can be used to create search queries on an Elasticsearch index:

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

Overview

The interface Expression is the base of all expression implementations. In picturesafe-search the following predefined expressions are supported:

Expression	Description	Comparison operator supported?
`FulltextExpression`	Expression to match values or query strings on fulltext fields	Yes
`ValueExpression`	Expression to match values on fields	Yes
`KeywordExpression`	Expression to match whole terms on keyword fields	Yes
`OperationExpression`	Expression to combine several expressions via a logical operation	-
`RangeValueExpression`	Expression to query ranges between two values	Yes
`DayExpression`	Expression to match a specific day	Yes
`DayRangeExpression`	Expression to query ranges between two days (omitting the time of day)	Yes
`InExpression`	Expression to match a set of values	-
`IsNullExpression`	Expression to match null values	-
`MustNotExpression`	Expression defining a negation of another expression	-
`FindAllExpression`	Expression to match all documents	-

FulltextExpression

The FulltextExpression can be used to match values on fulltext fields:

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

Prerequisite is that a fulltext field has been defined in the field configuration and at least one field has been configured as copyToFulltext.

Example:

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

ValueExpression

A ValueExpression can be used to match values on regular fields:

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

By default, the expression uses the “equals” field comparator. The expression above corresponds to the following:

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

Further field comparators are explained below.

KeywordExpression

The KeywordExpression should be used to match whole terms on keyword fields:

Expression expression = new KeywordExpression("keyword", "this is a test");

Keyword fields are not analyzed and therefore will only match on whole terms. For example if the ‘keyword’ field contains the term “this is a test” the KeywordExpression("keyword", "test") would not match but ` KeywordExpression(“keyword”, “this is a test”)`would match.

OperationExpression

An OperationExpression can be used to combine several expressions via a logical operation.

In the following example a FulltextExpression and a ValueExpression are combined using the AND operator.

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

In the same way expressions can be combined using the OR operator:

Expression expression = OperationExpression.or(
    new ValueExpression("city", "Hamburg"),
    new ValueExpression("keyword", "HH"),
    new ValueExpression("title", ValueExpression.Comparison.NOT_EQ, "Hamburg")

Operands of OperationExpressions may be OperationExpressions themselves. In this way complex search expressions can be created:

Expression expression = OperationExpression.and(
        new ValueExpression("count", ValueExpression.Comparison.GE, 100),
        OperationExpression.or(
                new ValueExpression("city", "Hamburg"),
                new ValueExpression("keyword", "HH"))
);

RangeValueExpression

The RangeValueExpression can be used to search for ranges between two values.

// Finds results with count 3, 4 and 5
Expression expression = new RangeValueExpression("count", 3, 5);

DayExpression

A DayExpression can be used to match a specific day.

Date day = new SimpleDateFormat("dd.MM.yyyy").parse("01.01.2020");
Expression expression = new DayExpression("created", day);

DayRangeExpression

A DayRangeExpression can be used to query ranges of days.

Date day1 = new SimpleDateFormat("dd.MM.yyyy").parse("01.01.2020");
Date day2 = new SimpleDateFormat("dd.MM.yyyy").parse("31.12.2020");
Expression expression = new DayRangeExpression("created", day1, day2);

InExpression

The InExpression can be used to match a set of values.

Expression expression = new InExpression("count", 1, 2, 5, 6);

IsNullExpression

The IsNullExpression can be used to match null values.

// Finds results without a 'title' field in the index document
Expression expression = new IsNullExpression("title");

MustNotExpression

A MustNotExpression can be used to define a negation of another expression.

// Finds results with 'city' not being 'Hamburg'
Expression expression 
= new MustNotExpression(new ValueExpression("city", "Hamburg"));

FindAllExpression

The FindAllExpression simply matches all documents in the Elasticsearch index. This can be useful for aggregations to build facets on the whole index data.

// Finds all documents
Expression expression = new FindAllExpression();

Comparison operator

The following table gives an overview of the comparison operators which are supported by the ValueExpression (as described above):

Operator	Comparison	Description
EQ	equals	token based equality
NOT_EQ	not equals	negated token based equality
LIKE	like	token based wildcard query - wildcards `?` for single character and `` for multiple characters, e.g `n?ce* sample*`
NOT_LIKE	not like	negated token based wildcard query - wildcards `?` for single character and `` for multiple characters, e.g `n?ce* sample*`
GT	greater than	mathematical `>` (does not work on text fields)
GE	greater equals	mathematical `>=` (does not work on text fields)
LT	lower than	mathematical `<` (does not work on text fields)
LE	lower equals	mathematical `<=` (does not work on text fields)
TERM_STARTS_WITH	term starts with	term based query (only works on keyword fields)
TERM_ENDS_WITH	term ends with	term based query (only works on keyword fields)
TERM_WILDCARD	term wildcard	term based wildcard query (only works on keyword fields) - wildcards `?` for single character and `` for multiple characters, e.g `n?ce* sample*`

Note: Term based queries operate on the textual content of (keyword) fields in its entirety, rather than operating on single tokens (e.g. words) as token based queries do.

Samples

new ValueExpression("count", ValueExpression.Comparison.GE, 1000);

new ValueExpression("title", ValueExpression.Comparison.NOT_EQ, "test");

new ValueExpression("keyword", ValueExpression.Comparison.TERM_STARTS_WITH, "This");

Indexing

Search parameter

picturesafe-search