Settings API - UA DQL filtering schema table

Published Sep 25, 2025

UA DQL filtering (`builtin:ua.dql-filtering)`

Configure DQL filtering.

Schema ID	Schema groups	Scope
`builtin:ua.dql-filtering`	`group:unified-analysis`	`ua-explorer`

Retrieve schema via Settings API

GET	Managed	`https://{your-domain}/e/{your-environment-id}/api/v2/settings/schemas/builtin:ua.dql-filtering`
	SaaS	`https://{your-environment-id}.live.dynatrace.com/api/v2/settings/schemas/builtin:ua.dql-filtering`
	Environment ActiveGate	`https://{your-activegate-domain}/e/{your-environment-id}/api/v2/settings/schemas/builtin:ua.dql-filtering`

Authentication

To execute this request, you need an access token with Read settings (settings.read) scope. To learn how to obtain and use it, see Tokens and authentication.

Parameters

Property	Type	Description	Required
Key `key`	text	Filtering key used that can be referenced in Inventory Explorer types config.	Required
Filters `filters`	FilterDefinition[]	List of filters.	Required

The `FilterDefinition` object

Property	Type	Description	Required
Filter label `label`	text	Name of the filter which is shown in the UI.	Required
Query `query`	text	DQL fragment that should be inserted after "filter" command. Following variables are available in this field: $value (from value suggestion), $key (optionally from key-value suggestions) and $field (field-reference).	Required
Field `field`	text	Reference to a field from main query or lookup, the field that should be filtered.	Required
Default filter `defaultFilter`	boolean	Specifies if a the filter is suggested as complete statement, when typing values into the filter field without selecting a key first.	Required
Distinct filter `distinctFilter`	boolean	Specifies if the filter is suggested again, once selected	Required
Field IDs `valueSuggestion`	ValueSuggestion	Datasource of autosuggestion.	Required

The `ValueSuggestion` object

Property	Type	Description	Required
`type`	enum	The element has these enums `STATIC` `DYNAMIC`	Required
Value extractor `valueExtractor`	text	Required for filter where value needs to be extracted from a field. It is also needed if other fields than $value is required (like $key)	Optional
Value formatter `valueFormatter`	text	When the suggestion doesn't provide a display name, a formatter can be used to produce a name based on value.	Optional
Predefined filter values `values`	PredefinedFilterValue[]	If the suggestion doesn't provide display name and name can be produced based on value	Required

The `PredefinedFilterValue` object

Property	Type	Description	Required
Text `text`	text	Required for filter where value needs to be extracted from a field, it is also needed if other fields than $value is required (like $key).	Required
Value `value`	text	Value that should be included in main query - Eq. "DE", to fit into "country == $value" query.	Optional
Query `query`	text	Query for each value, if specified it overrides the main query. Eg. "problems > 0".	Optional