Elasticsearch service

Abstract

Vorto relies on Elasticsearch to search for models in productive environments.

Conversely, a custom JCR query building mechanism is in use in development environments.

Both resulting search services use a common intermediary syntax to simplify and harmonize the search.

The search is available as a text field in the web UI, and can be also performed as a GET request in the HTTP API.

How to search

Syntax

Vorto model can be searched with the following syntax.

See the vortolang 1.0 specification for a full description of all properties below.

Tag	Description	Values	Tag required	Example
Name	The model's name. If the term is tagged explicitly with name:, will search the displayName field If the term is not tagged, will search either the displayName or the description fields Values with no wildcards will automatically be added a trailing multi-character wildcard, e.g. name:abc becomes name:abc* behind the scenes.	Any	No	name:RaspberryPi RaspberryPi Rasp* *aspberry?? name:*Pi
Author	The author of the model	Any	Yes	author:mena author:m*
User reference	A shortcut for either author: or lastModifiedBy	Any	Yes	userReference:m*
Visibility	Whether the model is private or public	Private Public	Yes	visibility:Private visibility:*
Type	The model's type	Functionblock InformationModel Datatype Mapping	Yes	type:InformationModel type:funct*
State	The model's state	Draft InReview Released Deprecated	Yes	state:Draft state:release?
Namespace	The model's namespace	Any	Yes	namespace:vorto.private.mynamespace namespace:org.*
Version	The model's version	Any	Yes	version:1.* version:?.?.1

Note: The web UI contains a few drop-downs and checkboxes to complement the text-based search - those elements are equivalent to specifying a fixed value for a tag.

Search logic

Combined together, these search terms can produce powerful searches, with the following rules:

• All tags and values are case-insensitive
• Values cannot contain whitespace
• Tagged expressions must follow the strict [tag name case-insensitive][:][value] syntax
• All values can contain any number of single character (?) or multi-character (*) wildcards, even enumerated values like types or states
• Tags themselves cannot contain wildcards
• Multiple tags can be used, with the following rule:
  • All identical tags e.g. name:a* name:*b will return models matching either expression, inclusively
  • All different tags (including un-tagged name searches) will return models matching all expressions

Advanced search examples

The following examples illustrate and elaborate on the rules above.

Description	Syntax	Explanation
Multi-tag search with same tags	mymodel* name:my*2	The first term is an implicit name: search The second term is an explicit name: search. This expression will return models whose name or description either starts with mymodel, or ends starts with my and ends with 2
Multi-tag search with different tags	name:my* type:info* state:rel*	This will search for models that fulfill all conditions listed below: The model's name starts with my The model's type starts with info (i.e. only models of type InformationModel) The model's state starts with rel (i.e. only Released models) Models that do not fulfill all of those conditions altogether will not be returned.
Complex search	mymodel* myothermodel* userReference:bob visibility:* type:function* type:mapping state:draft state:\*re* namesapce:com.mycompany* version:1.0.?	This will return all models that fulfill all of the following conditions: The model's name starts with either mymodel or myothermodel The model's author or last modifying user is Bob Model visibility is irrelevant (thus this term is redundant here) Model's type is either Functionblock or Mapping Model's state is either Draft, or InReview or Released (note the * wildcard is for 0 or more characters) The model's version starts with 1.0. and has exactly one character after (note that the ? wildcard would also allow 1.0. as a version, but that would be an invalid version according to specifications, so no chance of finding that)

Index changes requiring re-creating the index

At time, the Elasticsearch index can change, e.g. when a model index field type is modified.

This can happen when allowing free-text search for enumerated types, thus changing the index type from key to text.

This requires re-creating the whole Vorto index for Elasticsearch.

One straightforward way to do this is to send an HTTP POST request to the /rest/forcereindex endpoint while authorized as a system administrator (i.e. with role ROLE_SYS_ADMIN).

In the web UI, this is done by:

1. Logging in to the Vorto site as a system administrator
2. Navigating to the manage section
3. Selecting the Global repository functions tab
4. Clicking Re-create index (as opposed to just Reindex)

The operation will entirely re-create the Vorto index, then re-index the model.

Caution is advised: back-up the model first.