@dynatrace-sdk/dqlint

A simple and efficient DQL (Dynatrace Query Language) formatter.

Features

For the complete rule reference with before/after examples see docs/rules.md.

Command layout

• Each | command is placed on its own line.
• The first argument stays on the command line; subsequent arguments align beneath it.
• Named (key: value) arguments and block arguments use a two-space indent from the command, and all later arguments in the same command follow that indent.
• fetch, smartscapeNodes, and smartscapeEdges stay single-line; all other leading commands split per argument.
• Multi-line function-call arguments align under the opening parenthesis.

Blocks and subqueries

• Single-element { } blocks get a space inside; single-element [ ] blocks don't.
• Multi-element blocks expand to one element per line with indentation.
• Subqueries inside [ ] are formatted recursively with the same rules as a top-level query.

Spacing

• Commas are followed by a single space (unless a line break follows).
• Semantic colons (key:) get a trailing space; URL colons (://) and namespace colons (dt.entity:type) are left untouched.
• Assignment and comparison operators (=, ==, !=, <=, >=, =~) get one space on each side.
• Binary arithmetic operators (+, -, *, /) get one space on each side; unary signs on numeric literals and durations are left attached.
• The @ time-alignment operator (e.g. -2h@h) is written without surrounding spaces.

Preserved content

• Quoted strings ("…", '…', `…`) are never modified.
• Template variables (${…}) are passed through verbatim.
• Line comments (//) are passed through verbatim.
• Multiple consecutive blank lines are collapsed to at most one.
• Trailing comments and blank lines at the end of a command stay at the left margin.

Usage

@dynatrace-sdk/dqlint has three independent surfaces. Use whichever fits your workflow:

| Surface | When to use | |---|---| | Library | Format DQL strings programmatically inside application code. | | CLI | Scan and fix DQL strings in source files, or format a query on the command line. | | Prettier plugin | Auto-format DQL on save in your editor via Prettier. |

Library

Installation

npm install @dynatrace-sdk/dqlint
# or
yarn add @dynatrace-sdk/dqlint
# or
pnpm add @dynatrace-sdk/dqlint

Usage

Import formatDql and call it with any DQL string. The function is stateless and pure: the same input always produces the same output.

import { formatDql } from '@dynatrace-sdk/dqlint';

const formatted = formatDql(
  'fetch logs | filter loglevel == "ERROR" | limit 10',
);
console.log(formatted);
// fetch logs
// | filter loglevel == "ERROR"
// | limit 10

CLI

The CLI scans source files for DQL strings, reports their formatted versions, and can rewrite them in place.

Prerequisites

The CLI requires Node.js. Install the package as a project dev dependency so the dqlint binary is available via npx or as an npm script:

npm install --save-dev @dynatrace-sdk/dqlint
# or
yarn add --dev @dynatrace-sdk/dqlint
# or
pnpm add --save-dev @dynatrace-sdk/dqlint

Note: Running npx dqlint without a prior installation will download the package on demand, which works for one-off use but is slower and doesn't pin a version. For CI or pre-commit hooks, install it as a dev dependency.

Usage

npx dqlint <path...> [--ext=.ts,.tsx] [--fix] [--add-dql-tag]

<path...> accepts one or more files or directories. Directories are scanned recursively.

Add it as an npm script for convenience:

{
  "scripts": {
    "dqlint": "dqlint src"
  }
}

Supported file extensions

By default dqlint scans .txt, .dql, .js, .jsx, .ts, and .tsx files. Override with --ext:

dqlint src --ext=.ts,.tsx   # only TypeScript files
dqlint src --ext=ts,tsx     # dots are added automatically

Fixing files in place

The --fix flag rewrites each file with formatted DQL strings replacing the originals:

dqlint src --fix

Adding dql tags

The --add-dql-tag flag wraps detected DQL strings with the dql template tag and inserts the corresponding import statement. This is the recommended migration step before enabling the Prettier plugin:

dqlint src --add-dql-tag

Input:

const query = `fetch logs | filter loglevel == "ERROR"`;

Output:

import { dql } from '@dynatrace-sdk/dqlint';

const query = dql`fetch logs | filter loglevel == "ERROR"`;

Note: --add-dql-tag converts single- and double-quoted strings to template literals, because the dql tag only works with template literals.

Combine --fix and --add-dql-tag to format and tag in one pass:

dqlint src --fix --add-dql-tag

Raw string mode

Format a DQL string directly without reading any files:

dqlint --raw "fetch logs | filter loglevel == \"ERROR\" | limit 10"

Each argument after --raw is formatted and printed to stdout. Useful for quick checks or editor integrations.

Exit codes

| Code | Meaning | |---|---| | 0 | Success: files were processed or raw strings were formatted. | | 1 | Incorrect usage: no paths provided, no strings in --raw mode, or no matching files found. | | 2 | File or path not found. | | 3 | Unexpected error reading a file. |

Prettier Plugin

The Prettier plugin formats DQL automatically on save inside tagged template literals, commented template literals, and .dql files.

Prerequisites

• prettier must be installed in your project (declared as an optional peer dependency).
• The package itself must be installed.

Installation

npm install --save-dev @dynatrace-sdk/dqlint prettier
# or
yarn add --dev @dynatrace-sdk/dqlint prettier
# or
pnpm add --save-dev @dynatrace-sdk/dqlint prettier

Configuration

Add the plugin to your .prettierrc:

{
  "plugins": ["@dynatrace-sdk/dqlint/prettier-plugin"]
}

The plugin is published as a separate subpath export (/prettier-plugin) so that application code importing only formatDql or the dql tag doesn't transitively pull Prettier into the consumer bundle.

Usage

The plugin formats DQL inside any of the following:

Tagged template literals are the preferred approach. Import the dql tag from the package root (it's a tiny, dependency-free identity function and doesn't pull in Prettier):

import { dql } from '@dynatrace-sdk/dqlint';

const query = dql`fetch logs | filter loglevel == "ERROR" | limit 10`;

After running Prettier:

const query = dql`fetch logs
| filter loglevel == "ERROR"
| limit 10`;

Commented template literals are for when you can't add the dql tag:

const query = /* dql */ `fetch logs | filter loglevel == "ERROR" | limit 10`;

.dql files: standalone DQL files are formatted as a whole:

fetch logs | filter loglevel == "ERROR" | limit 10

To add dql tags to an existing codebase automatically, see --add-dql-tag in the CLI section.

Development

1. Install dependencies: pnpm install
2. Build: pnpm nx build dqlint
3. Run tests: pnpm nx test dqlint
4. Lint: pnpm nx lint dqlint

Help

Questions or feedback? Join #help-dqlint on Slack.