dt-dql-essentials（dt dql 要点）

DQL Essentials Skill

DQL is a pipeline-based query language. Queries chain commands with | to filter, transform, and aggregate data. DQL has unique syntax that differs from SQL — load this skill before writing any DQL query.

Use Cases

DQL Reference Index

Syntax Pitfalls

Fetch Command → Data Model

Each data model has a specific fetch command — using the wrong one returns no results.

Legacy compatibility: dt.entity.* still works in older queries, but it is deprecated. Use dt.smartscape.* and smartscapeNodes for all new queries.

Metric-key note: keys containing hyphens are parsed as subtraction. Use backticks, for example: ` timeseries sum(my.metric-name) `.

→ Full field namespace reference: references/semantic-dictionary.md

Data Objects

DQL queries start with fetch <data_object> or timeseries. There is no fetch dt.metric or fetch dt.metrics — metrics are queried with timeseries.

Core data objects for fetch:

Metrics — use timeseries, not fetch:

timeseries cpu = avg(dt.host.cpu.usage), by: {dt.smartscape.host}

Topology — use smartscapeNodes, not fetch:

smartscapeNodes "HOST"

Discover available data objects:

fetch dt.system.data_objects | fields name, display_name, type

Metric Discovery

To search for available metrics by keyword, use metric.series:

fetch metric.series, from: now() - 1h
| filter contains(metric.key, "replay")
| summarize count(), by: {metric.key}
| sort `count()` desc

There is no fetch dt.metric or fetch dt.metrics — those data objects do not exist.

Entity Field Patterns

Entity fields in DQL are scoped to specific entity types — not universal like SQL columns.

• entity.id does not exist — use a typed field such as dt.smartscape.host.

• For topology traversal and relationships, use smartscapeNodes instead of fetch.

Smartscape Entity Patterns

Use smartscapeNodes for topology queries. Node types are uppercase strings and differ from field names.

Use toSmartscapeId() for ID conversion from strings (required!).

→ references/smartscape-topology-navigation.md

matchesValue() Usage

Use matchesValue() for array fields such as dt.tags:

| filter matchesValue(dt.tags, "env:production")

• Not for string fields with special characters — use contains() for those
• matchesValue() on a scalar string field does not behave like a wildcard or fuzzy match

Chained Lookup Pattern

Each lookup command removes all existing fields starting with lookup. before adding new ones. When chaining multiple lookups, use fieldsRename after each to preserve the result:

fetch bizevents
// Step 1: First lookup — enrich orders with product info
| lookup [fetch bizevents
    | filter event.type == "product_catalog"
    | fields product_id, category],
  sourceField: product_id, lookupField: product_id

// Step 2: Rename BEFORE next lookup — or lookup.category gets wiped
| fieldsRename product_category = lookup.category

// Step 3: Second lookup — lookup.* is now clean for new results
| lookup [fetch bizevents
    | filter event.type == "warehouse_stock"
    | fields category, warehouse_region],
  sourceField: product_category, lookupField: category

// Both product_category and lookup.warehouse_region are available

Without the fieldsRename, the second lookup silently drops the first lookup's results — producing empty fields and collapsed aggregations.

makeTimeseries Command

makeTimeseries converts event-based data (logs, spans, bizevents) into a time-bucketed metric series. It is not the same as the timeseries command — timeseries queries pre-ingested metric data; makeTimeseries builds a series from signals in a pipeline.

Basic syntax:

fetch logs
| makeTimeseries count = count(), by: {loglevel}, interval: 5m

Key parameters:

→ Full formal parameter specification: references/dql/dql-commands.md

Example — error rate timeseries from logs:

fetch logs
| makeTimeseries
    total = count(),
    errors = countIf(loglevel == "ERROR"),
    interval: 5m,
    by: {k8s.cluster.name}
| fieldsAdd error_rate = errors / total * 100

Example — entity existence timeline using spread::

smartscapeNodes "HOST"
| makeTimeseries concurrently_existing_hosts = count(), spread: lifetime

spread: lifetime distributes each host's count across the timeframe it existed, producing a series that shows how many hosts were alive at any point in time.

→ references/iterative-expressions.md for timeseries array manipulation

Timeframe Specification

Access to data requires specification of a timeframe. It can be specified in the UI, as REST API parameters, or in a DQL query explicitly using a pair of parameters: from: and to: (if one is omitted it defaults to now()), or alternatively using a single timeframe: parameter. Timeframe can be expressed using absolute values or relative expressions vs. current time. The time alignment operator (@) can be used to round timestamps to time unit boundaries — see references/operators.md for full details.

Examples

from:now()-1h@h, to:now()@h     // last complete hour

from:now()-1d@d, to:now()@d     // yesterday complete

from:now()@M                    // this month so far, till now

from:now()-2h@h                 // go back 2 hours, then align to hour boundary

Absolute timestamps

Use ISO 8601 format:

from:"2024-01-15T08:00:00Z", to:"2024-01-15T09:00:00Z"

Modifying Time

Key concepts

• DQL has 3 specialized types related to time:

- timestamp — internally kept as number of nanoseconds since epoch, but exposed as date/time in a particular timezone - timeframe — a pair of 2 timestamps (start and end) - duration — internally kept as number of nanoseconds, but exposed as duration scaled to a reasonable factor (e.g. ms, minutes, days)

Rules

• Subtracting timestamps yields a duration: timestamp - timestamp → duration
• Duration divided by duration yields a double: e.g. 2h / 1m = 120.0
• Scalar times duration yields a duration: e.g. no_of_h * 1h → duration
• For extraction of time elements (hours, days of month, etc):

- ✅ Use time functions. They support calendar and time zones properly including DST. - ❌ Avoid using formatTimestamp for extracting time components. - ❌ Avoid converting timestamps and durations to double/long and using division, modulo, and constants expressing time units as nanoseconds.

References

• references/useful-expressions.md — Useful expressions in DQL
• references/semantic-dictionary.md — Dynatrace Semantic Dictionary: field namespaces, data models, stability levels, query patterns, and best practices
• references/summarization.md — Various applications of summarize and makeTimeseries commands
• references/operators.md — Operators: in comparison and @ time alignment
• references/iterative-expressions.md — Array and timeseries manipulation (creation, modifications, use in filters) using DQL
• references/smartscape-topology-navigation.md — Smartscape topology navigation syntax and patterns
• references/optimization.md — DQL query optimization: filter placement, time ranges, field selection, and performance best practices
• references/dql/ — Formal DQL 1.0 specification: commands, functions, data types, and parameter types