Dt Migration

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:

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:

1. 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.*

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

• smartscapeNodes
• smartscapeEdges
• traverse
• references
• getNodeName()
• getNodeField()

6. Check for special cases, unsupported entities, or ID assumptions. 7. 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.

DQL Constructs to Inspect During Migration

These classic constructs usually need explicit rewriting:

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:

• 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

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

Auto-Tagging Keys → Semantic Dictionary Field Mapping

Maps every ManagementZoneDataSourceMeAttribute key from auto_tagging_attributes.md to the most appropriate field defined in this semantic dictionary.

Legend:

• — — no direct equivalent exists in the semantic dictionary

---

Notes

Any auto tagging key referring to `*_TAGS uses a rule condition that is itself based on tags. Note that the referenced tags may either be the result of another rule for which a recursive search is then necessary to find the original underlying attribute. Alternatively, the referenced tags may also be imported from the monitored environment like cloud vendor tags/labels, Kubernetes labels/attributes or OneAgent environment variables. Cloud vendor tags have the pattern aws/azure/gcp.tags.*` where

Dynatrace supports "primary tags" which is a way to letting customers select custom tags from the source environment and placing them as enriched fields on mass data and top level attributes on smartscape nodes. For example, a selected Kubernetes label `team:backend on a POD becomes primary_tags.team:backend. Smartscape nodes usually contain all collected environment labels and mass data only a selected subset. Smartscape nodes group labels or tags in the structure of the tags` attribute.

HOST

Matching Smartscape Node: HOST

---

PROCESS_GROUP

Matching Smartscape Node: Does not exist, attributes need to be found on PROCESS nodes

---

SERVICE

Matching Smartscape Node: SERVICE

---

QUEUE

Matching Smartscape Node: SERVICE

---

CUSTOM_DEVICE

Matching Smartscape Node: Depends on the custom devices "type" attribute.

---

CUSTOM_DEVICE_GROUP

Matching Smartscape Node: No equivalent type.

---

WEB_APPLICATION

Matching Smartscape Node: FRONTEND

---

MOBILE_APPLICATION

Matching Smartscape Node: FRONTEND

---

CUSTOM_APPLICATION

Matching Smartscape Node: FRONTEND

---

ENTERPRISE_APPLICATION (DC-RUM App)

Matching Smartscape Node: No equivalent

---

DATA_CENTER_SERVICE (DC-RUM Service)

Matching Smartscape Node: No equivalent

---

BROWSER_MONITOR (Synthetic Test)

---

EXTERNAL_MONITOR (External Synthetic Test)

Matching Smartscape Node: Coming later.

---

HTTP_MONITOR

---

NETWORK_AVAILABILITY_MONITOR (NAM)

Matching Smartscape Node: No equivalent.

---

DOCKER

Matching Smartscape Node: CONTAINER

---

ESXI_HOST (Hypervisor)

Matching Smartscape Node: No equivalent.

---

EC2_INSTANCE

Matching Smartscape Node: AWS_EC2_INSTANCE

---

OPENSTACK_VM

Matching Smartscape Node: Unknown

---

VMWARE_VM

Matching Smartscape Node: Unknown.

---

KUBERNETES

Matching Smartscape Nodes, K8S_CLUSTER, K8S_NODE, K8S_SERVICE

---

CLOUD_APPLICATION

Matching Smartscape Node: K8S_DEPLOYMENT, K8S_REPLICASET, K8S_STATEFULSET, K8S_DAEMONSET, K8S_JOB, K8S_CRONJOB

---

AWS_AUTO_SCALING_GROUP

Matching Smartscape Node: AWS_AUTOSCALING_AUTOSCALINGROUP

---

AWS_CLASSIC_LOAD_BALANCER

Matching Smartscape Node: AWS_ELASTICLOADBALANCING_LOADBALANCER

---

AWS_APPLICATION_LOAD_BALANCER

Matching Smartscape Node: TBD

---

AWS_NETWORK_LOAD_BALANCER

Matching Smartscape Node: TBD

---

AWS_RELATIONAL_DATABASE_SERVICE

Matching Smartscape Node: AWS_RDS_DBCLUSTER

---

AWS_ACCOUNT

Matching Smartscape Node: AWS_ACCOUNT

---

AZURE

Matching Smartscape Node: TBD

---

DATACENTER

Matching Smartscape Node: TBD

---

OPENSTACK_ACCOUNT

Matching Smartscape Node: No equivalent

---

OPENSTACK

Matching Smartscape Node: No equivalent

---

CLOUD_FOUNDRY

Matching Smartscape Node: No equivalent

DQL Function and Pattern Migration

Use this reference when the migration is driven by a classic DQL construct rather than by a single entity type.

Contents

• `entityName()`
• `entityAttr()`
• `classicEntitySelector()`
• Classic relationship fields
• Signal dimensions
• Event fields
• Classic IDs

entityName()

Typical replacements

• When querying Smartscape nodes directly, prefer name
• When you only have an ID in a signal or edge query, use getNodeName(id)

Examples

fetch dt.entity.host
| fields entity.name, id

becomes:

smartscapeNodes HOST
| fields entity.name = name, id

If the migrated query works on edge records or signal dimensions:

| fields target_name = getNodeName(target_id)

Important rule

getNodeName() accepts only an ID. Do not pass a type: argument.

entityAttr()

Typical replacements

• Prefer a direct node field when Smartscape exposes one
• Otherwise use getNodeField(id_or_dimension, "field")

Example

Classic signal-style tag access often appears as:

| filter in(entityAttr(dt.entity.aws_lambda_function, "tags"), "[AWS]dt_owner_team:team-mirage")

Smartscape form:

| filter getNodeField(dt.smartscape.aws_lambda_function, "tags:aws")[dt_owner_team] == "team-mirage"

classicEntitySelector()

Migration strategy

1. Parse the selector for the constrained entity and relationships 2. Start from the constrained side if possible 3. Convert selector filters to Smartscape node filters 4. Replace fromRelationship.* and toRelationship.* with traverse

Example without relationships

fetch dt.entity.host
| filter in(id, classicEntitySelector("type(host),tag([Environment]syn_grail_log:bastion)"))
| fields entity.name, id

becomes:

smartscapeNodes HOST
| filter `tags:environment`[syn_grail_log] == "bastion"
| fields entity.name = name, id

Example with relationships

fetch dt.entity.service
| filter in(id, classicEntitySelector("type(service), fromRelationship.runsOnHost(type(host), tag([Azure]dt_owner_email:team-ops@example.com))"))
| fields id, entity.name

becomes:

smartscapeNodes HOST
| filter `tags:azure`[dt_owner_email] == "team-ops@example.com"
| traverse runs_on, SERVICE, direction:backward
| fields id, entity.name = name

