Try it free

Filtering

  • Latest Dynatrace
  • Reference
  • 6-min read
  • Published Jul 13, 2026

A filter bar of text, numeric, or predefined-value filters, optionally wrapping other elements so their queries respond to the active filter selection.

Filter bar with text and facet filters applied to a DQL table in an Entity details page
Filter bar with text and facet filters applied to a DQL table in an Entity details page

How a filter reaches the query: By default, a filter with only fieldIds set auto-appends a | filter <field> <operator> <value> clause to each wrapped element's query. No placeholder needed. Set a custom query or operatorSpecificQuery only when the auto-generated clause cannot express the logic (subqueries, joins, key-value lookups). One field is an exception: enableGeneralSearchFilter: true resolves to a $(generalSearchPipe) placeholder you must place before the fields pipe.

Fields

In addition to the shared CoreElement fields (see Elements overview):

PropertyTypeDescription

filters

(DqlFilter | BuiltInFilter)[]

The filters to render. Mix custom filters with built-in references.

disabled

boolean (optional, default false)

Disables the filter field, facets, and segments.

dqlQueryContext

DqlQueryContext (optional)

Enables dependent filtering, where one filter's suggestions depend on another's selection.

enableGeneralSearchFilter

boolean (optional, default false)

Enables a free-text search filter (* ~). Requires the main query to include a $(generalSearchPipe) placeholder before the fields pipe.

DqlFilter is a union of DqlTextFilter and DqlNumericFilter, both extending DqlFilterBase.

Quick filter accordion showing facet values for narrowing the data in view
Quick filter accordion showing facet values for narrowing the data in view

DqlFilterBase (shared fields)

PropertyTypeDescription

id

string

Unique filter ID.

title

string

Filter label.

fieldIds

string | string[]

The DQL field(s) this filter targets. Provide a single string for most filters. Provide an array for text filters that depend on multiple fields simultaneously; only the first entry is used for auto-generated DQL expressions and client-side row matching. For numeric filters, only the first entry is ever used.

semDictKey

string (optional)

Semantic Dictionary key for this filter. Strongly recommended. When provided, it serves as the filter's stable serialization key in bookmarks and URL state: renaming title will not break saved links. When omitted, title is used as the key, so any title change silently breaks existing bookmarks.

groupTitle

string (optional)

Group label in the quick filter accordion. Resolved automatically when semDictKey is set.

defaultFilter

boolean (optional, default false)

When true, text you type is suggested as a filter value. For example, after typing "abc", you see a suggested filter expression under a "Filters based on suggestion" section.

quickFilter

boolean (optional, default false)

Also shows this filter as a facet.

quickFilterExpanded

boolean (optional, default false)

If true, the quick filter accordion group is expanded (and data is loaded) by default. Your choice is persisted in local storage.

quickFilterVisible

boolean (optional, default true)

If false, you must open the Visibility settings modal to show this filter. Use false to de-clutter the sidebar for less frequently used filters while still keeping them accessible. Your choice is persisted in local storage.

allowedOperators

FilterFieldComparisonOperators[] (optional)

Overrides the comparison operators shown for this filter. When omitted, defaults are determined by filter type: numeric filters default to equals, not-equals, less-than, less-or-equal, greater-than, greater-or-equal, exists, not-exists; text filters with $operation(field) in query support all operators; text filters with a function query are limited to equals, exists, not-exists.

conditions

Condition[] (optional)

See Conditional rendering.

Filter input showing DQL-driven autocomplete suggestions for a text filter
Filter input showing DQL-driven autocomplete suggestions for a text filter

DqlTextFilter (type: 'text', default)

PropertyTypeDescription

type

'text' (optional)

Filter discriminator. Omit for text filters (default); set 'number' to use the numeric filter variant.

query

string (optional)

DQL filter expression fragment applied when you select a value. This is a partial DQL expression placed inside a filter pipe — not a full query. Placeholders: $(operation)(field) expands to the appropriate DQL operation based on the selected comparison operator (supporting equals, contains, startsWith, etc.); $(value) is replaced with the selected filter value; $(key) is replaced with the key when using key-value suggestions. When omitted, UA auto-generates the expression from fieldIds.

