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.
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 barItem | 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 |
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 |
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.
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). |