Classic relationship fields

Classic entity queries often expose relationships as projected fields such as:

• belongs_to[...]
• runs[...]
• instance_of[...]
• clustered_by[...]

Typical replacements

• Use traverse for relationship navigation
• Use smartscapeEdges when the result should be an edge-centric record set
• Use references[...] for static edges when simple field access is enough

references[...]

Use references only for static edges.

Example:

fetch dt.entity.network_interface
| fieldsAdd host = belongs_to[dt.entity.host]

becomes:

smartscapeNodes NETWORK_INTERFACE
| fieldsAdd host = references[belongs_to.host]

Signal dimensions

Every classic entity dimension in signal queries must be migrated.

Rule

• dt.entity.host → dt.smartscape.host
• dt.entity.service → dt.smartscape.service
• ` dt.entity.os:service → dt.smartscape.os_service`

Apply this rule everywhere in the signal query, not only in the main by clause.

Example

timeseries avg(dt.service.request.response_time),
  by:{ dt.entity.service }

becomes:

timeseries avg(dt.service.request.response_time),
  by:{ dt.smartscape.service }

Event fields

Use these field migrations in Davis event queries:

Important value rule

When the field contains entity types, use uppercase Smartscape type values such as HOST, SERVICE, or CONTAINER, not classic values like dt.entity.host.

Classic IDs

Classic entity IDs do not automatically carry over to Smartscape.

Rule

• never use id_classic
• when comparing to a Smartscape ID literal, wrap it with toSmartscapeId()

Example:

| filter in(dt.smartscape.host, { toSmartscapeId("HOST-ABC123") })

Open assumption pattern

If the classic query filters by a specific classic entity ID and the matching Smartscape ID is unknown, call that out as an assumption and tell the user how to look it up.

Example note:

// ASSUMPTION: Replace the old classic host ID with the matching Smartscape host ID.
// Look it up with:
smartscapeNodes HOST | fields id, name

Cloud Application Migration Guide

Use this guide when the classic query uses:

• dt.entity.cloud_application
• dt.entity.cloud_application_instance
• dt.entity.cloud_application_namespace

Core mappings

Why this matters

The classic cloud-application model grouped several Kubernetes workload concepts under one type. Smartscape models those workload types explicitly.

That means a direct one-to-one replacement often does not exist for dt.entity.cloud_application.

Migration guidance

dt.entity.cloud_application

• query the relevant workload types explicitly
• use workload or Kubernetes fields such as k8s.cluster.name
• if the classic query assumed one unified type, make the new multi-type scope explicit

dt.entity.cloud_application_instance

• translate to smartscapeNodes K8S_POD
• use first-class pod fields:
• k8s.workload.name
• k8s.namespace.name
• k8s.node.name
• k8s.cluster.name

dt.entity.cloud_application_namespace

• translate to smartscapeNodes K8S_NAMESPACE

Example: workload mapping

smartscapeNodes K8S_DEPLOYMENT, K8S_DAEMONSET, K8S_STATEFULSET, K8S_REPLICASET,
  K8S_REPLICATIONCONTROLLER, K8S_JOB, K8S_DEPLOYMENTCONFIG
| fields
    entity.name = name,
    kubernetesClusterName = k8s.cluster.name,
    cloudApplicationLabels = `tags:k8s.labels`

Example: pod mapping

smartscapeNodes K8S_POD
| fields entity.name = name,
  workloadName = k8s.workload.name,
  namespaceName = k8s.namespace.name,
  nodeName = k8s.node.name,
  kubernetesClusterName = k8s.cluster.name

Related references

• entity-kubernetes.md
• type-mappings.md
• examples.md

Container Migration Guide

Use this guide when the migration centers on dt.entity.container_group_instance or dt.entity.container_group.

Core mapping

Container-group special case

dt.entity.container_group is not a standalone Smartscape node.

When the old query projects container-group identifiers or names, preserve the output shape with null if there is no real equivalent.

Common field migrations

• entity.name → name
• containerizationType → container.containerization_type
• classic affected-entity event joins → smartscape.affected_entity.ids and smartscape.affected_entity.types

Relationship patterns

• CONTAINER runs_on HOST
• CONTAINER runs_on K8S_NODE
• CONTAINER is_part_of K8S_POD
• CONTAINER belongs_to K8S_NAMESPACE
• CONTAINER belongs_to K8S_CLUSTER

Example

smartscapeNodes CONTAINER
| fields
    id,
    containerName = name,
    containerizationType = container.containerization_type,
    containerGroupId = null,
    containerGroupName = null

Related references

• special-cases.md
• examples.md
• relationship-mappings.md

Host Migration Guide

Use this guide when the migration centers on dt.entity.host or host-related signal dimensions.

Core mapping

Common field migrations

• entity.name → name
• host tags in signal queries → getNodeField(dt.smartscape.host, "tags")
• host group data → host fields such as dt.host_group.id

Relationship patterns

• host to service via runs_on
• host to VM via runs_on
• host to disk via belongs_to

Important special case

dt.entity.host_group is not a Smartscape node type. Do not traverse to HOST_GROUP.

Example

smartscapeNodes HOST
| filter `tags:environment`[syn_grail_log] == "bastion"
| fields entity.name = name, id

Related references

• special-cases.md
• relationship-mappings.md
• examples.md

Kubernetes Migration Guide

Use this guide when the migration centers on Kubernetes cluster, node, namespace, service, pod, or workload entities.

Common mappings

Workload relationships

Smartscape models workload relationships explicitly:

• K8S_POD belongs_to K8S_CLUSTER
• K8S_POD belongs_to K8S_NAMESPACE
• K8S_POD runs_on K8S_NODE
• K8S_POD is_part_of K8S_DEPLOYMENT, K8S_STATEFULSET, K8S_DAEMONSET, and related workload types
• K8S_SERVICE routes_to K8S_POD

Migration guidance

• Prefer first-class k8s.* fields when querying pods or workloads directly
• Use traverse when the relationship itself matters
• For classic cloud application concepts, also load entity-cloud-application.md

Example

smartscapeNodes K8S_POD
| fields entity.name = name,
  workloadName = k8s.workload.name,
  namespaceName = k8s.namespace.name,
  nodeName = k8s.node.name,
  kubernetesClusterName = k8s.cluster.name

Related references

• entity-cloud-application.md
• relationship-mappings.md
• examples.md

Process Migration Guide

Use this guide when the migration centers on dt.entity.process_group_instance or dt.entity.process_group.

Core mapping

Process-group special case

dt.entity.process_group is not a standalone Smartscape node.

Use fields on PROCESS instead:

• dt.process_group.id
• dt.process_group.name
• dt.process_group.detected_name

Relationship patterns