operatorSpecificQuery

Partial<Record<DqlTextFilterOperator, string>> (optional)

Per-operator DQL query overrides. Use when different operators require structurally different DQL expressions that can't be captured by a single $operation(field) pattern. Each key adds that operator and its negation (not-<key>) to the available operator list. Valid keys: 'exists', 'contains', 'starts-with', 'ends-with'. The main query handles equals, not-equals, in, not in.

quickFilterSearch

boolean (optional)

Shows a search field above the suggestion list, allowing you to search within available filter values. Only applies to quick filters (requires quickFilter: true).

dynamicSuggestions

DqlFilterDynamicSuggestion (optional)

DQL-driven suggestion list.

staticSuggestions

DqlFilterPredefinedValue[] (optional)

Static value suggestions shown in the filter dropdown. Use when the possible values are known at configuration time.

displayCount

boolean (optional)

Shows a matching-record count next to each suggestion (requires a query on static suggestions, or suggestionField on dynamic ones).

countMode

'exact' | 'approx' (optional, default 'exact')

Controls which DQL aggregation function is used for suggestion counts. 'exact' uses countDistinctExact (precise but fails above 1 million rows); 'approx' uses countDistinctApprox (no row limit). Only relevant when displayCount is true.

DqlTextFilterOperator: 'exists' | 'equals' | 'contains' | 'starts-with' | 'ends-with'

DqlTextFilterOperator is the set of operators valid as operatorSpecificQuery keys (text filters only). FilterFieldComparisonOperators (see below) is the larger set governing allowedOperators. Use it to restrict which operators are shown to users across both text and numeric filters.

DqlNumericFilter (type: 'number')

PropertyTypeDescription

type

'number'

Required discriminator. Must be set to 'number' to select the numeric filter variant.

units

string[] (optional)

Unit options shown in the filter UI (for example, ['millisecond', 'second', 'minute', 'hour', 'day']). When omitted, the filter is dimensionless (for example, a plain count).

baseUnit

string (optional)

The base unit matching the raw query values. Must be set when units is provided — user-entered values are converted from the selected unit to this base before filtering (for example, 'millisecond' if the query stores durations in ms).

Choosing a suggestion source

MechanismWhen to use

staticSuggestions

Fixed hardcoded list; values never change at runtime.

dynamicSuggestions.mapping

Fixed display→query mapping (select-style); no Grail query, values known at authoring time.

dynamicSuggestions.dql

Values fetched live from Grail; list adapts to current data and supports a $(search) placeholder for user-typed filtering.

DqlFilterDynamicSuggestion

PropertyTypeDescription

valueExtractor

'string' | 'key-value'

'string': each result row has a single suggestion string field — use for simple scalar values like status codes or environment names. 'key-value': each row is a record of key/value pairs — suggestions appear as key:value, for tag-style or property-style filters where both are meaningful to you.

dql

string (optional)

Fully custom DQL query to fetch suggestions. Must expose a suggestion field (and optionally suggestionCount). Supports a $(search) placeholder for your current search input. Use dql when you need a standalone suggestion query independent of dqlQueryContext. For suggestions derived from the main query, use suggestionField instead.

suggestionField

string (optional)

The field name in the main dqlQueryContext query that contains suggestion values. When set, UA auto-generates the suggestion query from the main DQL context by appending a summarize command — no separate dql query needed. Recommended for most filters.

suggestionFilter

string (optional)

Overrides the DQL filter expression used when building the suggestion query. By default, the current filter's active value is applied. Only relevant when suggestionField is set. Supports $(search) as a placeholder.

valueFormatter

'upper-camel-case' | 'lower-camel-case' | 'upper-snake-case' | 'snake-case' | 'sentence-case' (optional)

Formats suggestion labels only — does not affect displayed cell or column values. To format column values use a cell renderer on the wrapping DQL Table.

mapping

DqlFilterPredefinedValue[] (optional, default [])

Maps raw DQL suggestion values to human-readable display labels shown in the dropdown. When a value matches an entry's value, the entry's text is displayed instead. For select-style filters where the values are known at authoring time.

requiredFields

