DevOps Query language#

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.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.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.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#

The searchable items table lists the objects that you can search and their query-able fields. Time-type fields are shown in italicized font.

Item Query-able fields
issue id, name, sprints, storyPoints, source, status, owner, priority, type, created, lastUpdate, labels
issue.comments comment, created, updated
issue.project id, 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 id, name, previous, description, startTime, endTime, completionTime, url, active
pr id, name, source, status, branch, baseBranch,commitId, merged, assignees, reviewers, created, lastUpdate, creator, number
pr.comments comment, created, updated
build id, name, source, status, endTime, requestor, startTime, number
deployment id, name, source, status, endTime, requestor, startTime, number, env

The query operator tables displays search 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

The value types table describes the valid 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).|

Parent topic: Value stream management