Dt Dql Essentials

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.

______________________________________________________________________

When to Load References

Before working on specific tasks, load the relevant reference:

| Task | Required Reading | | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Field names, namespaces, data models, stability levels, query patterns | [references/semantic-dictionary.md](references/semantic-dictionary.md) | | Query optimization (filter early, time ranges, field selection, performance) | [references/optimization.md](references/optimization.md) | | Smartscape topology navigation for discovering relationships between entities | [references/smartscape-topology-navigation.md](references/smartscape-topology-navigation.md) | | summarize and makeTimeseries patterns (bucketing, calendar months) | [references/summarization.md](references/summarization.md) | | Array and timeseries manipulation (arrayFilter, collectArray, iterative) | [references/iterative-expressions.md](references/iterative-expressions.md) | | Conditional logic (if/else chains), coalesce, string/date helpers | [references/useful-expressions.md](references/useful-expressions.md) | | in operator (subquery), full @ time alignment unit table | [references/operators.md](references/operators.md) |

______________________________________________________________________

DQL Reference Index

Use this index to route from a function group (e.g. time functions, conversions) to its detailed spec, or from a function name to its spec file.

| Description | Items | |-------------|-------| | [Data Types](references/dql/dql-data-types.md) | array, binary, boolean, double, duration, long, record, string, timeframe, timestamp, uid | | [Parameter Value Types](references/dql/dql-parameter-value-types.md) | bucket, dataObject, dplPattern, entityAttribute, entitySelector, entityType, enum, executionBlock, expressionTimeseriesAggregation, expressionWithConstantValue, expressionWithFieldAccess, fieldPattern, filePattern, identifierForAnyField, identifierForEdgeType, identifierForFieldOnRootLevel, identifierForNodeType, joinCondition, jsonPath, metricKey, metricTimeseriesAggregation, namelessDplPattern, nonEmptyExecutionBlock, prefix, primitiveValue, simpleIdentifier, tabularFileExisting, tabularFileNew, url | | [Commands](references/dql/dql-commands.md) | append, data, dedup, describe, expand, fetch, fields, fieldsAdd, fieldsFlatten, fieldsKeep, fieldsRemove, fieldsRename, fieldsSnapshot, fieldsSummary, filter, filterOut, join, joinNested, limit, load, lookup, makeTimeseries, metrics, parse, search, smartscapeEdges, smartscapeNodes, sort, summarize, timeseries, traverse | | [Functions — Aggregation](references/dql/dql-functions-aggregation.md) | avg, collectArray, collectDistinct, correlation, count, countDistinct, countDistinctApprox, countDistinctExact, countIf, max, median, min, percentRank, percentile, percentileFromSamples, percentiles, stddev, sum, takeAny, takeFirst, takeLast, takeMax, takeMin, variance | | [Functions — Array](references/dql/dql-functions-array.md) | arrayAvg, arrayConcat, arrayCumulativeSum, arrayDelta, arrayDiff, arrayDistinct, arrayFirst, arrayFlatten, arrayIndexOf, arrayLast, arrayLastIndexOf, arrayMax, arrayMedian, arrayMin, arrayMovingAvg, arrayMovingMax, arrayMovingMin, arrayMovingSum, arrayPercentile, arrayRemoveNulls, arrayReverse, arraySize, arraySlice, arraySort, arraySum, arrayToString, vectorCosineDistance, vectorInnerProductDistance, vectorL1Distance, vectorL2Distance | | [Functions — Bitwise](references/dql/dql-functions-bitwise.md) | bitwiseAnd, bitwiseCountOnes, bitwiseNot, bitwiseOr, bitwiseShiftLeft, bitwiseShiftRight, bitwiseXor | | [Functions — Boolean](references/dql/dql-functions-boolean.md) | exists, in, isFalseOrNull, isNotNull, isNull, isTrueOrNull, isUid128, isUid64, isUuid | | [Functions — Cast](references/dql/dql-functions-cast.md) | asArray, asBinary, asBoolean, asDouble, asDuration, asIp, asLong, asNumber, asRecord, asSmartscapeId, asString, asTimeframe, asTimestamp, asUid | | [Functions — Constant](references/dql/dql-functions-constant.md) | e, pi | | [Functions — Conversion](references/dql/dql-functions-conversion.md) | toArray, toBoolean, toDouble, toDuration, toIp, toLong, toSmartscapeId, toString, toTimeframe, toTimestamp, toUid, toVariant | | [Functions — Create](references/dql/dql-functions-create.md) | array, duration, ip, record, smartscapeId, timeframe, timestamp, timestampFromUnixMillis, timestampFromUnixNanos, timestampFromUnixSeconds, uid128, uid64, uuid | | [Functions — Cryptographic](references/dql/dql-functions-cryptographic.md) | hashCrc32, hashMd5, hashSha1, hashSha256, hashSha512, hashXxHash32, hashXxHash64 | | [Functions — Entities](references/dql/dql-functions-entities.md) | classicEntitySelector, entityAttr, entityName | | [Functions — Time series aggregation for expressions](references/dql/dql-functions-expression-timeseries.md) | avg, count, countDistinct, countDistinctApprox, countDistinctExact, countIf, end, max, median, min, percentRank, percentile, percentileFromSamples, start, sum | | [Functions — Flow](references/dql/dql-functions-flow.md) | coalesce, if | | [Functions — General](references/dql/dql-functions-general.md) | jsonField, jsonPath, lookup, parse, parseAll, type | | [Functions — Get](references/dql/dql-functions-get.md) | arrayElement, getEnd, getHighBits, getLowBits, getStart | | [Functions — Iterative](references/dql/dql-functions-iterative.md) | iAny, iCollectArray, iIndex | | [Functions — Mathematical](references/dql/dql-functions-mathematical.md) | abs, acos, asin, atan, atan2, bin, cbrt, ceil, cos, cosh, degreeToRadian, exp, floor, hexStringToNumber, hypotenuse, log, log10, log1p, numberToHexString, power, radianToDegree, random, range, round, signum, sin, sinh, sqrt, tan, tanh | | [Functions — Network](references/dql/dql-functions-network.md) | ipIn, ipIsLinkLocal, ipIsLoopback, ipIsPrivate, ipIsPublic, ipMask, isIp, isIpV4, isIpV6 | | [Functions — Smartscape](references/dql/dql-functions-smartscape.md) | getNodeField, getNodeName | | [Functions — String](references/dql/dql-functions-string.md) | concat, contains, decodeBase16ToBinary, decodeBase16ToString, decodeBase64ToBinary, decodeBase64ToString, decodeUrl, encodeBase16, encodeBase64, encodeUrl, endsWith, escape, getCharacter, indexOf, lastIndexOf, levenshteinDistance, like, lower, matchesPattern, matchesPhrase, matchesRegex, matchesValue, punctuation, replacePattern, replaceString, splitByPattern, splitString, startsWith, stringLength, substring, trim, unescape, unescapeHtml, upper | | [Functions — Time](references/dql/dql-functions-time.md) | formatTimestamp, getDayOfMonth, getDayOfWeek, getDayOfYear, getHour, getMinute, getMonth, getSecond, getWeekOfYear, getYear, now, unixMillisFromTimestamp, unixNanosFromTimestamp, unixSecondsFromTimestamp | | [Functions — Time series aggregation for metrics](references/dql/dql-functions-timeseries.md) | avg, count, countDistinct, end, max, median, min, percentRank, percentile, start, sum |

