Topology query syntax

The Inventory service is used by the UI for the querying features that are provided through the search bar and advanced filtering functionality.

While previous searching technology indexed only a subset of the information of a resource or group, the 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.

Fuzzy or 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 can 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 quotation marks to specify an exact match, as in "my expected match". This syntax 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 or full-text search.

You can specify the exact value, such as property=value

You can specify the expected value by using wildcards. For example:

  • property=*value
  • property=value*
  • property=*value*

You can use quotation marks to wrap the expected value (which can have spaces), such as. 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.

  • 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 is valid.

  • Collection operators: :,!:

    Comparison and collection operators accept a comma-separated list of values.

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 contains items for which property2 value is <=value2 (per the negated term).

Compound query

A compound query combines a fuzzy or 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 that is described for these two types applies to a compound query, with the following restrictions. If not followed, the query is 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 by 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 that are discovered after a certain date:

  • entityType=server AND createTime>="2023-02-16T13:30:00.000Z"

Parameterized query example: Tags

Finding servers tagged with certain values:

  • entityType=server AND tags:production,backend

Parameterized query example: Busines criticality

Finding servers who have been assigned a business criticality of 'gold':

  • entityTypes=server AND businessCriticality=gold

    Tip: Defining business criticality is described here.

Parameterized query example: Status

Finding servers with a status of 'critical':

  • entityTypes=server AND alert_severity=critical

Parameterized query example: Group membership

Finding every member of a specified resource group:

  • memberOfGroup=ID

You can find the resource group ID listed on the 'Properties' tab of the resource group More details page.

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