Topology query syntax

Edit online

The Inventory service replaces Search as the service providing the main query capabilities. This page details the supported query syntax.

Note: For the on-prem version only, from Agile Service Manager Version 1.1.17 the Search service has been replaced with the Inventory service. The OCP version of Agile Service Manager still uses the Search service.
About the inventory service:

This page describes the query syntax supported by the Inventory service search query endpoint (1.0/inventory/swagger#/Search/queryAll) which is in turn used by the UI for the querying features provided via the Resource management page search bar and advanced filtering functionality.

While the older Search service indexes only a sub-set of the information of a resource or group, the new inventory service can query all of the information.

Query syntax:
The main format of a supported query string consists of the following types:
Fuzzy or full-text search
A text to search its occurrence (or close similarity) over a set of well known properties.
Parameterized query
Tries to find items that contain properties with the expected value, for example matching a certain property=value content. All of the properties of a resource or group can be queried, including custom properties.
Compound query
A combination of the other two to provide a more complex query where we try to find items matching a full-text search that we further restrict to those also matching properties with some expected value.
Tip: Most of the information described here is also summarized in the API swagger page document:
https://<host>/1.0/inventory/swagger#/Search/queryAll

Fuzzy (full-text) search

A fuzzy query conducts a full-text search to find fragments of information that contain a certain string within the following subset of an item's information:
  • uuid
  • uniqueId
  • name
  • keyIndexName
  • description
  • businessCriticality
  • types (that is, entityTypes)
  • tokens (all types)
Supported syntax
Provide a string to be found in any part of the queried properties, such as mystring, where typically this is a substring of an expected value,although it can also be the full string.
Note: The string may contain spaces.
You can use the wildcard (*) character to specify how a substring should be matched:
  • *string - expects a suffix matching
  • string* - expects a prefix matching
  • *string* - expects a wrapped matching
Note: The wildcard character will only be interpreted when used at the beginning or end of the string.
You can use quotes to specify an exact match, as in "my expected match". This functions like the mystring matching, but in combination with the wildcard it allows you to define the prefix/suffix matching criteria for a string with spaces, for example:
  • "expected match"* - looks for the specified string (including the spaces) as the matching prefix

Parameterized query

A parameterized query lets you find items that contain a property matching an expected value. You can query or match any property of a resource or group including any custom property, which means that this query is not limited to a set of well-known properties, unlike the fuzzy query type (or the former Search type).

Supported syntax
The syntax is based on the one defined for the fuzzy / full-text search.
You can specify the exact value, such as property=value
You can specify the expected value using wildcards, such as:
  • property=*value
  • property=value*
  • property=*value*
You can use quotes to wrap the expected value (which can have spaces), for example:
  • property="complex value" (which can also use wildcards)
Operators
This type of query also supports different operators that modulate how the user expects the matching of the expected value, or substring of a matching value. These queries accept a comma-separated list of values.
Comparison operators
=, >, >=, <, <=
The comparison operators other than = are targeted at numeric properties; so if the property specified has a string as the value, then the comparison is likely to be done on the numeric counterpart of the characters, thereby potentially rendering some unexpected results.
Note: For the date values either an epoch value or timestamp value will be valid.
Collection operators
:,
Complex queries
You can specify several property-matching terms in the same query linking them with the AND / OR boolean operators to define a complex query criteria. For example:
  • property1=value1 AND property2>value2 OR property3=value3
Also, each term can in turn be logically negated by using the NOT operator, as in the following example:
  • property1=value1 AND NOT property2>value2 where the expected result will contain items for which property2 value is <=value2 (as per the negated term).

Compound query

A compound query combines a fuzzy / full-text query and parameterized query to let you specify a full-text search term and also properties to match as part of the same criteria, such as string AND property=value.

The syntax described for these two types applies to a compound query, with the following restrictions. If not followed, the query will be rejected as being of an invalid format.
  • The fuzzy query segment must be specified first.
  • The fuzzy query must be connected to the parameterized part using AND.

Examples

Fuzzy query example
Fuzzy matching of items with a couple of words:
my server
Fuzzy query example 2
Fuzzy matching of items with a certain prefix, for example all FQDN servers for which the user knows the first part of the string. 
host-*
Parameterized query example: Discovery date
Finding servers discovered after a certain date:
entityType=server AND createTime>="2023-02-16T13:30:00.000Z"
Parameterized query example: Tags
Finding servers tagged with a certain values:
entityType=server AND tags:production,backend
Parameterized query example: Business criticality
Finding servers who have been assigned a business criticality of 'gold':
entityTypes=server AND businessCriticality=gold
Defining business criticality is described here.
Parameterized query example: Status
Finding servers with a status of 'critical':
entityTypes=server AND alert_severity=critical
Compound query example
Finding images with the string test that also match a custom property for a certain release:
test AND entityType=image AND release=1