StackState SaaS
🛑
Problem analysis
📈
Metrics and events
🧩
StackPacks
StackState Query Language (STQL)
StackState SaaS
Overview
This page describes how to use the built-in StackState Query Language (STQL) to write advanced topology component filters. STQL queries are used in StackState to write advanced topology filters.
An STQL query consists of component filters and functions. The query output is a component, or set of components, filtered from the complete topology.
StackState Self-Hosted
STQL queries can be combined with scripts in the Analytics environment.
Component filters
Component filters are used in two ways in STQL:
- Define the set of components to be included in the query output.
- Specify the set of components to be handled by an in-built STQL function.
Filters
The filters described below can be combined using the available operators to achieve complex selections of components.
Filter
Default
Description
domain"all"
Components in the specified domain(s).
environment"all"
Components in the named environment.
healthstate"all"
Components with the named health state.
label"all"
Components with the named labels.
layer"all"
Components in the named layer.
name"all"
Components with the specified name.
type"all"
Components of the specified type.
identifier"all"
Components with the specified URN identifier. The identifier filter is only compatible with basic filtering when it is specified using
identifier IN (...) and combined with other filters using an OR operator. When the set filter is compatible with basic filtering, the number of component identifiers queried will be reported in the Other filters box.Operators
The operators described below are available to use in STQL queries. Note that boolean operators will be executed in the standard order: NOT, OR, AND.
Operator
Description
Example
=
Equality matching
name = "DLL_DB"!=
Inequality matching
name != "DLL_DB"IN
Value is in subset
name in ("DLL_DB", "J2EE_04")NOT
Negation
name NOT in ("DLL_DB", "J2EE_04")AND and OR
Filter based on more than one condition or sub-query
name = "DLL_DB" OR type = "database"()
Use parenthesis to group results
(name = … AND type = …) OR (…)For example:
1
# Return all components named DLL_DB or J2EE_04 regardless of type:
2
name = DLL_DB OR name = J2EE_04
3
4
# Return only databases named DLL_DB and host systems named J2EE_04:
5
(name = DLL_DB AND type = database) OR (name = J2EE_04 AND type = "host systems")
Copied!
Wildcard
You can use
* as a full wildcard in a component filter. It is not possible to filter for partial matches using a wildcard character.Examples
1
# Select all components
2
name = "*"
3
4
# Select all components with name "serviceB"
5
name = "serviceB"
6
7
# Select all components in the "application" layer:
8
layer = "application"
9
10
# Select all components named either "appA" or "appB" that do not have a label "bck"
11
name IN ("appA","appB") NOT label = "bck"
12
13
# Select all components named "appA" that do not have a label "bck" or "test"
14
name = "appA" NOT label in ("bck", "test")
Copied!
Functions
withNeighborsOf
The function withNeighborsOf extends STQL query output, adding connected components in the specified direction(s). The number of topology levels included can be adjusted up to a maximum of 15.
withNeighborsOf(components=(), levels=, direction=)To be compatible with basic filtering, the function can only be combined with other filters using an
OR operator. When an advanced filter contains a function withNeighborsOf that is compatible with basic filtering, the number of components whose neighbors are queried for is shown in the Other filters box.Parameters / fields
Parameter
Default
Allowed values
Description
components"all"
A component filter
levels1
"all", [1:14]
The number of levels to include in the output. Use "all" to display all available levels (maximum 15)
direction"both"
"up", "down", "both"
up: only components that depend on the named component(s) will be added down: only dependencies of the named component(s) will be added both: components that depend on and dependencies of the named component(s) will be added.
Example
The example below will return all components in the application layer that have a health state of either "CRITICAL" or "DEVIATING". Components with names "appA" or "appB" and their neighbors will also be included.
1
layer = "application"
2
AND (healthstate = "CRITICAL" OR healthstate = "DEVIATING")
3
OR withNeighborsOf(components = (name in ("appA","appB")))
Copied!
withCauseOf - DEPRECATED
The
withCauseOf function has been deprecated. This functionality has been replaced by the Root Cause Analysis section in the visualizer. The construct will be parsed, but will not produce any additional components.Compatibility basic and advanced filters
You can switch between basic and advanced filtering by selecting Basic or Advanced under Filter Topology in the View Filters pane.
It is always possible to switch from Basic to Advanced filtering. The selected basic filters will be converted directly to an STQL query. For simple queries it is also possible to switch from Advanced to Basic filtering, however, some advanced queries are not compatible with basic filters.
- Basic filters cannot contain an inequality.
- Basic filters do not use
=, rather they are formatted using theINoperator. For examplename IN ("DLL_DB”)and notname = "DLL_DB”. - Basic filters use AND/OR in a specific way:
- All items in each basic filter box are joined with an OR:
layer IN ("business service", "applications", "databases") - The different basic filter boxes are chained together with an AND:
layer IN ("business service") AND domain IN ("online banking”) - The Include components basic filter box (name) is the exception - this is chained to the other filter boxes with an OR:
layer IN ("business service") AND domain IN ("online banking") OR name IN ("DLL_DB”) - The advanced filtering options withNeighborsOf function and identifier are only compatible with basic filtering if they are joined to other filters with an OR:
layer in ("Processes") OR identifier IN ("urn:test:component")
If you try to switch from an Advanced filter to a Basic filter and the query is not compatible, StackState will let you know and ask for confirmation to continue as you will lose some of the set filters. Alternatively, you can choose to stay in advanced filtering.
See also
Last modified 5mo ago