Search Query Language

You use the search query language to define a search query, which is handled by the built-in procedure sys.esh_search(). The search query language offers a range of operators,wildcards and escaping rules while specifying a search request.

Basic Search Terms

The most simple search query consists of a single term, for example car.

This search returns all items where the term car is found in any relevant column of the search model.

The relevant columns are predefined in the search configuration. See the documentation for sys.esh_config().

Searching with several terms returns all items where all of the search terms are found in one or more fields, regardless of the order of the terms or the field.

A search for my car returns all items where both the term my and the term car occur in any field. Tokenization during query parsing is done exclusively at the space " " character.

Wildcards

The * wildcard can be used at any place inside a search token and stands for zero or more characters.

A search for car* returns all items where any relevant column contains a term starting with car, e.g. car, cars, care, carry, carbon, careful.

A search for *car returns all items where any relevant column contains a term ending with car, e.g. car, streetcar, autocar, flatcar.

A search for *car* returns all items where any relevant column contains a term containing the subterm car like car, cars, care, carry, carbon, careful, streetcar, autocar, flatcar, flatcars.

The ? wildcard can be used at any place in the search token and stands for any one character.

A search for ca?, for example, matches car, cat, can, but not cars, caterpillar, case.

You can also use wildcards within tokens, for example c*ar or c?ar.

Phrases

You can also use phrases in your search query. A phrase is a group of words written in double quotes. Phrase searches are used to find an exact phrase, for example "my car".

The search for "my car" returns all items where the complete phrase is found as it is in any relevant column.

Phrase searches can be combined with wildcards. The search for "my ca?" matches the phrases "my cat", "my car", "my can".

Operators

You can use the operators AND and NOT in your search queries.

The AND operator is the default operator.

The following search queries

my car

my AND car

my and car

return the same result.

The NOT operator is used to find items where one term is included but another is not.

A search for my NOT car returns all items where the term "my" is found in any freestyle field, but the term car is found is not found in any of the freestyle fields.

A shortcut for the NOT operator is the -. The following variants of the search query return the same result:

my NOT car

my AND NOT car

my and not car

my -car

The NOT operator can also be used with one term. A search for -car returns all items that do not have the term "car", same as * AND NOT car.

The OR operator is used to express that either search term should lead to a search result: my OR car returns all items where any of the search terms are found in any relevant column.

The NOT operator could also be used in conjunction with OR: my OR NOT car or my OR -car returns all items that have the term my in any field or car in no field. To help you understand mor easily, imagine a search execution as a set-based operation. Take the whole set of items and remove all items with the term car in any field. Now calculate the union with the set of items having the term my in any field. The same result would be returned with -(car –my) .

Boosting

A term can be boosted with the ^ operator.

The query my car^2 gives the term car a double weight compared to the term my.

The default value is 1. The weight must be a value >=0.

Grouping

Grouping can be used to build more complex search expressions using brackets, for example (my AND car) OR (her AND dog).

Searching in Fields

The search field can be specified using the field name followed by a colon title:car. This returns all items where the term car is found in the title field.

Field identifiers shall be case insensitive. Title, TITLE, TiTlE, title would address the same field title.

Field identifiers must be single words. There should be a configuration to declare the field identifier, which can differ from the technical name of the column. Also, it should be possible to define a list of fields as search scope.

Any search term from above could be used as the second part of the search. If there is more than one term and you want to search for all terms in only one field, then a grouping with brackets is necessary:

title:(my car)

title:"my car"

title:((my AND car) OR (her AND dog))

title:car~0.9

The search queries title:my car and car title:my would get the same results as the term car is searched for in all relevant columns.

You can extend the search scope using multiple fields. The default operator for scope is OR.

The following queries return all items where the term car is found in the title, author or abstract field:

(title OR author OR abstract):car

(title author abstract):car

You can also use the AND and NOT operators:

The query (title AND author AND abstract):car returns all items where the term car is found in the title andauthor and abstract field.

IN-Lists

You specify an IN-list as follows:

id:OR(K1 K2 K3 K4 K5 K6 K7)

This is a shorter and more convenient way from of the following statement:

id:K1 OR id:K2 OR id:K3 OR id:K4 OR id:K5 OR id:K6 OR id:K7

Fuzzy Search

Fuzzy search can be used to find similar terms.

The search query car~ matches with car, cars, can, cat.

If no value for fuzziness is provided, the default value of 0.8 is used. Use can specify a higher fuzziness value if you want to receive more precise results, or you can specify a lower fuzziness value if you want to match more tokens.

The fuzziness value needs to be a floating point number between 0.0 and 1.0 (e.g. car~0.9).

Escaping

The escaping of the special characters ^ # : ~ ( ) [ ] NOT_ AND_ OR_ NOT AND OR is done with double quotes "".

Escaping of the special characters * ? " \ is done with \ within a quoted token. "\*\*\*" searches for the token ***.

A search for "(3:3^2~#)-1" searches for the token (3:3^2~#)-1.. The special character "-" must be escaped if it is the first character of a token.

A search with a token having a - inside is supported.

A search for check-in searches for check-in, wheras check -in searches for check and excludes in.

A search for check "-in" searches for check and -in.

Precedence of Phrases and Operators

The following precedence is forged by the system handling a search:

  1. Special characters: ?*\^
  2. Phrases "" and special characters: ():
  3. Special characters: []
  4. Special character: ~
  5. The NOT_ operator
  6. The AND_ operator
  7. The OR_ operator
  8. The NOT operators: - NOT
  9. The AND operator
  10. The OR operator

Search on Single or Multiple Views

All examples above show searches on a single view. This is the case if only one searchable view exists in a system, or the UI restricts the search to one view. If more than one search view is available, a federated search is performed where the user needs the option to select a search scope. The search scope identifier is derived from the view name. Characters which are not allowed for OData identifiers are removed, such as . : / \ $. Package prefixes and context of SAP HANA CDS annotations are also removed.

Examples

Perform a search in all relevant columns of all connectors by just providing the token: car

Perform a search specifically in the document view: scope:document car

Perform a search in a list of views: scope:(document OR customer) car.

Perform a complex search query: scope:document car title:my This query searches in all document fields with the term car and additionally in the title field with the term my.

Example

Example of a call with sys.esh_search():

call esh_search('[ "/$all?$filter=Search.search(query=''scope:(document OR customer) car'')&$top=10" ]', ?);