Smartscape Migration Skill

This skill migrates Dynatrace classic and Gen2 entity-based DQL queries and query patterns to Smartscape-based equivalents.

Load the dt-dql-essentials skill before writing final DQL so the translated query also follows current DQL syntax rules.

This skill focuses on Smartscape-oriented DQL migration only. It does not cover asset-level migration workflows.

Query Purpose Classification

Start here. The correct migration strategy depends on what the query is actually trying to do — not just which classic constructs it uses.

There are three distinct situations:

#	Situation	Classic anti-pattern	Migration strategy
1	Mass data query filtered by entity conditions	`classicEntitySelector(...)` inline in `filter:` of a timeseries, logs, or metrics query	Resolve entity conditions to raw data dimensions first. Smartscape is a fallback, not the default.
2	Mass data query using entity subquery for filtering	`fetch dt.entity.*` inside `in [...]`, `lookup [...]`, or `join [...]` to filter the outer mass data query	Same dimension-first strategy. Rewrite as raw dimension filter or `in [smartscapeNodes ...]` subquery.
3	Pure entity list query	`fetch dt.entity.*` used standalone or as the primary result source	`smartscapeNodes` is the only valid path. No raw dimension alternative exists.

Decision:

Situations 1 or 2 — load references/mass-data-filtering-strategy.md and complete all steps including field discovery (Step 2) and equivalence verification (Step 4). Do not skip the fieldsSnapshot gates — they determine which approach is viable. Only fall back to the Migration Workflow below when the entity-type mapping or relationship traversal is needed to complete a Smartscape subquery.
Situation 3 — continue with the Migration Workflow and entity mapping table below.

Note: Situation 3 has a sub-case where classicEntitySelector is used to filter the entities returned by fetch dt.entity.*. This is rare and follows the same smartscapeNodes path — resolve the selector conditions using references/mass-data-filtering-strategy.md Step 1B, then apply them as node filters in smartscapeNodes.

Migration Workflow

Follow this order for Situation 3 (pure entity list queries) and for constructing Smartscape subqueries in Situations 1 and 2:

Identify the classic input pattern:

fetch dt.entity.*
classicEntitySelector(...)
relationship field access such as belongs_to[...], runs[...], instance_of[...]
signal or event queries using dt.entity.*

Identify the involved classic entity types.
Look up the Smartscape replacement in the core entity mapping table below.
Check which classic DQL constructs need explicit migration.
Rewrite the query using Smartscape primitives:

smartscapeNodes
smartscapeEdges
traverse
references
getNodeName()
getNodeField()

Check for special cases, unsupported entities, or ID assumptions.
Load the matching detailed references for the specific entity family or migration pattern.

For the full migration process and output expectations, load references/migration-workflow.md.

Core Entity Mapping Table

Use this compact table first for common migrations. For the full mapping set, load references/type-mappings.md.

Classic / Gen2 entity	Smartscape field	Smartscape node type	Notes
`dt.entity.host`	`dt.smartscape.host`	`HOST`	Standard host mapping
`dt.entity.service`	`dt.smartscape.service`	`SERVICE`	Standard service mapping
`dt.entity.process_group_instance`	`dt.smartscape.process`	`PROCESS`	Process instance maps directly
`dt.entity.container_group_instance`	`dt.smartscape.container`	`CONTAINER`	Container-group instance maps directly
`dt.entity.kubernetes_cluster`	`dt.smartscape.k8s_cluster`	`K8S_CLUSTER`	Kubernetes cluster
`dt.entity.kubernetes_node`	`dt.smartscape.k8s_node`	`K8S_NODE`	Kubernetes node
`dt.entity.kubernetes_service`	`dt.smartscape.k8s_service`	`K8S_SERVICE`	Kubernetes service
`dt.entity.cloud_application`	multiple workload fields	multiple K8S workload node types	Maps to multiple workload types; load the cloud-application guide
`dt.entity.cloud_application_instance`	`dt.smartscape.k8s_pod`	`K8S_POD`	Classic cloud app instance becomes pod
`dt.entity.cloud_application_namespace`	`dt.smartscape.k8s_namespace`	`K8S_NAMESPACE`	Namespace mapping
`dt.entity.application`	`dt.smartscape.frontend`	`FRONTEND`	Frontend application mapping
`dt.entity.aws_lambda_function`	`dt.smartscape.aws.lambda_function`	`AWS_LAMBDA_FUNCTION`	Cloud-function entity mapping

DQL Constructs to Inspect During Migration

These classic constructs usually need explicit rewriting:

Classic construct	Typical Smartscape replacement	Notes
`entityName(x)`	`name` or `getNodeName(x)`	Prefer `name` when querying nodes directly
`entityAttr(x, "...")`	direct node field or `getNodeField(x, "...")`	Prefer direct fields when available
`classicEntitySelector(...)`	node filters plus `traverse`	Start from the constrained side; for mass data queries see mass-data-filtering-strategy.md first
`dt.entity.*` in signal queries	`dt.smartscape.*`	Applies to `by`, `filter`, `fieldsAdd`, `expand`, and related clauses
`belongs_to[...]`, `runs[...]`, `instance_of[...]`	`traverse` or `references[...]`	`references` works only for static edges
classic entity ID filters	Smartscape `id`	Do not reuse classic IDs blindly
`affected_entity_ids` and `affected_entity_types`	`smartscape.affected_entity.ids` and `smartscape.affected_entity.types`	Use Smartscape event fields

For the detailed function-by-function guide, load references/dql-function-migration.md.

Special Cases

Do not translate these patterns literally:

Host group — no standalone Smartscape entity; use fields on HOST
Process group — no standalone Smartscape entity; use fields on PROCESS
Container group — no standalone Smartscape entity; preserve output shape with placeholders if needed
Classic IDs — classic entity IDs do not carry over to Smartscape automatically
Planned, missing, or not-planned mappings — check the full mapping table before assuming direct support

Load references/special-cases.md before migrating these patterns.

Entity-Focused Guides

When a migration centers on a specific entity family, load the matching detailed guide:

Each guide explains:

what the classic entity represented
what the Smartscape replacement is
which fields usually change
how relationships are migrated
common examples and pitfalls

References

references/README.md — Reference index and reading guide
references/mass-data-filtering-strategy.md — Start here for Situations 1 and 2. Mandatory steps: resolve conditions, run fieldsSnapshot discovery, select approach, write query, verify equivalence
references/auto-tagging-field-mapping.md — Maps auto-tagging rule condition keys to semantic dictionary fields (mass data and Smartscape node attributes)
references/entity-selector-predicates.md — Full predicate vocabulary for classicEntitySelector expressions
references/migration-workflow.md — End-to-end migration process and output expectations
references/type-mappings.md — Full classic-to-Smartscape type and field mappings
references/dql-function-migration.md — How to migrate classic DQL functions and patterns
references/relationship-mappings.md — Valid Smartscape edges and traversal guidance
references/special-cases.md — Non-literal and unsupported entity migrations
references/quick-reference.md — Compact rules and gotchas
references/examples.md — Before/after migration examples

dt-migration