Try it free

Filtering

  • Latest Dynatrace
  • Reference
  • 6-min read
  • Published Jul 13, 2026
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

type: 'filtering'

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

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). Two fields are exceptions: inlineMetricFilter: true routes the filter expression to a $(inlineMetricFilter) placeholder you must place in the query; 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.

items

LayoutElement[] (optional)

Elements wrapped by this filtering context — their queries can incorporate the active filter state.

disabled

boolean (optional)

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[]

Field ID(s) this filter operates on.

semDictKey

string (optional)

Semantic dictionary or custom-known-fields key, used to connect this filter to matching table columns and properties.

groupTitle

string (optional)

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

defaultFilter

boolean (optional, default false)

Treats free-typed text as a valid filter value without requiring a suggestion match.

quickFilter

boolean (optional, default false)

Also shows this filter as a facet.

quickFilterExpanded

boolean (optional, default true)

Whether the quick filter starts expanded (and its data loaded).

quickFilterVisible

boolean (optional, default true)

Whether the quick filter is visible by default.

inlineMetricFilter

boolean (optional, default false)

Places this filter's DQL expression at a $(inlineMetricFilter) placeholder in the query instead of the standard filter clause.

maskValueInTracking

boolean (optional, default false)

Masks the filter value in analytics tracking.

allowedOperators

FilterFieldComparisonOperators[] (optional)

Restricts which comparison operators are offered for this filter.

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

query

string (optional)

DQL query pattern for evaluating the filter. Use $(value) for the typed value and $(key) for the field name. When omitted, the filter auto-generates a standard | filter clause from fieldIds.

operatorSpecificQuery

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

Per-operator DQL overrides; takes precedence over query for the listed operators. Use when different operators need structurally different DQL (for example, exists uses a field-existence check while equals uses an exact match). Keys are DqlTextFilterOperator values.

quickFilterSearch

boolean (optional)

Adds an extra search field to the quick filter.

dynamicSuggestions

DqlFilterDynamicSuggestion (optional)

DQL-driven suggestion list.

staticSuggestions

DqlFilterPredefinedValue[] (optional)

Hardcoded suggestion list.

displayCount

boolean (optional)

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

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

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'

How to interpret query results as suggestions.

dql

string (optional)

Query fetching suggestions; must expose a suggestion field (and optionally suggestionCount). Supports a $search placeholder.

suggestionField

string (optional)

Field containing the suggestion value.

suggestionFilter

string (optional)

Overrides the default filter DQL used for suggestions.

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)

Value-to-query mapping, for select-style filters.

countField

number (optional)

Record count value displayed next to the suggestion name.

DqlFilterPredefinedValue

PropertyTypeDescription

text

string

Suggestion label.

value

string (optional)

Value inserted into the filter query.

query

string (optional)

Full filter query for this suggestion.

color

string (optional)

Suggestion color.

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 — 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

Text filter with static suggestions and quick filter

{
  "type": "filtering",
  "id": "host-filters",
  "filters": [
    { "builtInFilter": "ALERT_STATUS_FILTER" },
    {
      "id": "region",
      "type": "text",
      "title": "Region",
      "fieldIds": "region",
      "groupTitle": "Location",
      "quickFilter": true,
      "quickFilterExpanded": true,
      "staticSuggestions": [
        { "text": "EU", "value": "eu" },
        { "text": "US", "value": "us" },
        { "text": "APAC", "value": "apac" }
      ]
    }
  ],
  "items": []
}

Text filter with per-operator DQL

{
  "id": "os-type",
  "type": "text",
  "title": "OS type",
  "fieldIds": "os.type",
  "operatorSpecificQuery": {
    "equals": "| filter os.type == $(value)",
    "exists": "| filter isNotNull(os.type)"
  },
  "allowedOperators": ["equals", "not-equals", "exists", "not-exists"]
}

Dynamic suggestions from Grail

{
  "id": "technology",
  "type": "text",
  "title": "Technology",
  "fieldIds": "process.technology",
  "quickFilter": true,
  "displayCount": true,
  "dynamicSuggestions": {
    "valueExtractor": "string",
    "dql": "fetch dt.entity.process_group | filter matchesPhrase(technology, \"$search\") | summarize count = count(), by:{suggestion = technology} | sort count desc | limit 20"
  }
}

Numeric filter with unit conversion

{
  "id": "response-time",
  "type": "number",
  "title": "Response time",
  "fieldIds": "duration",
  "units": ["millisecond", "second"],
  "baseUnit": "millisecond",
  "allowedOperators": ["greater-than", "less-than", "greater-or-equal", "less-or-equal"]
}

See also

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