dt-dql-essentials
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDQL Essentials Skill
DQL基础技能
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.
|DQL是一种基于管道的查询语言。查询使用连接命令来过滤、转换和聚合数据。DQL有着与SQL不同的独特语法——编写任何DQL查询前请先加载此技能。
|Use Cases
使用场景
| Use case | Reference |
|---|---|
| Useful expressions in DQL | references/useful-expressions.md |
| Smartscape topology navigation syntax and patterns | references/smartscape-topology-navigation.md |
| Dynatrace Semantic Dictionary: field namespaces, data models, stability levels, query patterns, and best practices | references/semantic-dictionary.md |
| Various applications of summarize and makeTimeseries commands | references/summarization.md |
Operators (in, time alignment | references/operators.md |
| Array and timeseries manipulation (creation, modifications, use in filters) using DQL | references/iterative-expressions.md |
| Query optimization (filter early, time ranges, field selection, performance) | references/optimization.md |
| 场景 | 参考文档 |
|---|---|
| DQL常用表达式 | references/useful-expressions.md |
| Smartscape拓扑导航语法与模式 | references/smartscape-topology-navigation.md |
| Dynatrace语义字典：字段命名空间、数据模型、稳定性级别、查询模式与最佳实践 | references/semantic-dictionary.md |
| summarize与makeTimeseries命令的各类应用 | references/summarization.md |
运算符（in、时间对齐运算符 | references/operators.md |
| 使用DQL进行数组与时间序列操作（创建、修改、在过滤器中使用） | references/iterative-expressions.md |
| 查询优化（提前过滤、时间范围、字段选择、性能） | references/optimization.md |
DQL Reference Index
DQL参考索引
| Description | Items |
|---|---|
| Data Types | |
| Parameter Value Types | |
| Commands | |
| Functions — Aggregation | |
| Functions — Array | |
| Functions — Bitwise | |
| Functions — Boolean | |
| Functions — Cast | |
| Functions — Constant | |
| Functions — Conversion | |
| Functions — Create | |
| Functions — Cryptographic | |
| Functions — Entities | |
| Functions — Time series aggregation for expressions | |
| Functions — Flow | |
| Functions — General | |
| Functions — Get | |
| Functions — Iterative | |
| Functions — Mathematical | |
| Functions — Network | |
| Functions — Smartscape | |
| Functions — String | |
| Functions — Time | |
| Functions — Time series aggregation for metrics | |
| 描述 | 项 |
|---|---|
| 数据类型 | |
| 参数值类型 | |
| 命令 | |
| 函数——聚合类 | |
| 函数——数组类 | |
| 函数——位运算类 | |
| 函数——布尔类 | |
| 函数——类型转换类 | |
| 函数——常量类 | |
| 函数——格式转换类 | |
| 函数——创建类 | |
| 函数——加密类 | |
| 函数——实体类 | |
| 函数——表达式时间序列聚合类 | |
| 函数——流程类 | |
| 函数——通用类 | |
| 函数——取值类 | |
| 函数——迭代类 | |
| 函数——数学类 | |
| 函数——网络类 | |
| 函数——Smartscape类 | |
| 函数——字符串类 | |
| 函数——时间类 | |
| 函数——指标时间序列聚合类 | |
Syntax Pitfalls
语法陷阱
| ❌ Wrong | ✅ Right | Issue |
|---|---|---|
| | No array literal syntax |
| | Multiple grouping fields require curly braces |
| | There's no function for |
| | Mid-string wildcards not allowed; use |
| | |
| | The correct function in DQL is called |
| | |
| | |
Chained | | Each |
| | DQL functions use named parameters — positional args cause |
| | Log severity field is |
| | fields with special characters must use backticks |
| ❌ 错误写法 | ✅ 正确写法 | 问题说明 |
|---|---|---|
| | 不支持数组字面量语法 |
| | 多分组字段需要用大括号包裹 |
| | DQL中没有 |
| | 不支持中间通配符，使用 |
对字符串字段使用 | | |
| | DQL中对应的正确函数是 |
| | |
| | |
链式 | 在两次lookup之间使用 | 每次 |
| | DQL函数使用命名参数——位置参数会报 |
| | 日志级别字段是 |
| | 包含特殊字符的字段需要用反引号包裹 |
Fetch Command → Data Model
Fetch命令对应的数据模型
Each data model has a specific fetch command — using the wrong one returns no results.
| Fetch Command | Data Model | Key Fields / Notes |
|---|---|---|
| Distributed tracing | |
| Log events | |
| Davis / infra events | |
| Business events | |
| Security events | |
| RUM sessions | |
| Metrics | NOT |
Legacy compatibility: still works in older queries, but it is deprecated. Use and for all new queries.
dt.entity.*dt.smartscape.*smartscapeNodesMetric-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
每个数据模型都有对应的fetch命令——使用错误的命令会返回空结果。
| Fetch命令 | 数据模型 | 关键字段/说明 |
|---|---|---|
| 分布式追踪 | |
| 日志事件 | |
| Davis / 基础设施事件 | |
| 业务事件 | |
| 安全事件 | |
| RUM会话 | |
| 指标 | 不使用 |
旧版兼容：在旧查询中仍然可用，但已废弃。所有新查询请使用和。
dt.entity.*dt.smartscape.*smartscapeNodes指标key注意事项：包含连字符的key会被解析为减法运算。请使用反引号包裹，例如：。
timeseries sum(`my.metric-name`)→ 完整字段命名空间参考：references/semantic-dictionary.md
Data Objects
数据对象
DQL queries start with or . There is no or — metrics are queried with .
fetch <data_object>timeseriesfetch dt.metricfetch dt.metricstimeseriesCore data objects for :
fetch| Data Object | Description |
|---|---|
| Log entries |
| Distributed traces / spans |
| Platform events |
| Business events |
| RUM individual events (page views, clicks, requests, errors) |
| RUM session-level aggregates |
| Session replay recordings |
| Security events |
| Application snapshots |
| Smartscape entity fields (e.g., |
| DAVIS-detected problems |
| DAVIS events |
Metrics — use , not :
timeseriesfetchdql
timeseries cpu = avg(dt.host.cpu.usage), by: {dt.smartscape.host}Topology — use , not :
smartscapeNodesfetchdql
smartscapeNodes "HOST"Discover available data objects:
dql
fetch dt.system.data_objects | fields name, display_name, typeDQL查询以或开头。不存在或 — 指标使用查询。
fetch <data_object>timeseriesfetch dt.metricfetch dt.metricstimeseriesfetch| 数据对象 | 描述 |
|---|---|
| 日志条目 |
| 分布式追踪/span |
| 平台事件 |
| 业务事件 |
| RUM单事件（页面访问、点击、请求、错误） |
| RUM会话级别聚合 |
| 会话回放录制 |
| 安全事件 |
| 应用快照 |
| Smartscape实体字段（例如 |
| DAVIS检测到的问题 |
| DAVIS事件 |
指标 — 使用，不要用：
timeseriesfetchdql
timeseries cpu = avg(dt.host.cpu.usage), by: {dt.smartscape.host}拓扑 — 使用，不要用：
smartscapeNodesfetchdql
smartscapeNodes "HOST"查找可用数据对象：
dql
fetch dt.system.data_objects | fields name, display_name, typeMetric Discovery
指标查找
To search for available metrics by keyword, use :
metric.seriesdql
fetch metric.series, from: now() - 1h
| filter contains(metric.key, "replay")
| summarize count(), by: {metric.key}
| sort `count()` descThere is no or — those data objects do not exist.
fetch dt.metricfetch dt.metrics要按关键词搜索可用指标，使用：
metric.seriesdql
fetch metric.series, from: now() - 1h
| filter contains(metric.key, "replay")
| summarize count(), by: {metric.key}
| sort `count()` desc不存在或 — 这些数据对象不存在。
fetch dt.metricfetch dt.metricsEntity Field Patterns
实体字段模式
Entity fields in DQL are scoped to specific entity types — not universal like SQL columns.
- does not exist — use a typed field such as
entity.id.dt.smartscape.host
| Entity | ID field |
|---|---|
| Host | |
| Service | |
| Process | |
| Kubernetes cluster | |
- For topology traversal and relationships, use instead of
smartscapeNodes.fetch
DQL中的实体字段属于特定实体类型——不像SQL列那样通用。
- 不存在 — 使用类型化字段，例如
entity.id。dt.smartscape.host
| 实体 | ID字段 |
|---|---|
| 主机 | |
| 服务 | |
| 进程 | |
| Kubernetes集群 | |
- 拓扑遍历和关系查询请使用，不要用
smartscapeNodes。fetch
Smartscape Entity Patterns
Smartscape实体模式
Use for topology queries. Node types are uppercase strings and differ from field names.
smartscapeNodes| Entity | Field name | |
|---|---|---|
| Host | | |
| Service | | |
| K8s cluster | | |
Use for ID conversion from strings (required!).
toSmartscapeId()→ references/smartscape-topology-navigation.md
拓扑查询使用。节点类型是大写字符串，与字段名不同。
smartscapeNodes| 实体 | 字段名 | |
|---|---|---|
| 主机 | | |
| 服务 | | |
| K8s集群 | | |
从字符串转换ID请使用（必须使用！）。
toSmartscapeId()→ references/smartscape-topology-navigation.md
matchesValue() Usage
matchesValue()用法
Use for array fields such as :
matchesValue()dt.tagsdql
| filter matchesValue(dt.tags, "env:production")- Not for string fields with special characters — use for those
contains() - on a scalar string field does not behave like a wildcard or fuzzy match
matchesValue()
matchesValue()dt.tagsdql
| filter matchesValue(dt.tags, "env:production")- 不要用于带特殊字符的字符串字段——这类场景使用
contains() - 对标量字符串字段使用不会实现通配符或模糊匹配效果
matchesValue()
Chained Lookup Pattern
链式Lookup模式
Each command removes all existing fields starting with before adding new ones. When chaining multiple lookups, use after each to preserve the result:
lookuplookup.fieldsRenamedql
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 availableWithout the , the second silently drops the first lookup's results — producing empty fields and collapsed aggregations.
fieldsRenamelookup每个命令在添加新字段前会清除所有已存在的以开头的字段。链式调用多个lookup时，每次调用后使用保留结果：
lookuplookup.fieldsRenamedql
fetch bizevents
// 步骤1：第一次lookup — 为订单补充产品信息
| lookup [fetch bizevents
| filter event.type == "product_catalog"
| fields product_id, category],
sourceField: product_id, lookupField: product_id
// 步骤2：下一次lookup前重命名 — 否则lookup.category会被清除
| fieldsRename product_category = lookup.category
// 步骤3：第二次lookup — lookup.*前缀现在为空，可以存储新结果
| lookup [fetch bizevents
| filter event.type == "warehouse_stock"
| fields category, warehouse_region],
sourceField: product_category, lookupField: category
// product_category和lookup.warehouse_region都可正常访问如果不使用，第二次会静默删除第一次lookup的结果——导致字段为空、聚合异常。
fieldsRenamelookupmakeTimeseries Command
makeTimeseries命令
makeTimeseriestimeseriestimeseriesmakeTimeseriesBasic syntax:
dql
fetch logs
| makeTimeseries count = count(), by: {loglevel}, interval: 5mKey parameters:
| Parameter | Required | Description |
|---|---|---|
| Yes | Aggregation to compute per bucket (e.g. |
| No | Bucket size — e.g. |
| No | Optional grouping dimensions (same |
| No | Explicit time range; defaults to the query timeframe |
| No | Number of time buckets (alternative to |
| No | Field to use as the timestamp; defaults to |
| No | Timeframe expression for bucket calculation; alternative to |
| No | Boolean; when |
→ Full formal parameter specification: references/dql/dql-commands.md
Example — error rate timeseries from logs:
dql
fetch logs
| makeTimeseries
total = count(),
errors = countIf(loglevel == "ERROR"),
interval: 5m,
by: {k8s.cluster.name}
| fieldsAdd error_rate = errors / total * 100Example — entity existence timeline using :
spread:dql
smartscapeNodes "HOST"
| makeTimeseries concurrently_existing_hosts = count(), spread: lifetimespread: lifetime→ references/iterative-expressions.md for timeseries array manipulation
makeTimeseriestimeseriestimeseriesmakeTimeseries基础语法：
dql
fetch logs
| makeTimeseries count = count(), by: {loglevel}, interval: 5m核心参数：
| 参数 | 是否必填 | 描述 |
|---|---|---|
| 是 | 每个时间桶要计算的聚合（例如 |
| 否 | 时间桶大小 — 例如 |
| 否 | 可选分组维度（与 |
| 否 | 显式时间范围；默认使用查询的时间范围 |
| 否 | 时间桶数量（ |
| 否 | 用作时间戳的字段；默认使用 |
| 否 | 时间桶计算的时间范围表达式；是 |
| 否 | 布尔值；为 |
→ 完整正式参数说明：references/dql/dql-commands.md
示例 — 从日志生成错误率时间序列：
dql
fetch logs
| makeTimeseries
total = count(),
errors = countIf(loglevel == "ERROR"),
interval: 5m,
by: {k8s.cluster.name}
| fieldsAdd error_rate = errors / total * 100示例 — 使用生成实体存在时间线：
spread:dql
smartscapeNodes "HOST"
| makeTimeseries concurrently_existing_hosts = count(), spread: lifetimespread: lifetime→ 时间序列数组操作参考references/iterative-expressions.md
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: and (if one is omitted it defaults to ), or alternatively using a single 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.
from:to:now()timeframe:@访问数据需要指定时间范围。
可以在UI中指定，作为REST API参数传递，或者在DQL查询中显式使用一对参数和（如果省略其中一个，默认值为），也可以使用单个参数替代。
时间范围可以使用绝对值表示，也可以使用相对于当前时间的表达式表示。时间对齐运算符（）可用于将时间戳对齐到时间单位边界——完整说明见references/operators.md。
from:to:now()timeframe:@Examples
示例
dql
from:now()-1h@h, to:now()@h // last complete hourdql
from:now()-1d@d, to:now()@d // yesterday completedql
from:now()@M // this month so far, till nowdql
from:now()-2h@h // go back 2 hours, then align to hour boundarydql
from:now()-1h@h, to:now()@h // 上一个完整小时dql
from:now()-1d@d, to:now()@d // 完整的昨天dql
from:now()@M // 本月至今dql
from:now()-2h@h // 回退2小时，然后对齐到小时边界Absolute timestamps
绝对时间戳
Use ISO 8601 format:
dql
from:"2024-01-15T08:00:00Z", to:"2024-01-15T09:00:00Z"使用ISO 8601格式：
dql
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)
- DQL有3种与时间相关的专用类型：
- timestamp — 内部存储为纪元以来的纳秒数，但在特定时区下展示为日期/时间
- timeframe — 包含2个timestamp的对（开始和结束）
- duration — 内部存储为纳秒数，但展示为缩放后的合理单位（例如ms、分钟、天）
Rules
规则
- Subtracting timestamps yields a duration:
timestamp - timestamp → duration - Duration divided by duration yields a double: e.g. =
2h / 1m120.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 for extracting time components.
formatTimestamp - ❌ Avoid converting timestamps and durations to double/long and using division, modulo, and constants expressing time units as nanoseconds.
- timestamp相减得到duration：
timestamp - timestamp → duration - duration除以duration得到双精度浮点数：例如=
2h / 1m120.0 - 标量乘以duration得到duration：例如
no_of_h * 1h → duration - 提取时间元素（小时、当月日期等）：
- ✅ 使用时间函数。它们完美支持日历和时区，包括夏令时。
- ❌ 不要使用提取时间组件。
formatTimestamp - ❌ 不要将timestamp和duration转换为double/long类型，再通过除法、取模和纳秒级时间单位常量进行计算。
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: comparison and
intime 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
- references/useful-expressions.md — DQL常用表达式
- references/semantic-dictionary.md — Dynatrace语义字典：字段命名空间、数据模型、稳定性级别、查询模式与最佳实践
- references/summarization.md — summarize与makeTimeseries命令的各类应用
- references/operators.md — 运算符：比较与
in时间对齐@ - references/iterative-expressions.md — 使用DQL进行数组与时间序列操作（创建、修改、在过滤器中使用）
- references/smartscape-topology-navigation.md — Smartscape拓扑导航语法与模式
- references/optimization.md — DQL查询优化：过滤位置、时间范围、字段选择与性能最佳实践
- references/dql/ — 正式DQL 1.0规范：命令、函数、数据类型与参数类型