______________________________________________________________________

Syntax Pitfalls

| ❌ Wrong | ✅ Right | Issue | | --- | --- | --- | | filter field in ["a", "b"] | filter in(field, {"a", "b"}) | [ and ] wrap sub-queries in DQL but do not wrap static array literals. Use {} or array() for static values. | | filter: { in(field, [sub-query]) } (e.g. in timeseries filter:) | filter: { field in [sub-query] } | in() does not accept execution blocks as arguments. When the right-hand side is a sub-query (execution block), use the in operator: field in [execution block]. | | by: severity, status | by: {severity, status} | List of fields must be grouped by curly braces in by: clauses (summarize, makeTimeseries, etc.). | | contains(toLowercase(field), "err") | contains(field, "err", false) | Don't wrap in lower() for case-insensitive matching. contains() has a built-in third positional caseSensitive parameter (default true). | | filter name == "*serv*9*" | filter matchesValue(name, "*serv*") and matchesValue(name, "*9*") | == does not support wildcards. matchesValue() supports * wildcards but only at the beginning and/or end of the pattern—split mid-string wildcard intent into multiple calls combined with and. | | matchesValue(field, "prod") on string field | contains(field, "prod") | Without wildcards, matchesValue() performs an exact (case-insensitive) match — it will not find "production". Use contains() for substring matching (or matchesValue(field, "*prod*") for wildcard matching). | | toLowercase(field) | lower(field) | The function is lower(), not toLowercase(). Only type-casting functions use the to prefix (toString(), toLong(), etc.). | | arrayAvg(field[]) or arraySum(field[]) | arrayAvg(field) or field[] | field[] = element-wise iterative expression (array→array); arrayAvg(field) = collapse to scalar (array→single value). Never mix both — arrayAvg(field[]) is semantically wrong. | | my_field after lookup or join | lookup.my_field / right.my_field | lookup prefixes added fields with lookup. by default (configurable via prefix:). join prefixes right-side fields with right.. | | substring(field, 0, 200) | substring(field, from: 0, to: 200) | The first parameter (expression) is positional, but from: and to: are named optional parameters and must include their names. | | filter host = "A" | filter host == "A" | DQL uses == for equality comparison, not =. Single = is assignment (e.g., in fieldsAdd, summarize aliases). | | fetch logs, from: toTimestamp('2026-01-01') | fetch logs, from: -24h | from: / to: accept duration literals (e.g., -24h, -7d) or now() expressions — not toTimestamp(). For absolute ranges use timeframe: "start/end" (ISO 8601). | | filter log.level == "ERROR" | filter loglevel == "ERROR" | Log severity field is loglevel (no dot) — log.level does not exist. | | sort count() desc | ` sort count() desc | Fields with special characters (like parentheses) must be wrapped in backticks. | | length(field) | stringLength(field) | DQL string length function is stringLength — there is no length(). | | metrics dt.host.cpu.usage | timeseries avg(dt.host.cpu.usage) | metrics loads metric metadata, not values — use timeseries for data. | | join [...], on:{left.a.b == right.a.b} | join [...], on:{left[a.b] == right[a.b]} | Dotted field names in join/lookup conditions require bracket notation with backticks. | | fieldsSummary (no arguments) | fieldsSummary field1, field2 | fieldsSummary requires at least one field parameter. | | timeseries with percentile/median/percentRank — no results | Add rollup: avg (or min/max/sum) to the timeseries command | These three functions **require rollup:** on gauge/count metrics — without it the query silently returns empty. | | lookup [...], fields: {dotted.name} | lookup [...], fields: {dotted.name} | Do not backtick field names inside the fields: parameter of lookup — causes PARSE_ERROR. | | data record(key: "val") | data record(key = "val") | record() uses = for named fields, not : — : is for command parameters like rollup:. | | getNodeField(dt.smartscape.host, "tags")["tag.key"] | getNodeField(dt.smartscape.host, "tags")[tag.key] | In this tag-map access pattern, bracket keys must use unquoted identifier syntax; quoted keys cause a parse error. | | by: {dt.entity.host} or dt.entity. | by: {dt.smartscape.host} or dt.smartscape. | dt.entity. is **deprecated** — always use dt.smartscape.` in new queries. |

