DevOps query language (DQL)

Use the DevOps query language to filter the information displayed in your value stream.

About the DevOps query language

The DevOps query language is a search tool designed to filter value streams. You build simple queries by combining searchable items with operators and values. A searchable item is a query-able object, such as issue.status. Nearly all HCL Accelerate database fields are query-able, and you can search across nested objects, for example, issue.project.name.

Query scope

Queries can be scoped to the entire value stream or a stage. You can create queries on the Value stream view, or define them in the value_stream_name-vsm.json file attached to a value stream. Each stage can have a query defined for it.

You set the scope of a query at the value stream level by defining a query in the header of the value_stream_name-vsm.json file or on the Value stream view. You might do this if you have a shared Jira® instance, for example, and want to restrict the displayed issues to those that belong to your team. For example, issue.project.name="my_jira_project".

If you set the scope to the stream level, other queries work within that scope. After you set the scope to the value stream level, you cannot override it by defining a new stream-level query on the Value stream view. To change a value stream scoped query, replace the query in the value_stream_name-vsm.json file.

Simple queries

Filter your value streams with queries that restrict the displayed information to the things that you want to see. You build simple queries with the DevOps query language by combining searchable items with operators and values. A searchable item is a query-able object, such as issue.status. The query format consists of an item, a period, a query-able parameter, an operator, and a value of a valid type:

[item].[field] [operator] [value type]

The following list displays some typical queries:

issue.status = “In Progress”
issue.owner = “John Doe”
pr.number > 5
issue.status != Done
build.endTime < 1d
issue.created > 10d
issues.sprints.name = "sprint 1"

Value types are case insensitive. Text value types can be enclosed in single- or double-quotes.

A list of searchable objects, or items, are provided later in this topic.

Combining queries

You can combine simple queries by using the logical operators ‘and’ and ‘or’. Combined queries are resolved in left-right order.

The following query displays issues for Jane and John Doe with the status of 'In Progress' .

issue.owner = “John Doe” or issue.owner = “Jane Doe” and issue.status=“In Progress”

The following query displays items with the status of "Open," and that are older than one day.

pr.status = Open and pr.created > 1d

Priority queries

You can override the default order of precedence by using parenthesis.

Unlike the earlier example, this example displays all issues owned by John Doe, and only issues owned by Jane Doe with the status of "Done."

issue.owner = “John Doe” or (issue.owner = “Jane Doe” and issue.status=Done)

This example displays John Doe's open issues and with the status of "In Progress."

(issue.status = “In Progress” or pr.status = open) and issue.owner = “John Doe”

Elements of the DevOps query language

Use items in table to search in their query-able fields. Time-type fields are shown in italicized font.

The below table lists all the DevOps queries that you can use in stages of value_stream_name-vsm.json file. Using the query, you can view the data of an application integrated in value stream.

Table 1. Searchable items - stages of value_stream_name-vsm.json
Table 1. Searchable items - stages of value_stream_name-vsm.json
Item Query-able fields
issue count, status, labels
issue.comments count
issue.labels count
issue.project id, key, name. For example, issue.project.name="my_project". Note: A project is a group of issues that include Jira: stories, bugs, tasks, and epics for a product, service, or activity.
issue.sprints active, count
pr count, labels, repositoryId, repositoryName, repositoryOwner, source, status
pr.approvals count
pr.assignees count
pr.comments count
pr.labels count
pr.reviewers count
pr.reviews count
commit count, repositoryId, repositoryName, repositoryOwner, source
build count, status, type
deployment count, env, environmentId, source, status

The below table lists all the DevOps queries that you can use to search in Value stream view. Using the query, you can search in search bar to filter the required dots in Value stream view.

Table 2. Searchable items - Value stream view search bar
Table 2. Searchable items - Value stream view search bar
Item Query-able fields
feature created, creator, id, name, status, url
issue count, components, id, name, sprints, storyPoints, source, status, owner, priority, type, created, lastUpdate, labels
issue.comments count, comment, created, updated
issue.labels count
issue.project id, key, name. For example, issue.project.name="my_project". Note: A project is a group of issues that include Jira: stories, bugs, tasks, and epics for a product, service, or activity.
issue.rawIssue The rawIssue field contains non-normalized data from the external tool, such as Jira. For example, issue.rawIssue.fields.custom_field.
issue.releases id, name, description, archived, released, releaseDate. Several typical examples include, issue.releases.name="Version 1.1", issue.releases.releaseDate > 5w, issue.releases.released = false . Note: A release is a deployment to an environment.
issue.sprints active, count, id, name, previous, description, startTime, endTime, completeTime, url
pr count, id, labels, name, source, status, branch, baseBranch, commitId, merged, assignees, reviewers, created, lastUpdate, creator, number, repositoryId, repositoryName, repositoryOwner,
pr.approvals count
pr.assignees count
pr.comments count, comment, created, updated
pr.labels count
pr.reviewers count
pr.reviews count
commit repositoryId, repositoryName, repositoryOwner, source
build count, id, name, source, status, endTime, requestor, startTime, number, type
deployment count, id, name, source, status, endTime, requestor, startTime, number, env
Note: A feature is a collection of stories and equivalent to an Epic in Jira.

The query operator tables displays search operators.

Table 3. Query operators
Operator Definition
= equal
> greater then
< less than
>= greater than or equal to
<= less than or equal to
!= not equal
"" required for exact phrase match with spaces
( ) order of operations grouping
AND or and conjunction for searching both values
OR or or disjunction for searching one value or another
IN disjunction for searching one value or another.
Note: The IN operator is shorthand for the OR operator. Use the IN operator to avoid using multiple OR operators when you query in the same field.

The value types table describes the valid value types.

Table 4. Value types
Value type Definition
value Supports any characters except whitespace or the following reserved characters : . = ! < > “ ( )
quoted value Characters are wrapped in double quotes. This type supports any character including those unsupported by value. For example: “This is a quoted value”, “(This = valid input!)”
time Use to compare time fields. Valid input is a number followed by a measure of time, (h = hours, d = days, w = weeks, y = years. For example:1w (one week), 10d (ten days), 3y (three years).