Try it free

DQL variables

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

Any DQL query you write inside a document — a table's dqlQuery, a chart's dqlQuery, a filter's suggestion query, a condition-context query, and so on — can contain variables: placeholders that UA replaces with runtime values before the query runs. This lets one document adapt to whichever entity, timeframe, row, or filter selection the user is looking at.

The syntax is $(<VARIABLE_KEY>), for example,

smartscapeNodes "HOST" | filter id == toSmartscapeId($(nodeId))

At runtime $(nodeId) is replaced with the current entity's node ID, so the query fetches exactly the host the user opened.

Most variables come already quoted where a DQL string literal is expected. Variants prefixed with unquoted give the raw value for cases where you supply the quotes yourself.

Entity context

Available in Entity Details and in any card bound to a single entity.

VariableDescriptionExample

$(entityId)

Effective entity ID — the Smartscape node ID when present, otherwise the classic entity (ME) ID.

timeseries avg(dt.host.cpu.usage), by:{dt.entity.host}, filter: dt.entity.host == $(entityId)

$(nodeId)

Smartscape node ID of the current entity.

smartscapeNodes "HOST" | filter id == toSmartscapeId($(nodeId))

$(meId)

Classic entity (ME) ID only — use when a query must use the classic ID even though a node ID is available.

fetch logs | filter affected_entity_ids == $(meId)

$(unquotedEntityId)

Same as $(entityId) but without surrounding quotes.

... == "$(unquotedEntityId)"

Timeframe

Available everywhere. The current timeframe follows the app's timeframe selector.

VariableDescriptionExample

$(startTimestamp)

Start of the current timeframe.

fetch events, from: $(startTimestamp), to: $(endTimestamp)

$(endTimestamp)

End of the current timeframe.

fetch events, from: $(startTimestamp), to: $(endTimestamp)

$(tfRecentMe)

Preset timeframe for recent last-value entity data.

smartscapeNodes "HOST", from: $(tfRecentMe)

$(tfRecentAggr)

Preset timeframe for data that must be aggregated over an interval.

timeseries used = sum(dt.host.disk.used.bytes), from: $(tfRecentAggr)

$(tfRecentTs)

Preset timeframe for recent timeseries data.

timeseries cpu = avg(dt.host.cpu.usage), from: $(tfRecentTs)

$(tfDavis)

Preset timeframe (6 h 10 min) for Davis events.

fetch events, from: $(tfDavis) | filter event.kind == "DAVIS_PROBLEM"

Chart Group

Available in a chart's dqlQuery when the corresponding selector is configured on the chart.

VariableDescriptionExample

$(aggregation)

Currently selected chart aggregation.

timeseries $(aggregation)(dt.host.cpu.usage), by:{dt.entity.host}

$(aggregation_gauge)

Currently selected gauge aggregation.

timeseries $(aggregation_gauge)(dt.host.mem.used.percent), by:{dt.entity.host}

$(rollup)

Currently selected rollup.

timeseries avg(dt.host.net.nic.bytes_rx$(rollup)), by:{dt.entity.host}

DQL Table rows

Available in a table's expandable-row content. They resolve to data from the row being expanded.

VariableDescriptionExample

$(rowId)

idField value of the current row (quoted).

... | filter dt.entity.service == $(rowId)

$(unquotedRowId)

Same as $(rowId) without quotes.

... == "$(unquotedRowId)"

$(row[<PATH>])

Any row field via bracket notation; supports nested objects and arrays.

$(row[id]), $(row[entity][type]), $(row[tags][0])

Row bracket notation

$(row[<PATH>]) gives full access to the row, including nested objects and arrays. Given a row:

{ "id": "SERVICE-123", "count": 42, "entity": { "type": "SERVICE", "tags": ["production"] } }
  • $(row[id]) → SERVICE-123
  • $(row[count]) → 42 (stringified)
  • $(row[entity][type]) → SERVICE
  • $(row[entity][tags][0]) → production

Filter queries

Available in filter suggestion queries and in DQL Table base queries that participate in filtering.

VariableDescriptionExample

$(search)

The user's current search term, in value-suggestion queries.

... | filter contains(lower(name), lower("$(search)"))

$(value)

The selected filter value.

dt.smartscape.k8s_cluster in [smartscapeNodes "K8S_CLUSTER" | filter k8s.cluster.distribution == "$(value)" | fields id]

$(key)

The filter key (key-value filters only).

k8s.labels[$(key)] == "$(value)"

$(generalSearchPipe)

Replaced with | search "<value>" when the general search filter (* ~) is active, empty otherwise. Place it before the | fields pipe; requires enableGeneralSearchFilter on the filtering element.

fetch logs $(generalSearchPipe) | fields id, content, status

$(inlineMetricFilter)

Comma-prefixed expression of all filters marked inlineMetricFilter (for example, , matchesValue(k8s.cluster.name, "my-cluster")), or empty when none are selected.

timeseries requestCount = sum(dt.service.request.count), by: {dt.smartscape.service}, filter: isNotNull(dt.smartscape.service)$(inlineMetricFilter)

$(prefixedInlineMetricFilter)

Same as above but with , filter: prefixed, so it can stand alone.

timeseries requestCount = sum(dt.service.request.count)$(prefixedInlineMetricFilter)

$(inlineMetricSplitBy)

Comma-separated field IDs for a by: clause (no leading comma).

timeseries c = sum(dt.service.request.count), by: {$(inlineMetricSplitBy)}

$(prefixedInlineMetricSplitBy)

Same as above but with a leading , , so it can follow existing split dimensions.

..., by: {dt.smartscape.service$(prefixedInlineMetricSplitBy)}

Health alert actions

Available in health-alert action payloads and links.

VariableDescriptionExample

$(event[<PATH>])

Health-alert event field via bracket notation; supports nested objects and arrays.

$(event[event.kind]), $(event[entity][id]), $(event[properties][threshold])

DQL Table sampling

VariableDescriptionExample

$(samplingRatio)

Dynamic sampling ratio value for the table's query.

fetch spans, scanLimitGBytes:-1, samplingRatio: $(samplingRatio)

Condition variable limitations

Variables produced by a document's conditionContext are a separate channel used only to decide whether an element is shown. They are not available for $(...) interpolation inside element DQL queries. See Conditional rendering.

App-specific variables

An app hosting UA may define its own custom variables in addition to the built-in ones above. If you see a $(...) placeholder in an app's own examples that isn't listed here, it is likely one of those app-supplied variables rather than a built-in one.

See also

  • DQL Table
  • Chart Group
  • Filtering
  • Conditional rendering
Related tags
ExtensionsExtensionsInfrastructure Observability