Dynatrace 经典/Gen2 实体型 DQL 迁移到…

将 Dynatrace classic/Gen2 中基于 dt.entity.*、classicEntitySelector、entityName/entityAttr 及相关关系的 DQL 迁移为 Smartscape 等价写法。

适用场景

解决思路

1. 编写最终 DQL 前先加载 dt-dql-essentials skill，确保翻译后的查询也符合当前 DQL 语法规则。
2. 从查询目的分类开始，不要只看用了哪些经典构造；先判断查询属于三种情况之一：①用实体条件过滤的海量数据查询；②用实体子查询过滤的海量数据查询；③纯实体列表查询。
3. 情况① mass data query filtered by entity conditions：经典反模式是 `classicEntitySelector(...)` 内联在 timeseries、logs 或 metrics 查询的 `filter:` 中；迁移时先把实体条件解析为原始数据维度，Smartscape 仅作为回退方案，不是默认方案。
4. 情况② mass data query using entity subquery for filtering：经典反模式是在 `in [...]`、`lookup [...]` 或 `join [...]` 中使用 `fetch dt.entity.*` 来过滤外层海量数据查询；采用同样的维度优先策略，改写为原始维度过滤器或 `in [smartscapeNodes ...]` 子查询。
5. 情况③ pure entity list query：经典反模式是单独使用 `fetch dt.entity.*` 或把它作为主要结果来源；`smartscapeNodes` 是唯一有效路径，不存在原始维度替代方案。
6. 决策：情况①或②时，加载 references/mass-data-filtering-strategy.md 并完成所有步骤，包括字段发现（Step 2）和等价性验证（Step 4）；不要跳过 `fieldsSnapshot` 关卡，它们决定哪种方案可行；只有在需要实体类型映射或关系遍历来完成 Smartscape 子查询时，才回退到 Migration Workflow。
7. 决策：情况③时，继续执行 Migration Workflow 和实体映射表。
8. 注意：情况③有一个子情况，即用 `classicEntitySelector` 过滤 `fetch dt.entity.*` 返回的实体；这种情况少见，但走同样的 `smartscapeNodes` 路径；先用 references/mass-data-filtering-strategy.md 的 Step 1B 解析 selector 条件，再将其作为 `smartscapeNodes` 中的节点过滤器应用。
9. Migration Workflow（用于情况③，以及为情况①/②构造 Smartscape 子查询）按顺序执行：①识别经典输入模式：`fetch dt.entity.*`；`classicEntitySelector(...)`；关系字段访问如 `belongs_to[...]`、`runs[...]`、`instance_of[...]`；使用 `dt.entity.*` 的信号或事件查询。②识别涉及的经典实体类型。③在下方的核心实体映射表中查找 Smartscape 替代项。④检查哪些经典 DQL 构造需要显式迁移。⑤使用 Smartscape 原语改写查询：`smartscapeNodes`、`smartscapeEdges`、`traverse`、`references`、`getNodeName()`、`getNodeField()`。⑥检查特殊情况、不支持的实体或 ID 假设。⑦加载匹配的详细参考文档（针对具体实体族或迁移模式）。要了解完整迁移流程和输出预期，加载 references/migration-workflow.md。
10. 先使用核心实体映射表进行常见迁移；完整映射集加载 references/type-mappings.md。核心映射：`dt.entity.host` -> `dt.smartscape.host` / `HOST`；`dt.entity.service` -> `dt.smartscape.service` / `SERVICE`；`dt.entity.process_group_instance` -> `dt.smartscape.process` / `PROCESS`；`dt.entity.container_group_instance` -> `dt.smartscape.container` / `CONTAINER`；`dt.entity.kubernetes_cluster` -> `dt.smartscape.k8s_cluster` / `K8S_CLUSTER`；`dt.entity.kubernetes_node` -> `dt.smartscape.k8s_node` / `K8S_NODE`；`dt.entity.kubernetes_service` -> `dt.smartscape.k8s_service` / `K8S_SERVICE`；`dt.entity.cloud_application` -> 多个 workload 字段 / 多个 K8S workload 节点类型（需加载 cloud-application 指南）；`dt.entity.cloud_application_instance` -> `dt.smartscape.k8s_pod` / `K8S_POD`；`dt.entity.cloud_application_namespace` -> `dt.smartscape.k8s_namespace` / `K8S_NAMESPACE`；`dt.entity.application` -> `dt.smartscape.frontend` / `FRONTEND`；`dt.entity.aws_lambda_function` -> `dt.smartscape.aws.lambda_function` / `AWS_LAMBDA_FUNCTION`。
11. 迁移期间检查以下经典构造并显式改写：①`entityName(x)` -> `name` 或 `getNodeName(x)`；直接查询节点时优先用 `name`。②`entityAttr(x, "...")` -> 直接节点字段或 `getNodeField(x, "...")`；可用时优先用直接字段。③`classicEntitySelector(...)` -> 节点过滤器加 `traverse`；从受约束的一侧开始；对海量数据查询先看 mass-data-filtering-strategy.md。④信号查询中的 `dt.entity.*` -> `dt.smartscape.*`；适用于 `by`、`filter`、`fieldsAdd`、`expand` 及相关子句。⑤`belongs_to[...]`、`runs[...]`、`instance_of[...]` -> `traverse` 或 `references[...]`；`references` 仅适用于静态边。⑥经典实体 ID 过滤器 -> Smartscape `id`；不要盲目复用经典 ID。⑦`affected_entity_ids` 和 `affected_entity_types` -> `smartscape.affected_entities`；一条 record 数组替代两个并行数组；每条 record 包含 `id`、`type`、`name`。⑧详细函数级指南加载 references/dql-function-migration.md。
12. 不要逐字翻译的特殊情况：①Host group：没有独立 Smartscape 实体；使用 `HOST` 上的字段。②Process group：没有独立 Smartscape 实体；使用 `PROCESS` 上的字段。③Container group：没有独立 Smartscape 实体；如需要，用占位符保留输出形状。④Classic IDs：经典实体 ID 不会自动迁移到 Smartscape。⑤Planned、missing 或 not-planned 映射：在假定直接支持前检查完整映射表。⑥迁移这些模式前加载 references/special-cases.md。
13. 当迁移聚焦于特定实体族时，加载匹配的详细指南：references/entity-host.md；references/entity-service.md；references/entity-process.md；references/entity-container.md；references/entity-kubernetes.md；references/entity-cloud-application.md。每个指南说明：经典实体代表什么；Smartscape 替代项是什么；通常哪些字段会变化；关系如何迁移；常见示例和陷阱。
14. 按需加载 References：references/README.md（参考索引和阅读指南）；references/mass-data-filtering-strategy.md（情况①和②从这里开始；强制步骤：解析条件、运行 fieldsSnapshot 发现、选择方案、编写查询、验证等价性）；references/auto-tagging-field-mapping.md（将自动标记规则条件键映射到语义字典字段，包括海量数据和 Smartscape 节点属性）；references/entity-selector-predicates.md（`classicEntitySelector` 表达式的完整谓词词汇表）；references/migration-workflow.md（端到端迁移流程和输出预期）；references/type-mappings.md（完整的经典到 Smartscape 类型和字段映射）；references/dql-function-migration.md（如何迁移经典 DQL 函数和模式）；references/relationship-mappings.md（有效的 Smartscape 边和遍历指南）；references/special-cases.md（非逐字和不支持的实体迁移）；references/quick-reference.md（紧凑规则和注意事项）；references/examples.md（迁移前后示例）。

适用边界 · 注意事项

• 不适用于资产级迁移工作流（asset-level migration workflows）。
• 不适用于没有 Dynatrace/Smartscape 环境或不需要迁移 Dynatrace classic/Gen2 entity-based DQL 的场景。
• 不适用于非 Dynatrace DQL 的查询迁移。