string[] (optional)

Underlying DQL fields to include in the timeseries by:{} clause when suggestionField is a virtual or computed field (for example, produced by an additionalCommands pipe). When omitted, [suggestionField] is used by default.

DqlFilterPredefinedValue

PropertyTypeDescription

text

string

Suggestion label.

value

string (optional)

Value inserted into the filter query.

query

string (optional)

Full filter query for this suggestion.

BuiltInFilter

{ "builtInFilter": "ALERT_STATUS_FILTER" }
LiteralDescription

'ALERT_STATUS_FILTER'

Filters by alert status (critical / no alerts).

'ALERT_STATUS_WITH_WARNINGS_FILTER'

Same, including warnings.

DqlQueryContext

Used in dqlQueryContext to support dependent filtering.

PropertyTypeDescription

query

string

Base query providing values for the main dimensions.

lookups

DqlLookup[] (optional)

Additional joined queries.

additionalCommands

DqlAdditionalCommand[] (optional)

Derived-field commands.

DqlLookup (query, sourceField, lookupField, fields) and DqlAdditionalCommand (dependencies, fields, query) mirror the shapes used for DQL table's query context. For details, see DQL table.

FilterFieldComparisonOperators

Full operator set available via allowedOperators: 'equals', 'not-equals', 'less-than', 'less-or-equal', 'greater-than', 'greater-or-equal', 'exists', 'not-exists', 'in', 'not in', 'starts-with', 'ends-with', 'contains', 'not-starts-with', 'not-ends-with', 'not-contains', 'matches-phrase', 'not-matches-phrase', 'search'.

Examples

Minimal text filter

UA auto-generates the DQL expression from fieldIds. No suggestions or custom query are necessary. You see the full set of text operators (equals, not-equals, in, not-in, exists, not-exists, starts-with, contains, and their negations) in the operator dropdown.

{
  "type": "filtering",
  "id": "example-minimal-text",
  "filters": [
    {
      "id": "name-filter",
      "title": "Name",
      "fieldIds": "name"
    }
  ],
  "dqlQueryContext": {
    "query": "smartscapeNodes \"HOST\" | fields id, name"
  }
}
Minimal filtering element with a single text filter applied
Minimal filtering element with a single text filter applied

Static suggestions

Use when the possible values are known at configuration time. Suggestions appear in the dropdown immediately without a DQL query.

{
  "type": "filtering",
  "id": "example-static",
  "filters": [
    {
      "id": "os-type-filter",
      "title": "Operating system",
      "fieldIds": "os.type",
      "quickFilter": true,
      "quickFilterExpanded": true,
      "staticSuggestions": [
        { "text": "Linux", "value": "OS_TYPE_LINUX" },
        { "text": "Windows", "value": "OS_TYPE_WINDOWS" },
        { "text": "AIX", "value": "OS_TYPE_AIX" },
        { "text": "macOS", "value": "OS_TYPE_DARWIN" }
      ]
    }
  ],
  "dqlQueryContext": {
    "query": "smartscapeNodes \"HOST\" | fields id, name, os.type"
  }
}
Filter dropdown showing static suggestion values for Operating system
Filter dropdown showing static suggestion values for Operating system

Static suggestions with custom query

The query field on a suggestion overrides the auto-generated DQL filter expression for that specific value. Use it when the natural query for a suggestion is more complex than a simple equality check (for example, "Physical host" means no hypervisor is present, which cannot be expressed as a value match). When query is set, value is optional.

{
  "type": "filtering",
  "id": "example-static-query",
  "filters": [
    {
      "id": "hypervisor-filter",
      "title": "Hypervisor",
      "fieldIds": "hypervisor.type",
      "quickFilter": true,
      "quickFilterExpanded": true,
      "staticSuggestions": [
        { "text": "Physical host", "query": "isNull(hypervisor.type)" },
        { "text": "VMware", "value": "VMWARE" },
        { "text": "Microsoft Hyper-V", "value": "HYPERV" },
        { "text": "Xen", "value": "XEN" }
      ]
    }
  ],
  "dqlQueryContext": {
    "query": "smartscapeNodes \"HOST\" | fields id, name, hypervisor.type"
  }
}
Filter with static suggestions using a custom DQL query for the Physical host option
Filter with static suggestions using a custom DQL query for the Physical host option