______________________________________________________________________

Fetch Command → Data Model

DQL queries start with fetch or timeseries. There is no fetch dt.metric — metrics use timeseries.

| Fetch Command | Data Model | Key Fields / Notes | |---------------|------------|--------------------| | fetch spans | Distributed tracing | span.*, service.*, http.*, db.*, code.*, exception.* | | fetch logs | Log events | log.*, k8s.*, host.* — message body is content, severity is loglevel (NOT log.level) | | fetch events | DAVIS / infra events | event.*, dt.smartscape.* | | fetch bizevents | Business events | event.*, custom fields | | fetch security.events | Security events | vulnerability.*, event.* | | fetch user.sessions | RUM sessions | dt.rum.*, browser.*, geo.* | | fetch user.events | RUM individual events | page views, clicks, requests, errors | | fetch user.replays | Session replay recordings | | | fetch application.snapshots | Application snapshots | | | fetch dt.davis.events | Davis-detected events | | | fetch dt.davis.problems | Davis-detected problems | | | timeseries avg(metric.key) | Metrics | NOT fetch — hyphenated keys need backticks: ` timeseries sum(my.metric-name) | | smartscapeNodes "HOST" | Topology | NOT fetch — types: HOST, SERVICE, K8S_CLUSTER`, etc. |

dt.entity.* is deprecated — use dt.smartscape.* and smartscapeNodes for new queries.

Discover all available data objects: fetch dt.system.data_objects | fields name, display_name, type

→ [references/semantic-dictionary.md](references/semantic-dictionary.md) for full field namespaces

______________________________________________________________________

samplingRatio Parameter

fetch supports a samplingRatio: parameter to reduce the volume of data read — useful for improving query performance on large datasets.

fetch spans, samplingRatio:100   // reads ~1% of data

Allowed values: depend on the concrete data object and range from 1, 10, 100, 1000, 10000 to 100000, the highest level only available for logs and spans.

Sampling is hierarchical for spans, user.events and user.sessions: a record included at a higher ratio (e.g. 100) is guaranteed to also appear at lower ratios (e.g. 10, 1), but not vice versa. This means results at different ratios are subsets of each other. All other non-metric data objects are sampled independently per record, so results at different ratios are not subsets.

The actual ratio applied is accessible via the dt.system.sampling_ratio field. Use it to extrapolate sampled counts back to true totals:

fetch logs, samplingRatio:10
| summarize count_extrapolated = sum(dt.system.sampling_ratio)

________________________________________________________________

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Dynatrace
• Source: Dynatrace/dynatrace-for-ai
• License: Apache-2.0
• Homepage: https://www.dynatrace.com

Install and usage instructions live in the source repository linked above.