StackState Query Language (STQL)
StackState Self-hosted v5.1.x
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.
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.
# Return all components named DLL_DB or J2EE_04 regardless of type:
name = DLL_DB OR name = J2EE_04
# Return only databases named DLL_DB and host systems named J2EE_04:
(name = DLL_DB AND type = database) OR (name = J2EE_04 AND type = "host systems")
You can use
*as a full wildcard in a component filter. It isn't possible to filter for partial matches using a wildcard character.
# Select all components
name = "*"
# Select all components with name "serviceB"
name = "serviceB"
# Select all components in the "application" layer:
layer = "application"
# Select all components named either "appA" or "appB" that don't have a label "bck"
name IN ("appA","appB") NOT label = "bck"
# Select all components named "appA" that don't have a label "bck" or "test"
name = "appA" NOT label in ("bck", "test")
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
ORoperator. When an advanced filter includes a function
withNeighborsOfthat's compatible with basic filtering, the number of components whose neighbors are queried for is shown in the Other filters box.
The example below will return all components in the application layer that have a health state of either
CRITICAL. Components with names "appA" or "appB" and their neighbors will also be included.
layer = "application"
AND (healthstate = "CRITICAL" OR healthstate = "DEVIATING")
OR withNeighborsOf(components = (name in ("appA","appB")))
withCauseOffunction has been deprecated. This functionality has been replaced by the Root Cause Analysis section in the visualizer. The construct will be parsed, but won't produce any additional components.
You can switch between basic and advanced filtering by selecting Basic or Advanced under Filter Topology in the View Filters panel.
It's 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's also possible to switch from Advanced to Basic filtering, however, some advanced queries aren't compatible with basic filters.
- Basic filters can't contain an inequality.
- Basic filters don't use
=, rather they're formatted using the
INoperator. For example
name IN ("DLL_DB”)and not
name = "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're 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 isn't compatible, StackState will let you know and ask for confirmation to continue as you will lose some set filters. Alternatively, you can choose to stay in advanced filtering.