• PROCESS runs_on HOST
• PROCESS runs_on CONTAINER
• PROCESS calls PROCESS

Example

smartscapeNodes PROCESS
| summarize by:{ id = dt.process_group.id, entity.name = dt.process_group.detected_name }, process.metadata = takeAny(process.metadata)

Related references

• special-cases.md
• relationship-mappings.md
• type-mappings.md

Entity Selector Predicates

Reference for all valid predicates in the entity selector query language, used via the /api/v2/entities API.

Multiple predicates are combined with , (implicit AND):

type("SERVICE"),tag("env:prod"),mzName("Production"),healthState("UNHEALTHY")

Each section includes a Semantic Dictionary Field column that maps classic entity selector predicates to their corresponding fields in the Dynatrace Semantic Dictionary. These mappings help when migrating from classic entity-based queries to Grail/DQL-based workflows. Calls to `fieldsSnapshot ...` allow discovery of available enriched mass data fields or Smartscape Node attributes.

---

Core / Identity

---

Management Zone

Note: In Grail, management zones are replaced by ownership and permission models. Can not appear in DQL queries, only directly in query constructs against classic APIs.

---

Tags

Note: See mass-data-filtering-strategy.md for how to resolve tag filter conditions.

---

Health State

---

Timestamps

Each supports .lte, .lt, .gte, .gt operators. Predicates based on entity lifetime need to be translated to Smartscape Node queries with equivalent filters on `lifetime`.

Note: lifetime is a complex record containing start/end timestamps representing when the entity was first and last seen.

---

Modifiers / Wrappers

---

Filter Predicates

These accept an optional .exists variant (e.g., ipAddress.exists).

Note: Where two fields are listed (e.g., os.type / osType), the first is the normalized Semantic Dictionary resource field and the second is the classic shared entity property. Use the normalized field for new Grail/DQL queries and the shared field when querying the classic entity model.

---

AppSec

Note: AppSec coverage predicates do not have direct Semantic Dictionary equivalents. Related security data is available through vulnerability.* and dt.security.* signal fields.

---

Releases

---

Installer

---

Relationship Predicates

Syntax: fromRelationships.<name>(<entitySelector>) or toRelationships.<name>(<entitySelector>)

Example:

type("SERVICE"),fromRelationships.runsOn(type("HOST"),entityName.contains("prod"))

The Semantic Dictionary defines normalized relationship types in the relationships group of source/model/dt.entities/model_group_dt_entities.yaml. Classic entity selector relationship names map to these normalized types as follows:

Mapping to Semantic Dictionary Relationship Types

All Classic Relationship Names (Reference)

Note: The Semantic Dictionary normalizes the many specific classic relationship names (e.g., isClusterOfNode, isNamespaceOfPg) into a smaller set of generic relationship types (e.g., cluster_of, contains). The classic names remain valid for entity selector queries against the v2 API.

---

Postfix Operators

All string predicates support these operators. Numeric and timestamp predicates support comparison operators.

Service Migration Guide

Use this guide when the migration centers on dt.entity.service or service-related signal dimensions.

Core mapping

Common migration patterns

• entity.name → name
• service signal dimension dt.entity.service → dt.smartscape.service
• classic selectors constrained by host or process often become traverse runs_on, SERVICE, direction:backward

Common relationships

• SERVICE runs_on HOST
• SERVICE runs_on PROCESS
• SERVICE runs_on CONTAINER
• SERVICE calls SERVICE

Example

smartscapeNodes HOST
| filter `tags:azure`[dt_owner_email] == "team-ops@example.com"
| traverse runs_on, SERVICE, direction:backward
| fields id, entity.name = name

Related references

• relationship-mappings.md
• dql-function-migration.md
• examples.md

Example Migrations

Use these examples as before/after templates.

Keep the same pattern when adding more examples:

1. input query 2. Smartscape translation sketch 3. notes about the mapping

Contents

• Example 001: `classicEntitySelector` filter without relationships
• Example 002: expanding relationships
• Example 003: `classicEntitySelector` with relationships
• Example 004: signal query with Smartscape dimension
• Example 005: `CLOUD_APPLICATION` to workload node types
• Example 006: `CLOUD_APPLICATION_INSTANCE` to `K8S_POD`
• Example 007: signal query with Smartscape tag access
• Example 008: AWS DynamoDB table field projection
• Example 009: filter by tags and host group
• Example 010: multi-cloud datacenter traversal with missing relationship handling
• Example 011: container plus affected-entity mapping
• Example 012: mass data migration end-to-end with fieldsSnapshot
• Example 013: `timeseries filter` with tag-based entity sub-query

Example 001: classicEntitySelector filter without relationships

Input

fetch dt.entity.host
| filter in(id, classicEntitySelector("type(host),tag([Environment]syn_grail_log:bastion)"))
| fields entity.name, id

Smartscape sketch

smartscapeNodes HOST
| filter `tags:environment`[syn_grail_log] == "bastion"
| fields entity.name = name, id

Notes

• entity.name becomes name
• tag context [Environment] becomes ` tags:environment `

Example 002: expanding relationships

Input

fetch dt.entity.host
| fieldsAdd runs[dt.entity.service_instance]
| expand service_instance = runs[dt.entity.service_instance]
| fields
    id,
    entity.name,
    service_instance

Smartscape sketch

smartscapeEdges runs_on
| filter target_type == "HOST" and source_type == "SERVICE"
| fields
    id = target_id,
    entity.name = getNodeName(target_id),
    service_instance = source_id

Notes

• use edge records when the output shape is relationship-centric

Example 003: classicEntitySelector with relationships

Input

fetch dt.entity.service
| filter in(id, classicEntitySelector("type(service), fromRelationship.runsOnHost(type(host), tag([Azure]dt_owner_email:team-ops@example.com))"))
| fields id, entity.name

Smartscape sketch

smartscapeNodes HOST
| filter `tags:azure`[dt_owner_email] == "team-ops@example.com"
| traverse runs_on, SERVICE, direction:backward
| fields id, entity.name = name

Notes

• start from the constrained side and traverse backward

Example 004: signal query with Smartscape dimension

Input

timeseries avg(dt.service.request.response_time),
  by:{ dt.entity.service }

Smartscape sketch

timeseries avg(dt.service.request.response_time),
  by:{ dt.smartscape.service }

Notes

• every dt.entity.* signal dimension must be migrated

Example 005: CLOUD_APPLICATION to workload node types

Input

fetch dt.entity.cloud_application
| fields entity.name, kubernetesClusterName, cloudApplicationLabels

Smartscape sketch

smartscapeNodes K8S_DEPLOYMENT, K8S_DAEMONSET, K8S_STATEFULSET, K8S_REPLICASET,
  K8S_REPLICATIONCONTROLLER, K8S_JOB, K8S_DEPLOYMENTCONFIG
