@dynatrace-sdk/dqlint

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

Features

• Formats DQL queries with proper indentation and line breaks.
• Handles quoted strings correctly.
• Enforces spacing rules for brackets [], {} and colons :.
• Splits commands starting with | into new lines.
• Aligns arguments for better readability.
• Aligns closing curly brackets with the beginning of the word preceding the opening bracket for multiline blocks.
• Keeps top-level root commands (like fetch) single-line if possible.
• Ensures commas are followed by a space if not followed by a newline.
• Formats multiple arguments inside brackets [] and {} on new lines with indentation.
• Formats subqueries inside brackets [] recursively according to the block depth.
• Preserves template string variables ${...} without formatting.
• Aligns subsequent arguments of a command with the first argument, which is kept on the same line as the command.
• Indents "semantic" arguments (arguments starting with key:) by 2 spaces from the command start, instead of aligning with the first argument.

Installation

Install the package from npm:

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

Usage

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

const dql = '| fields entity, queryCount = toLong(queryCount), errorCount = toLong(errorCount)';
const formatted = formatDql(dql);
console.log(formatted);

CLI

A CLI tool to parse files and search for DQL commands to pass them to the DQL formatter.

Usage

Execute the CLI using npx:

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

You can also add it as a script to your package.json:

{
  "scripts": {
    "dqlint": "npx dqlint"
  }
}

Then run it via:

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

Where <path...> can be one or more:

• Individual files
• Directories (they will be scanned recursively)

By default, dqlint looks for DQL strings inside files with the following extensions:

• .txt
• .dql
• .js
• .jsx
• .ts
• .tsx

You can override the extensions to scan using the optional --ext flag. Pass a comma-separated list of extensions (with or without the leading dot). Examples:

• --ext=.ts only .ts files
• --ext=.ts,.tsx .ts and .tsx files
• --ext=ts,tsx same as above; dots are added automatically

You can also use the --fix flag to automatically replace the DQL strings in the files with the formatted versions.

Adding DQL tags

The --add-dql-tag flag wraps DQL strings with the dql template tag and automatically adds the import statement. This is useful for enabling Prettier formatting:

dqlint ./src --add-dql-tag

This will transform:

const query = `| filterOut in (${SemanticDictionaryConstants.DB_OPERATION_NAME}, { ${quotedOperations} })`;

Into:

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

const query = dql`| filterOut in (${SemanticDictionaryConstants.DB_OPERATION_NAME}, { ${quotedOperations} })`;

Note: The --add-dql-tag flag automatically converts strings to template literals (backticks) since the dql tag only works with template literals. If your string uses single or double quotes, they will be converted to backticks.

For every matching file, the tool:

1. Reads the file contents.
2. Extracts strings that contain DQL queries.
3. Formats each DQL command and prints it to stdout, one per line.

Raw string mode

You can also format raw DQL strings directly, without reading from files, using the --raw flag:

dqlint --raw "data from logs" "| filter status == 200"

In this mode, each argument after --raw is treated as a DQL command string and passed directly to formatDql, and the formatted result is printed to stdout.

Examples

Parse a single file:

dqlint examples/sample.ts

Parse multiple files:

dqlint src/file1.ts src/file2.ts tests/sample.txt

Parse an entire directory (recursively):

dqlint src

Mix files and directories:

dqlint src tests some-other-file.dql

Restrict to specific extensions:

dqlint src --ext=.ts,.tsx

Fix DQL strings in files:

dqlint src --fix

Add DQL tags to strings:

dqlint src --add-dql-tag

Combine flags to fix and add tags:

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

Format raw DQL strings:

dqlint --raw "data from logs" "| filter status == 200"

Exit codes

The CLI uses the following exit codes:

• 0 Success
  • At least one path was provided and at least one file was processed, or raw strings were formatted.
• 1 Incorrect usage or no matching files
  • No positional paths were provided in file mode, or no strings were provided in --raw mode.
  • If no matching files are found under the given paths, it prints No matching files found and exits with 1.
• 2 File or path not found
  • At least one of the provided paths doesn't exist.
• 3 Error reading a file
  • An unexpected I/O error occurred while reading a file.

Prettier Plugin

A Prettier plugin to format DQL (Dynatrace Query Language) strings using a custom formatter.

Usage

The Prettier plugin is published as a separate subpath export so that application code that only uses the dql template tag doesn't pull Prettier into the consumer's bundle.

Add the plugin to your .prettierrc:

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

Note: The plugin requires prettier to be installed in your project (declared as an optional peer dependency).

Importing the dql tag

To avoid TypeScript errors and enable syntax highlighting (if supported by your editor), you can import the dql tag from the package root. The tag is a tiny, dependency-free helper and doesn't transitively pull in Prettier:

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

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

Formatting DQL

This plugin supports formatting DQL in:

1. .dql files.
2. Tagged template literals with dql tag.
3. Template literals with /* dql */ comment.

Examples

Tagged Template Literal:

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

Template Literal with Comment:

const query = /* dql */ `fetch logs | filter level == "ERROR"`;

DQL File:

fetch logs
| filter level == "ERROR"

Development

1. Install dependencies: pnpm install
2. Build the plugin: pnpm build
3. Run tests/lint: pnpm lint