Dynamic suggestions from query context

Use suggestionField to derive suggestions from the same DQL query that drives the table. No separate dql query needed. UA appends a summarize command automatically. The Filtering element must have dqlQueryContext set so UA knows which query to use.

{
  "type": "filtering",
  "id": "example-dynamic-context",
  "filters": [
    {
      "id": "host-name-filter",
      "title": "Host name",
      "fieldIds": "name",
      "quickFilter": true,
      "quickFilterExpanded": true,
      "dynamicSuggestions": {
        "valueExtractor": "string",
        "suggestionField": "name"
      }
    }
  ],
  "dqlQueryContext": {
    "query": "smartscapeNodes \"HOST\" | fields id, name"
  }
}
Filter suggestions populated dynamically from the main query context using suggestionField
Filter suggestions populated dynamically from the main query context using suggestionField

Custom DQL suggestion query

The dql field runs an independent query to populate the suggestion dropdown. Use when suggestions come from a separate query rather than the main table query. The query must produce a suggestion field (for 'string' extractor) or key/value fields (for 'key-value' extractor).

{
  "type": "filtering",
  "id": "example-custom-dql",
  "filters": [
    {
      "id": "host-group-filter",
      "title": "Host group",
      "fieldIds": "dt.host_group.id",
      "quickFilter": true,
      "quickFilterExpanded": true,
      "dynamicSuggestions": {
        "valueExtractor": "string",
        "dql": "smartscapeNodes \"HOST\"\n| summarize suggestion = collectDistinct(dt.host_group.id)\n| expand suggestion\n| filter isNotNull(suggestion)"
      }
    }
  ],
  "dqlQueryContext": {
    "query": "smartscapeNodes \"HOST\" | fields id, name, dt.host_group.id"
  }
}
Filter using a standalone DQL query to populate host group suggestions
Filter using a standalone DQL query to populate host group suggestions

Mapped display labels

Raw DQL enum values like 'OS_TYPE_LINUX' are remapped to human-readable labels in the dropdown. The filter query still uses the original value (for example, os.type == "OS_TYPE_LINUX"), but you see Linux in the UI.

{
  "type": "filtering",
  "id": "example-mapped",
  "filters": [
    {
      "id": "os-type-filter",
      "title": "Operating system",
      "fieldIds": "os.type",
      "quickFilter": true,
      "quickFilterExpanded": true,
      "dynamicSuggestions": {
        "valueExtractor": "string",
        "suggestionField": "os.type",
        "mapping": [
          { "value": "OS_TYPE_LINUX", "text": "Linux" },
          { "value": "OS_TYPE_WINDOWS", "text": "Windows" },
          { "value": "OS_TYPE_AIX", "text": "AIX" },
          { "value": "OS_TYPE_DARWIN", "text": "macOS" }
        ]
      }
    }
  ],
  "dqlQueryContext": {
    "query": "smartscapeNodes \"HOST\" | fields id, name, os.type"
  }
}
Filter suggestions showing human-readable labels mapped from raw DQL enum values
Filter suggestions showing human-readable labels mapped from raw DQL enum values

Suggestion count

displayCount: true adds a count badge to each suggestion in the dropdown. The count query runs in parallel with the suggestion query. countMode controls whether counts are computed from the full query or just the suggestion field.

{
  "type": "filtering",
  "id": "example-count",
  "filters": [
    {
      "id": "cloud-provider-filter",
      "title": "Cloud provider",
      "fieldIds": "cloud.provider",
      "displayCount": true,
      "quickFilter": true,
      "quickFilterExpanded": true,
      "dynamicSuggestions": {
        "valueExtractor": "string",
        "suggestionField": "cloud.provider"
      }
    }
  ],
  "dqlQueryContext": {
    "query": "smartscapeNodes \"HOST\" | fields id, name, cloud.provider"
  }
}
Filter suggestion dropdown with count badges showing the number of matching entities
Filter suggestion dropdown with count badges showing the number of matching entities