| fields
    entity.name = name,
    kubernetesClusterName = k8s.cluster.name,
    cloudApplicationLabels = `tags:k8s.labels`

Notes

• one classic type becomes multiple workload node types

Example 006: CLOUD_APPLICATION_INSTANCE to K8S_POD

Input

fetch dt.entity.cloud_application_instance
| fields
    entity.name,
    workloadName,
    namespaceName,
    nodeName,
    kubernetesClusterName = entityName(clustered_by[dt.entity.kubernetes_cluster], type:"dt.entity.kubernetes_cluster")

Smartscape sketch

smartscapeNodes K8S_POD
| fields entity.name = name,
  workloadName = k8s.workload.name,
  namespaceName = k8s.namespace.name,
  nodeName = k8s.node.name,
  kubernetesClusterName = k8s.cluster.name

Notes

• use first-class k8s.* fields on K8S_POD

Example 007: signal query with Smartscape tag access

Input

timeseries avg(dt.host.cpu.usage),
  by:{ dt.entity.host }
| filter in(entityAttr(dt.entity.host, "tags"), "Dtp_Capability:grail")

Smartscape sketch

timeseries avg(dt.host.cpu.usage),
  by:{ dt.smartscape.host }
| filter getNodeField(dt.smartscape.host, "tags")[Dtp_Capability] == "grail"

Notes

• migrate the signal dimension and replace classic tag access with getNodeField()
• use unquoted key syntax for tag-map access: ...[Dtp_Capability]; quoted keys in this pattern cause a DQL syntax error

Example 008: AWS DynamoDB table field projection

Input

fetch `dt.entity.cloud:aws:dynamodb:table`
| fields entity.name, aws_account, aws_arn, aws_region, aws_resource_type, aws_service, cloud_provider

Smartscape sketch

smartscapeNodes AWS_DYNAMODB_TABLE
| fields
  entity.name = name,
  aws_account = aws.account.id,
  aws_arn = aws.arn,
  aws_region = aws.region,
  parse(aws.resource.type, """ (WORD "::" WORD) "::" WORD:aws_resource_type"""),
  parse(aws.resource.type, """ (WORD "::" WORD):aws_service "::" WORD"""),
  cloud_provider = cloud.provider

Notes

• prefer native Smartscape cloud fields; parse composite fields only when necessary

Example 009: filter by tags and host group

Input

timeseries series = avg(dt.host.cpu.usage),
  filter:{
    in(dt.host_group.id, array("dtp-dev101-grail"))
    and in(dt.entity.host, classicEntitySelector("type(host),tag(\"Dtp_Capability:grail\")"))
    and in(dt.entity.host, classicEntitySelector("type(host),tag(\"Dtp_Tier:segment-indexer-traces\")"))
  },
  by:{ dt.entity.host }

Smartscape sketch

timeseries series = avg(dt.host.cpu.usage),
  filter:{
    in(dt.host_group.id, array("dtp-dev101-grail"))
    and getNodeField(dt.smartscape.host, "tags")[Dtp_Capability] == "grail"
    and getNodeField(dt.smartscape.host, "tags")[Dtp_Tier] == "segment-indexer-traces"
  },
  by:{ dt.smartscape.host }

Notes

• host group remains a host field, not a traversed entity
• use unquoted key syntax for tag-map access: ...[Dtp_Capability] and ...[Dtp_Tier]; quoted keys in this pattern cause a DQL syntax error

Example 010: multi-cloud datacenter traversal with missing relationship handling

Input

fetch dt.entity.host
| filterOut isMonitoringCandidate
| fieldsAdd
    dt.entity.aws_availability_zone = belongs_to[dt.entity.aws_availability_zone],
    dt.entity.azure_region = belongs_to[dt.entity.azure_region],
    dt.entity.gcp_zone = belongs_to[dt.entity.gcp_zone]
| fieldsAdd
    awsDataCenterName = entityName(dt.entity.aws_availability_zone),
    azureRegionName = entityName(dt.entity.azure_region),
    gcpZoneName = entityName(dt.entity.gcp_zone)
| fields
    id,
    entity.name,
    dataCenter = coalesce(dt.entity.aws_availability_zone, dt.entity.azure_region, dt.entity.gcp_zone, "NO_DATACENTER"),
    dataCenterName = coalesce(awsDataCenterName, azureRegionName, gcpZoneName, "No Data center")

Smartscape sketch

smartscapeNodes HOST
| lookup [
    smartscapeNodes HOST
    | traverse runs_on, {AWS_EC2_INSTANCE, AZURE_MICROSOFT_COMPUTE_VIRTUALMACHINES,  GCP_COMPUTE_GOOGLEAPIS_COM_INSTANCE}, direction:forward
    | traverse runs_on, {AWS_AVAILABILITY_ZONE, AZURE_REGION, GCP_ZONE}, direction:forward
    | fields dt.smartscape.host = dt.traverse.history[-2][id], dataCenter = id, dataCenterName = name
  ], sourceField:id, lookupField:dt.smartscape.host, fields:{ dataCenter, dataCenterName }
| fields
    id,
    entity.name = name,
    dataCenter = coalesce(dataCenter, "NO_DATACENTER"),
    dataCenterName = coalesce(dataCenterName, "No Data center")

Notes

• use lookup to preserve hosts without cloud relationships

Example 011: container plus affected-entity mapping

Input

fetch dt.entity.container_group_instance
| fields
    id,
    containerName = entity.name,
    containerizationType = containerizationType,
    containerGroupId = instance_of[dt.entity.container_group],
    containerGroupName = entityName(instance_of[dt.entity.container_group], type:"dt.entity.container_group")
| lookup [
  fetch dt.davis.events.snapshots
  | filter isNotNull(affected_entity_ids)
  | filter in(affected_entity_types, "dt.entity.container_group_instance")
  | expand affected_entity_ids
  | summarize by:{affected_entity_ids}, events = countDistinct(event.id)
], sourceField:id, lookupField:affected_entity_ids, fields: events
| fieldsAdd events = if(isNull(events), 0, else:events)
| fields id, containerName, containerizationType, containerGroupId, containerGroupName, events

Smartscape sketch

smartscapeNodes CONTAINER
| fields
    id,
    containerName = name,
    containerizationType = container.containerization_type,
    containerGroupId = null,
    containerGroupName = null
| lookup [
  fetch dt.davis.events.snapshots
  | filter isNotNull(smartscape.affected_entity.ids)
  | filter in(smartscape.affected_entity.types, "CONTAINER")
  | expand smartscape.affected_entity.ids
  | fields affected_entity_ids = smartscape.affected_entity.ids, event.id
  | summarize by:{affected_entity_ids}, events = countDistinct(event.id)
], sourceField:id, lookupField:affected_entity_ids, fields: events
| fieldsAdd events = if(isNull(events), 0, else:events)
| fields id, containerName, containerizationType, containerGroupId, containerGroupName, events

