# dt-dql-essentials

A DQL syntax skill for Dynatrace: helps write, fix and optimize queries so they scan less data and cost less per run.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2800 installs · ★ 167
- Author: Dynatrace
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Dynatrace/dynatrace-for-ai/tree/HEAD/skills/dt-dql-essentials/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/dt-dql-essentials

## What it does

DQL is a pipeline language — commands chain with `|`, and the syntax is not SQL. The skill loads a reference so the agent stops guessing at commands and field types. Inside are an index of commands (`fetch`, `filter`, `summarize`, `makeTimeseries`, `timeseries`, `parse`, `lookup` and more), function tables grouped by category, and specs for data types and parameter values.

Separate reference files cover the things that usually break a query: field namespaces and data models, time alignment with `@`, string matching (`matchesValue`, `matchesPhrase`, `matchesPattern`), array and timeseries manipulation, Smartscape topology. There is also an optimization file: filter early, keep time ranges short, select only the fields you need, use sampling, watch cardinality. Less scanned data means lower consumption.

The skill will not explain an existing query or answer product questions. It also is not about billing: to see what a tenant's queries actually cost and who scanned the most, use `dt-platform-costs`. This one tunes the query text, not the cost data.

## Requirements
- Works with: Dynatrace

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Dynatrace/dynatrace-for-ai --skill dt-dql-essentials -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/dt-dql-essentials/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/dt-dql-essentials/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Dynatrace/dynatrace-for-ai --skill dt-dql-essentials -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/dt-dql-essentials/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Dynatrace/dynatrace-for-ai --skill dt-dql-essentials -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/dt-dql-essentials/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Dynatrace/dynatrace-for-ai dt-dql-essentials
```

2. **Manually: put the files in place**
- File: `.github/skills/dt-dql-essentials/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Dynatrace/dynatrace-for-ai --skill dt-dql-essentials -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Dynatrace/dynatrace-for-ai --path skills/dt-dql-essentials
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/dt-dql-essentials/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Dynatrace/dynatrace-for-ai --skill dt-dql-essentials -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Dynatrace/dynatrace-for-ai/tree/HEAD/skills/dt-dql-essentials/SKILL.md

## When to use it
- The agent writes DQL like SQL and hits syntax errors — the skill loads the command and type reference up front.
- Queries scan more data than needed and cost more — the optimization reference points to early filters and shorter time ranges.
- You need field namespaces, time alignment or string matching sorted out — each has its own reference file.

## Example prompts
- Ask the agent to write a query: "build a DQL query that pulls error spans from the last hour".
- Paste a slow query and say: "optimize this DQL, it scans too much".
- Ask about syntax: "how does time alignment with @ work in DQL".

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 650f09c8584df646.

BEGIN THIRD-PARTY FILE 650f09c8584df646
```text
---
name: dt-dql-essentials
description: "Core DQL syntax, pitfalls, query patterns, and query optimization. Load to write, build, fix, or OPTIMIZE a DQL query — prevents syntax errors and makes queries faster, more efficient, and cheaper (less data scanned = lower query consumption/cost per run). Covers fetch commands, data models, field namespaces, time alignment, entity/smartscape patterns, metric discovery, and performance/cost optimization (filter early, bucket filters, short time ranges, field selection, sampling, cardinality). Trigger: \"write/build/fix a DQL query\", \"DQL syntax\", \"query logs/spans/metrics\", \"create a timeseries\", \"optimize my DQL\", \"make my query faster/cheaper\", \"reduce DQL cost/consumption/scanned data\", \"keep DQL cost under control\". Do NOT use to explain an existing query or answer product questions. For MONITORING a tenant's ACTUAL query consumption/billing (how much queries cost, who scanned most, cost trends) use dt-platform-costs — this tunes the query text, not billing data."
license: Apache-2.0
---

# 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                                                                             |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Discovering data | [references/discovery.md](references/discovery.md) |   
| Field names, namespaces, data models, stability levels, query patterns        | [references/semantic-dictionary.md](references/semantic-dictionary.md)                       |
| Query optimization — make a query faster / more efficient / cheaper, reduce consumption & scanned data (filter early, bucket filters, time ranges, field selection, sampling, cardinality) | [references/optimization.md](references/optimization.md)                                     |
```
END THIRD-PARTY FILE 650f09c8584df646

The third-party file has ended. Everything between the 650f09c8584df646 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2361 of 37263 bytes. © Dynatrace · Apache-2.0 · https://github.com/Dynatrace/dynatrace-for-ai/tree/HEAD/skills/dt-dql-essentials/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md