All operators with $(operation) placeholder

$(operation)(field) expands to the DQL expression for whichever operator you select (for example, matchesValue(name, "$(value)") for equals, contains(name, "$(value)") for contains). This lets one query pattern cover all operators without writing operatorSpecificQuery entries.

{
  "type": "filtering",
  "id": "example-all-operators",
  "filters": [
    {
      "id": "name-filter",
      "title": "Host name",
      "fieldIds": "name",
      "query": "$(operation)(name)",
      "quickFilter": true,
      "quickFilterExpanded": true,
      "dynamicSuggestions": {
        "valueExtractor": "string",
        "suggestionField": "name"
      }
    }
  ],
  "dqlQueryContext": {
    "query": "smartscapeNodes \"HOST\" | fields id, name"
  }
}
Filter bar showing multiple comparison operators enabled via the $(operation) placeholder
Filter bar showing multiple comparison operators enabled via the $(operation) placeholder

Numeric filter

units lists the units shown in the unit selector dropdown. baseUnit is the unit all user-entered values are converted to before the DQL expression is generated. Both fields are required together. Default numeric operators:

  • equals
  • not-equals
  • less-than
  • less-or-equal
  • greater-than
  • greater-or-equal
  • exists
  • not-exists
{
  "type": "filtering",
  "id": "example-numeric",
  "filters": [
    {
      "type": "number",
      "id": "memory-filter",
      "title": "Memory",
      "fieldIds": "memory",
      "quickFilter": true,
      "quickFilterExpanded": true,
      "units": ["information.megabyte", "information.gigabyte"],
      "baseUnit": "information.byte"
    }
  ],
  "dqlQueryContext": {
    "query": "smartscapeNodes \"HOST\" | fields id, name, memory"
  }
}
Numeric filter with unit selector showing memory filter options
Numeric filter with unit selector showing memory filter options

Key-value filter

valueExtractor: 'key-value' expects the field to be a Record<string, string> where each entry becomes a key:value suggestion (for example, team:platform). The auto-generated filter expression uses record indexing: tags[`$(key)`] == "$(value)". This is the natural format for smartscapeNodes entity tags.

{
  "type": "filtering",
  "id": "example-key-value",
  "filters": [
    {
      "id": "tag-filter",
      "title": "Tag",
      "fieldIds": "tags",
      "quickFilter": true,
      "quickFilterExpanded": true,
      "dynamicSuggestions": {
        "valueExtractor": "key-value",
        "suggestionField": "tags"
      }
    }
  ],
  "dqlQueryContext": {
    "query": "smartscapeNodes \"HOST\" | fields id, name, tags"
  }
}
Key-value filter showing tag suggestions in key:value format
Key-value filter showing tag suggestions in key:value format

Inventory Explorer filtering

Inventory Explorer documents configure filtering directly on the type definition via the filtering field. Unlike standalone Filtering elements used inside layouts, Inventory Explorer filtering is always supported and does not need to be registered separately.

{
  "type": "filtering",
  "id": "host-filtering",
  "filters": [
    {
      "id": "host-name",
      "title": "Host name",
      "fieldIds": "name",
      "query": "$(operation)(name)",
      "quickFilter": true,
      "quickFilterExpanded": true,
      "dynamicSuggestions": {
        "valueExtractor": "string",
        "suggestionField": "name"
      }
    },
    {
      "id": "os-type",
      "title": "Operating system",
      "fieldIds": "os.type",
      "quickFilter": true,
      "quickFilterExpanded": true,
      "staticSuggestions": [
        { "text": "Linux", "value": "OS_TYPE_LINUX" },
        { "text": "Windows", "value": "OS_TYPE_WINDOWS" },
        { "text": "AIX", "value": "OS_TYPE_AIX" }
      ]
    }
  ],
  "dqlQueryContext": {
    "query": "smartscapeNodes \"HOST\" | fields id, name, os.type"
  }
}
Inventory Explorer filtering configuration with name and OS type filters applied
Inventory Explorer filtering configuration with name and OS type filters applied

See also

  • DQL table
  • DQL variables
  • Elements overview
Related tags
ExtensionsExtensionsInfrastructure Observability