Notes

• container_group_instance maps to CONTAINER
• container_group remains unsupported as a standalone entity
• event fields become Smartscape event fields

Example 012: mass data migration end-to-end with fieldsSnapshot

This example demonstrates the full mass-data-filtering-strategy.md workflow including field discovery and verification.

Input

timeseries avg(dt.host.cpu.idle),
  filter:{ in(dt.entity.host, classicEntitySelector("type(HOST),tag(Dtp_Tier:segment-indexer-traces),hostGroupName(dtp-dev101-grail)")) },
  by:{ dt.entity.host }

Step 1 — Resolve conditions

Two conditions extracted from the classicEntitySelector:

• tag(Dtp_Tier:segment-indexer-traces) — resolved via auto-tagging rule config. The rule targets entity type HOST with condition key HOST_TAGS referencing a primary tag. Mapped field: tag Dtp_Tier with value segment-indexer-traces.
• hostGroupName(dtp-dev101-grail) — maps to dt.host_group.id on HOST node or as enriched dimension.

Step 2 — Discover available fields

Mass data discovery:

dtctl query 'fieldsSnapshot metrics, by:{metric.key} | filter metric.key == "dt.host.cpu.idle" | fields field' --plain

Output includes: dt.entity.host, dt.smartscape.host, dt.host_group.id, host.name, ... (but NOT Dtp_Tier or host.group.name)

Node discovery:

dtctl query 'fieldsSnapshot smartscape.nodes, by:{node.type} | filter node.type == "HOST" | fields field' --plain

Output includes: host.group.name, tags, name, cloud.provider, ...

Step 3 — Select approach

• dt.host_group.id is an enriched dimension on the metric -> Check 1 applies for the host group condition.
• Dtp_Tier tag is NOT an enriched dimension, but dt.smartscape.host exists and tags is available on the HOST node -> Check 2 applies for the tag condition.

Both conditions can be expressed as inline filters using a mix of direct dimension filter and getNodeField.

Migrated query

timeseries avg(dt.host.cpu.idle),
  filter:{
    dt.host_group.id == "dtp-dev101-grail"
    AND getNodeField(dt.smartscape.host, "tags")[Dtp_Tier] == "segment-indexer-traces"
  },
  by:{ dt.smartscape.host }
/* Original: timeseries avg(dt.host.cpu.idle), filter:{ in(dt.entity.host, classicEntitySelector("type(HOST),tag(Dtp_Tier:segment-indexer-traces),hostGroupName(dtp-dev101-grail)")) }, by:{ dt.entity.host } */

Step 4 — Verification

• Output shape: original had timeframe, interval, avg(dt.host.cpu.idle), dt.entity.host. Migrated has same structure with dt.smartscape.host replacing dt.entity.host.
• Probe: ran migrated query over last 5 minutes, returned 3 time series matching expected hosts.
• Host group condition confirmed via dt.host_group.id enriched dimension; tag condition confirmed via getNodeField on dt.smartscape.host.

Mapping Resolution

• dt.entity.host dimension -> dt.smartscape.host
• hostGroupName(X) -> dt.host_group.id (enriched dimension, Check 1)
• tag(Dtp_Tier:X) -> getNodeField(dt.smartscape.host, "tags")[Dtp_Tier] (Check 2)

Notes

• Combines Check 1 (direct dimension) and Check 2 (getNodeField) in the same query when conditions map to different field types
• fieldsSnapshot discovery was mandatory to confirm dt.host_group.id is enriched but Dtp_Tier is not

Example 013: timeseries filter with tag-based entity sub-query

Input

timeseries usage=avg(dt.host.cpu.usage),
  filter: { in(dt.entity.host, classicEntitySelector("type(host),tags(\"BF\")")) }

Smartscape sketch

timeseries usage=avg(dt.host.cpu.usage),
  filter: { dt.smartscape.host in [smartscapeNodes "HOST" | filter tags ~ "BF" | fields id] }

Notes

• dt.entity.host → dt.smartscape.host (standard dimension migration)
• in(dt.entity.host, classicEntitySelector(...)) → dt.smartscape.host in [...]: the in() function does not accept execution blocks — use the in operator (field in [execution block]) when the right-hand side is a sub-query
• tags("BF") in the classic selector matches hosts tagged with BF; in Smartscape, tags ~ "BF" uses substring matching on the serialized tag string, which also matches tags whose key or value contains BF — use an exact match if needed: `tags[BF] == <value> or isNotNull(tags[BF]`

Mass Data Filtering Strategy

Covers Situations 1 and 2 from the Query Purpose Classification in SKILL.md: migrating DQL queries where entities serve only as a filter on mass data (timeseries, logs, metrics). For pure entity list queries (Situation 3), return to SKILL.md.

Step 1 — Resolve the filter conditions

A. Tag-based filter — tag(X) or matchesValue(tags, "X")

Tag origins: Tags in Dynatrace have three possible sources:

>

1. Rule-based — created via auto-tagging rules (builtin:tags.auto-tagging).

2. Imported — automatically applied from cloud providers (e.g., AWS tags, Azure tags, GCP labels) or other integrations. Imported tags are recognizable by a bracketed prefix in their key, e.g. [AWS]Name, [Environment]Stage.

3. Manually applied — added by users through the UI or the Dynatrace API.

>

Only rule-based tags can be migrated by inspecting the tagging rule configuration as described below. For imported or manually applied tags there is no declarative rule to resolve; you must identify the underlying entity attribute or condition that the tag represents and use that directly as the filter (treat as Step 1B). However, the values behind imported or manually applied tags may still be available as enriched dimensions on the mass data — the field discovery in Step 2 still applies and should be executed to check for a direct match.

Fetch the tagging rule config:

dtctl get settings --schema builtin:tags.auto-tagging -o json --plain

Find the entry where value.name matches the tag key. Rules within a tag have OR semantics; conditions within a rule have AND semantics. If a condition key ends with _TAG, recursively resolve that tag's rule.

Propagation flags: pgToHostPropagation, pgToServicePropagation, serviceToHostPropagation mean the tag applies to a different entity type than the rule's entityType. Note which entity type the conditions actually describe — this drives approach selection in Step 3.

key:value tags: Inspect valueFormat for placeholders like {Host:Kubernetes:label//key}. If the value comes from a K8s label, k8s.workload.name is often a simpler discriminator.

Map condition keys to semantic fields via auto-tagging-field-mapping.md. Resolve *_TAG conditions recursively.

B. Explicit attribute filter — non-tag classicEntitySelector predicates

The conditions are already explicit in the selector string. Parse each predicate using entity-selector-predicates.md and map to its semantic field using the table below.

---

Step 2 — Discover available fields (MANDATORY — execute before proceeding)

STOP. Execute the commands below now. The outputs determine which approach is viable. Do not proceed to Step 3 without these results.

2a. Inspect the mass data source

Run fieldsSnapshot on the data source from the original query to discover enriched dimensions:

dtctl query 'fieldsSnapshot metrics, by:{metric.key} | filter metric.key == "<the_metric>" | fields field' --plain

dtctl query 'fieldsSnapshot logs, by:{dt.system.bucket} | filter matchesValue(dt.system.bucket, "<the_bucket>") | fields field' --plain

Record from the output:

1. Which enriched dimensions match the resolved conditions from Step 1 (e.g., k8s.namespace.name, host.name) 2. Whether a dt.smartscape.* dimension exists for the relevant entity type (e.g., dt.smartscape.host) 3. Whether a dt.entity.* dimension exists (e.g., dt.entity.host)

2b. Inspect the smartscape node type

Run fieldsSnapshot on the smartscape node type that matches the entity type from Step 1:

dtctl query 'fieldsSnapshot smartscape.nodes, by:{node.type} | filter node.type == "<TYPE>" | fields field' --plain

Record from the output: which node attributes match the resolved conditions (e.g., host.group.name, service.technology).

---

Step 3 — Select the approach

Use the discovery outputs from Step 2 to select the first matching approach. Follow this order strictly.

Check 1 → Direct dimension filter

Condition: Step 2a shows the resolved condition is available as an enriched dimension on the mass data.

timeseries avg(dt.host.cpu.idle), filter:k8s.namespace.name == "my-ns" AND k8s.workload.name == "my-app"

This is the simplest and most performant path. Use it whenever possible.

Check 2 → getNodeField (same-node smartscape filter)

Condition: Step 2a shows a dt.smartscape.* dimension exists, and Step 2b shows the condition attribute is available on that node type, but the attribute is not an enriched dimension on the mass data.

timeseries avg(dt.host.cpu.idle), filter:getNodeField(dt.smartscape.host, "host.group.name") == "my-group"

Multiple conditions on the same node:

timeseries avg(dt.host.cpu.idle), filter:getNodeField(dt.smartscape.host, "host.group.name") == "my-group" AND getNodeField(dt.smartscape.host, "cloud.provider") == "aws"

Check 3 → in [smartscapeNodes] subquery (cross-node filter)

Condition: The condition targets a different node type than the data's smartscape dimension, or neither Check 1 nor Check 2 applies.

With dt.smartscape.* — project id:

timeseries avg(dt.host.cpu.idle), filter:dt.smartscape.host in [smartscapeNodes "PROCESS" | filter name == "Cassandra" | traverse edgeTypes: {runs_on}, targetTypes: {HOST}, direction: forward | fields id]

Pattern: start at the node type that carries the condition -> filter -> traverse to target node type.

Step 4 — Verify equivalence (MANDATORY — execute before delivering)

STOP. Execute the commands below now. Do not deliver the migrated query without verification evidence.

4a. Output shape check

Compare the columns/fields between the original and migrated query. They must match. If you renamed fields (e.g., entity.name -> name), alias them back to the original names.

4b. Probe run

Validate syntax, then run the migrated query with a short timeframe:

dtctl verify query '<migrated_query>' --plain

dtctl query '<migrated_query>' --plain

Check:

• Non-empty results: The query returns data. Zero rows when the original would return data means the approach selection or field mapping is wrong — go back to Step 2.
• Plausible values: Spot-check that metric values, entity names, and row counts are reasonable.

If the original query can still execute (deprecated constructs may still work temporarily), run both side-by-side and compare row counts and a sample of values.

4c. Document deviations

If exact equivalence is not achievable, add a leading comment:

/* Migration note: <what differs and why> */

---

Critical constraints

---

Checklist (condensed)

Use this as a sequential checklist. Each step has a required output.

1. Classify — Mass data query (Pattern A) or entity list sub-source (Pattern B)? -> output: pattern type 2. Resolve conditions — tag(X) -> Step 1A (dtctl get settings). Explicit predicate -> Step 1B (lookup table). -> output: list of (entity type, field, value) conditions 3. Discover fields — Execute dtctl query 'fieldsSnapshot ...' on the mass data source AND the smartscape node type. -> output: list of available enriched dimensions and node attributes 4. Select approach — Walk Check 1 -> Check 2 -> Check 3 using the discovery outputs. -> output: selected approach with rationale 5. Write query — Apply the selected approach. Include the original as a /* */ trailing comment. 6. Verify — Execute dtctl verify query then dtctl query on the migrated query, confirm non-empty results, check output shape matches original. -> output: verification evidence (row count, field comparison) 7. Deliver — Return the migrated query with mapping resolution and any open assumptions.

---

When to abandon

Return the original query with a /* */ comment explaining the closest approximation if:

• No viable approach exists for the resolved conditions.
• 3+ distinct approaches tried and failed.
• Verification (Step 4) shows non-equivalent results that cannot be reconciled.

/* Migration not completed: <reason>. Closest approximation: <what was tried>. */
<original query unchanged>

Migration Workflow

Contents

• Purpose
• Required Input
• Query Purpose Gate
• Step-by-Step Process
• Core Rules
• Signal and Event Rules
• Tag Matching Rules
• Traverse Guidance
• Output Expectations
• When to Load More References

Purpose

Use this workflow when converting classic or Gen2 entity-based DQL to Smartscape DQL.

This reference is based on the source prompt pack and keeps the same migration order, but reformats it for skill usage.

Required Input

The minimum required input is the classic DQL query.

Infer the intent, timeframe, relationships, output shape, and likely Smartscape replacements from the query itself. If something cannot be confirmed from the mapping references, state the assumption explicitly.

Query Purpose Gate

Before mapping types, determine what role entities play in the query.

• Entities serve only as a filter on mass data (timeseries, logs, metrics) — the real output is metric values, log records, or trace spans, and the entity condition merely narrows which data to include. Load mass-data-filtering-strategy.md and complete all steps — including the mandatory fieldsSnapshot discovery (Step 2) and equivalence verification (Step 4). Do not write the migrated query before running fieldsSnapshot. Return here only if you need entity-type mapping or relationship traversal to complete a Smartscape subquery.

• Entities are the primary output — the query lists, counts, or describes entities. This is a pure entity list query. Continue with the Step-by-Step Process below.

Step-by-Step Process

1. Consult mappings first. Do not skip this.

• type-mappings.md — classic entity type to Smartscape node type and field mappings
• relationship-mappings.md — valid edges per type

2. Detect the input pattern:

• fetch dt.entity.*
• classicEntitySelector(...)
• signal query with dt.entity.* dimensions
• event query using classic entity fields

3. Extract the important parts:

• entity types
• filters
• relationships
• projected fields
• timeframe

4. Map types, fields, and edges using the reference files. 5. Build the Smartscape query with the appropriate primitives:

• smartscapeNodes
• smartscapeEdges
• traverse
• filter
• fields, fieldsAdd, fieldsRemove
• getNodeField() and getNodeName() only when needed

6. Validate the translation:

• timeframe or topology lifetime changes
• missing or unsupported fields
• special cases such as host group or process group

7. Return the migrated query along with the mapping resolution and any open assumptions.

Core Rules

• Node types are uppercase and unquoted: smartscapeNodes HOST
• Do not use id_classic; use Smartscape id
• Prefer name over getNodeName() when querying nodes directly
• getNodeName() accepts only an ID; do not pass a type: argument
• Avoid entityAttr() and entityName() in the migrated query; use direct fields or getNodeField() / getNodeName() as needed
• | fields removes all other fields; use | fieldsAdd if you need to preserve existing ones
• Prefer dt.smartscape.<type> dimensions in signal queries
• smartscapeNodes supports from: and to: for historical topology queries
• Add explicit assumptions when the exact Smartscape equivalent is unclear

Signal and Event Rules

• Every dt.entity.* dimension in signal queries must be migrated to the correct dt.smartscape.* field
• This applies to:
• by:{}
• filter
• fieldsAdd
• expand
• helper functions using entity dimensions
• Event fields migrate as follows:
• affected_entity_ids → smartscape.affected_entity.ids
• affected_entity_types → smartscape.affected_entity.types
• dt.source_entity.type → dt.smartscape_source.type

Tag Matching Rules

• Node queries:
• classic in(tags, "[CONTEXT]key:value")
• becomes ` tags:renamedContext[key] == "value" `
• Signal queries:
• use getNodeField(dt.smartscape.<type>, "tags:<context>")[key] == "value"

Traverse Guidance

• Multiple targets:

  | traverse runs_on, {AWS_EC2_INSTANCE, AZURE_MICROSOFT_COMPUTE_VIRTUALMACHINES, GCP_COMPUTE_GOOGLEAPIS_COM_INSTANCE}

• Multiple edge types:

  | traverse {runs_on, belongs_to}, {AWS_AVAILABILITY_ZONE, AZURE_REGION}

• Chained traversal:
• HOST → VM → DATACENTER

fieldsKeep

fieldsKeep preserves source node fields through traversal. After traversal, id and name refer to the target node, and the source fields are available via dt.traverse.history.

smartscapeNodes CONTAINER
| traverse runs_on, HOST, direction:forward, fieldsKeep:name
| fieldsAdd
    containerName = dt.traverse.history[0][name],
    containerId = dt.traverse.history[0][id],
    hostId = id,
    hostName = name

Preserving entities without relationships

Use lookup when you must preserve entities even if the traversal has no match.

smartscapeNodes HOST
| lookup [
    smartscapeNodes HOST
    | traverse runs_on, {AWS_EC2_INSTANCE, AZURE_MICROSOFT_COMPUTE_VIRTUALMACHINES, GCP_COMPUTE_GOOGLEAPIS_COM_INSTANCE}, direction:forward
    | traverse {runs_on, belongs_to}, {AWS_AVAILABILITY_ZONE, AZURE_REGION, GCP_ZONE}, direction:forward, fieldsKeep:name
    | fieldsAdd dataCenter = id, dataCenterName = name, host_id = dt.traverse.history[0][id]
    | fields host_id, dataCenter, dataCenterName
  ], sourceField:id, lookupField:host_id, fields:{dataCenter, dataCenterName}
| fields id,
    dataCenter = coalesce(dataCenter, "NO_DATACENTER"),
    dataCenterName = coalesce(dataCenterName, "No Data center")

Output Expectations

Every final translation should include:

1. the Smartscape DQL in a code block 2. a Mapping Resolution section 3. open assumptions, if any 4. verification evidence — for Situation 1/2 migrations (mass data), include which fieldsSnapshot queries were run, the selected approach with rationale, and the result of the equivalence check (row count comparison, output shape match)

Suggested format:

## Mapping Resolution

Applied mappings:
- dt.entity.container_group_instance → CONTAINER
- dt.entity.host → HOST

Applied edge mappings:
- CONTAINER runs_on HOST

## Verification
- fieldsSnapshot on metrics confirmed `k8s.namespace.name` as enriched dimension
- Approach: direct dimension filter (Check 1)
- Probe: migrated query returned 42 rows over last 5m, matching original

When to Load More References

• Load dql-function-migration.md when the hard part is a specific function or pattern
• Load special-cases.md when the query mentions host group, process group, container group, or classic IDs
• Load examples.md when you need a before/after template

Quick Reference

Use this page as a compact cheat sheet during Smartscape migration.

Core rules

• Use smartscapeNodes, smartscapeEdges, and traverse for topology queries
• Smartscape node type values are uppercase and unquoted in smartscapeNodes
• Prefer Smartscape dimensions (dt.smartscape.<type>) in signal queries
• Prefer direct node fields like name; use getNodeName() only when you only have an ID
• Use getNodeField(dt.smartscape.<type>, "tags:<context>")[key] == "value" for tag matching in signal queries
• Classic tag filter in(tags, "[CONTEXT]key:value") becomes ` tags:renamedContext[key] == "value" ` in node queries
• Do not use id_classic; use Smartscape id
• | fields drops other fields; use | fieldsAdd when you need to preserve them

Traversal tips

• Multiple target types:

  | traverse runs_on, {AWS_EC2_INSTANCE, AZURE_MICROSOFT_COMPUTE_VIRTUALMACHINES, GCP_COMPUTE_GOOGLEAPIS_COM_INSTANCE}

• Multiple edge types:

  | traverse {runs_on, belongs_to}, {AWS_AVAILABILITY_ZONE, AZURE_REGION}

• Preserve source fields through traversal:

  | traverse runs_on, HOST, direction:forward, fieldsKeep:name

• Starting node after traversal:
• dt.traverse.history[0][id]

Event field updates

• affected_entity_ids → smartscape.affected_entity.ids
• affected_entity_types → smartscape.affected_entity.types
• dt.source_entity.type → dt.smartscape_source.type

Common gotchas

Mass data migrations require fieldsSnapshot before approach selection

Run fieldsSnapshot on both the mass data source and the smartscape node type before choosing direct dimension filter, getNodeField, or smartscapeNodes subquery. See mass-data-filtering-strategy.md Step 2.

Always verify equivalence

Run the migrated query with a short timeframe. Confirm non-empty results and matching output shape. See mass-data-filtering-strategy.md Step 4.

getNodeName() takes no type: argument

getNodeName(someId)

not:

getNodeName(someId, type: "HOST")

Host group is not an entity

Do not traverse to HOST_GROUP. Use host fields like dt.host_group.id on HOST.

All dt.entity.* dimensions must become dt.smartscape.*

Apply this everywhere in signal and event queries:

• timeseries by:{}
• filter
• fieldsAdd
• expand
• summarize by:{}

references is for static edges

Use references[...] when the relationship is static. Use traverse for general navigation.

smartscapeNodes supports from: and to:

Use historical topology when the classic query has an explicit timeframe.

Where to go next

• Full mappings: type-mappings.md
• Full edges: relationship-mappings.md
• Function migration: dql-function-migration.md
• Examples: examples.md

dt-migration references

Use these references with SKILL.md.

Read This First

1. Start with `../SKILL.md` for scope, use cases, and the Query Purpose Classification — this determines which path to take. 2. For mass data queries filtered by entity conditions (Situations 1 and 2), load `mass-data-filtering-strategy.md` before anything else. 3. For pure entity list queries (Situation 3), load `migration-workflow.md` for the step-by-step migration process. 4. Then choose the most relevant deep reference for the task at hand.

Reference Map

Related Skills

• Load dt-dql-essentials before writing final DQL.

Relationship Mappings

Use this reference to verify which Smartscape edges are valid when rewriting classic relationships to traverse, smartscapeEdges, or references.

Contents

• How to use this file
• Edge types
• Standardized edge types
• Examples
• Note on completeness

How to use this file

• Use traverse to navigate edges in topology queries
• Use smartscapeEdges when you want edge-centric records
• Use references[...] only for static edges

Edge types

Standardized edge types

Examples

Querying edges directly

smartscapeEdges "runs_on"
| filter source_type == "SERVICE" and target_type == "HOST"
| fields source_id, source_name = getNodeName(source_id), target_id, target_name = getNodeName(target_id)

Following an edge with traverse

smartscapeNodes HOST
| filter `tags:azure`[dt_owner_email] == "team-ops@example.com"
| traverse runs_on, SERVICE, direction:backward

Using references for static edges

smartscapeNodes NETWORK_INTERFACE
| fieldsAdd host = references[belongs_to.host]

Note on completeness

This file contains the migration-relevant edge set extracted from the source repository. If a migration depends on an edge not listed here, verify it directly in the target environment before assuming availability.

Special Cases

Use this reference before translating classic entity patterns literally. Several classic entity concepts are not modeled as standalone Smartscape node types.

Contents

• Host group
• Process group
• Container group
• Classic IDs
• Missing or planned mappings

Host group

dt.entity.host_group is not a separate Smartscape entity.

What to do instead

• query HOST
• use host fields such as dt.host_group.id
• if the classic query expects a host-group ID that no longer exists as a standalone entity, preserve the output shape with null or use the host-group name if grouping still requires a value

Example

Classic:

fetch dt.entity.host
| fields id, entity.name, hostGroupName

Smartscape:

smartscapeNodes HOST
| fields id, entity.name = name, hostGroupName = `dt.host_group.id`

Process group

dt.entity.process_group is not a separate Smartscape entity.

What to do instead

• query PROCESS
• use dt.process_group.id, dt.process_group.name, or dt.process_group.detected_name
• summarize if you need one row per process group rather than one row per process

Example

Classic:

fetch dt.entity.process_group
| fields id, entity.name, metadata

Smartscape:

smartscapeNodes PROCESS
| summarize by:{ id = dt.process_group.id, entity.name = dt.process_group.detected_name }, process.metadata = takeAny(process.metadata)

Container group

dt.entity.container_group is not a separate Smartscape entity.

What to do instead

• treat dt.entity.container_group_instance as CONTAINER
• when the classic query asks for container-group identity or name, preserve the output shape with null placeholders if there is no real Smartscape equivalent

Example

Classic:

fetch dt.entity.container_group_instance
| fields
    id,
    containerGroupId = instance_of[dt.entity.container_group],
    containerGroupName = entityName(instance_of[dt.entity.container_group], type:"dt.entity.container_group")

Smartscape:

smartscapeNodes CONTAINER
| fields
    id,
    containerGroupId = null,
    containerGroupName = null

Classic IDs

Classic entity IDs do not carry over automatically to Smartscape IDs. The suffix changes.

Rules

• do not reuse classic entity IDs blindly
• do not use id_classic
• use Smartscape id
• if the correct Smartscape ID is unknown, add an explicit assumption and a lookup hint

Example lookup hint:

smartscapeNodes HOST
| fields id, name

Missing or planned mappings

The mapping table distinguishes between:

• available — direct mapping is already known
• planned — a Smartscape replacement is expected but may not be fully usable yet
• missing or unclear — direct replacement is not confirmed
• not planned — do not expect a direct Smartscape entity replacement

Guidance

• If the mapping is available, translate directly.
• If the mapping is planned, translate cautiously and call out the assumption.
• If the mapping is missing or unclear, avoid pretending the mapping is certain.
• If the mapping is not planned, work around it with fields, placeholders, or a different starting entity.

Related references

• type-mappings.md — full table and status values
• entity-host.md — host and host-group migration patterns
• entity-process.md — process-group-instance and process-group patterns
• entity-container.md — container migration patterns

Type and Field Mappings

Use this reference when you need the full classic-to-Smartscape mapping set.

Contents

• How to read this table
• Type mappings
• Special cases: entities that are no longer standalone types
• Field mappings
• Related references

How to read this table

• Classic entity type and field name appears in classic queries such as fetch dt.entity.<type> or signal filters using dt.entity.*
• Smartscape id field name is the signal or helper field to use in Smartscape-aware signal queries
• Smartscape type is the node type used with smartscapeNodes
• Status indicates how certain the mapping is:
• available — already available
• planned — expected to be available
• unclear — direct mapping not confirmed
• not planned — no direct Smartscape replacement should be assumed

Type mappings

Special cases: entities that are no longer standalone types

Host group

Example:

smartscapeNodes HOST
| fields id, entity.name = name, hostGroupName = `dt.host_group.id`

Process group

Example:

smartscapeNodes PROCESS
| summarize by:{ id = dt.process_group.id, entity.name = dt.process_group.detected_name }, process.metadata = takeAny(process.metadata)

Container group

dt.entity.container_group_instance still maps to CONTAINER.

Field mappings

Use these field migrations when the classic field name, not just the entity type, needs updating.

Related references

• special-cases.md
• dql-function-migration.md
• entity-cloud-application.md