Last updated
© 2024 Ketryx Corporation
Last updated
The Ketryx Query Language (KQL) is a language to query configuration items in the Ketryx Platform.
Items can be filtered based on their field values, relations, and various other metadata.
Ketryx separates between "full" KQL and Simplified KQL, which is subset of KQL that focuses on filtering for item types, relations, and particular core item data. This is
When using KQL in the Ketryx web application or document templating engine, full KQL can be used
When using KQL within Ketryx organization/project configurations, only simplified KQL can be used (e.g. when setting up cross-project references)
This document describes the full feature set of KQL, but will specifically denote features that are not supported by Simplified KQL.
Some frequently used examples:
KQL consists of expressions which contain the following elements:
Symbols are represented by any individual tokens that are not wrapped in quotes (which would make them strings). They can not contain whitespace or certain other special characters such as (
, )
, :
, "
.
Strings are pieces of text wrapped in quotes ("..."
).
Boolean operators are keywords (or
, and
, not
) or special characters (||
, &&
, !
) to combine expressions into an overall boolean meaning.
Groups are wrapped in parentheses ((...)
).
Sequences are formed by expressions following each other, optionally delimited by a comma (,
).
Filters are denoted by a filter name (a string or symbol) followed by one or more arguments (other expressions) delimited by :
.
Symbols are identifiers that are not strings or special keywords (such as and
, or
, and not
). Symbols can not contain the following special characters:
"
:
,
(
, )
[
, ]
&
, |
, !
whitespace (spaces, tabs, newlines)
The following symbols are treated specially when matching items (note that these special cases are case-sensitive):
*
matches any item
none
matches no item
Shorthand for the id:
filter:
Jira issue keys (e.g., SAMD-12
)
Ketryx item references (KXITM...
)
Ketryx item record references (KXREC...
)
Shorthand for the type:
filter:
Item type short names (e.g., RQ
, SW
, TE
)
Shorthand for the is:risk-control
filter:
RC
(denoting a risk control)
Besides these special cases, symbols are treated like strings and are matched against the title of an item (in a case-insensitive way).
Strings are wrapped in (double) quotes ("
).
Strings are matched against the title of an item, in a case-insensitive way. For instance, "text"
matches any item whose title contains text
, Text
, TEXT
, etc.
Note that single quotes ('
) and similar characters such as typographic "curly" quotes (‘
, ”
, etc.) are not treated as string delimiters in KQL. This can sometimes lead to surprising consequences when copying and pasting text in environments that automatically replace straight quotes with curly quotes.
Boolean operators are evaluated in the following order of decreasing precedence: not
before and
before or
. For instance,
is equivalent to:
Boolean operators can also be written in upper-case (NOT
, AND
, OR
), or using the special characters !
(not
), &&
(and
), and ||
(or
).
For instance,
can also be written as:
Depending on the operand, the operators and
and or
can be omitted entirely (see Sequences below).
Expressions following each other without an explicit boolean operator form a sequence. They can optionally be delimited by a comma (,
).
If not indicated otherwise, the individual expressions are combined using a boolean operator, depending on the type of expressions involved:
Symbols referring to mutually exclusive filters are combined using a logical or. For instance, SAMD-1 SAMD-2
refers to an ID-based filter; since each item can only have one ID, the individual expressions are combined using a logical or, making the sequence equivalent to SAMD-1 or SAMD-2
, i.e., match all items with an ID of either SAMD-1
or SAMD-2
. This includes the following kinds of symbols:
Jira issue keys (e.g. SAMD-1
)
Jira issue numbers (e.g. 1
)
Ketryx item IDs (KXITM...
)
Ketryx record IDs (KXREC...
)
Item type short names (e.g., RQ
, SW
)
Otherwise, the elements in the sequence are combined using a logical and. For instance, RQ RC
refers to filters for item types and risk controls (which are not mutually exclusive), i.e., match all items that are of type Requirement and a risk control.
This usually matches one's intuition and makes simple queries based on IDs or pieces of text more concise. However, when in doubt, one can always write queries with explicit logical operators.
An empty sequence ()
matches no items. However, if the overall query is empty, all items are matched.
Some filters take a sequence of symbols or strings as parameters (string lists), e.g., diff:(new,changed)
. These are special in the sense that they don't allow arbitrary logical combinations or complex nested expressions.
Filters allow for powerful query criteria, based on various attributes of an item and relations among items.
In the specifications below, UPPER-CASE
parts denote placeholders for other expressions, typically arbitrary query expressions.
Some filters expect a string list in certain parameters, which can be a single string or symbol (e.g., just new
), or a sequence of strings or symbols (e.g., (new,changed)
or ("new","changed")
). Symbols and strings can generally be used interchangeably; strings have to be used when referring to values that contain spaces or other special characters. (The examples in this documentation generally use the shorter symbol form if possible, and the string form otherwise.)
Users can be referenced using their full name (e.g. "John Doe"
) or email addresses (e.g. john@example.com
). Generally, email addresses should be preferred since they are guaranteed to be unique. The special value me
denotes the calling user.
to:ITEMS
, to:DEPTH:ITEMS
Items with a relation to a set of other (target) items, optionally filtering for a certain level of depth.
ITEMS
is an arbitrary query expression to filter for allowed targets of the relation. This expression might involve other, nested filters for relations.
DEPTH
is an optional parameter to specify a restriction on the relation depth:
*
: allows any depth of least 1
1
: allow a depth of exactly 1, i.e. only direct relations
N
: allows a depth of up to N
(where N
is an integer number)
(MIN MAX)
or (MIN, MAX)
: allows a depth of at least MIN
up to MAX
(where MIN
and MAX
are integer numbers; MAX
can also be *
)
The short form to:ITEMS
is equivalent to to:1:ITEMS
, while to::ITEMS
is equivalent to to:*:ITEMS
.
Note that, by default, this filter does not include the target items themselves; e.g., to:TC
matches all items that have a relation to a Test Case, without including those Test Cases themselves. To include them, specify a MIN
level of 0, e.g.:
from:ITEMS
, from:DEPTH:ITEMS
Items with a relation from a set of other (source) items, optionally filtering for a certain level of depth.
Other than referring to the opposite relation direction, this works just like the to:
filter.
diff:KINDS
Not supported by Simplified KQL
Items with a difference (compared to another version) of a certain kind.
KINDS
is , with the following values:
new
changed
removed
same
id:ID
Items with a certain ID.
ID
is a string list containing one or more item IDs, which can be one of the following:
Jira issue key (e.g., SAMD-42
)
Jira issue number (e.g., 42
)
Ketryx item ID (e.g., KXITM5QFTEHESAE8P8R9256PX60YXRS
)
Ketryx item record ID (e.g., KXREC4KX77X9CER95WV7F96XBNP2WQX
)
type:TYPES
Items of a certain type.
TYPES
is a string list containing one or more item type names or short names. In the default Ketryx configuration, the following names can be used:
RQ
= Requirement
SW
= "Software Item Spec"
TSK
= Task
TC
= Test Case
TE
= "Test Execution"
AN
= Anomaly
CMPL
= Complaint
CR
= "Change Request"
CAPA
RISK
= Risk
HW
= "Hardware Item Spec"
state:STATES
, status:STATES
Items in a certain state (or with a certain Jira status).
STATES
is a string list containing one or more state names. In the default Ketryx configuration, the following names can be used:
Open
Reopened
"In Progress"
Resolved
Closed
Custom status names (if configured) can also be used.
As a courtesy, status:
is an equivalent alias for state:
.
is:FLAG
Items matching a certain (boolean) flag.
FLAG
can be one of the following:
controlled
: matches controlled items
deleted
: matches deleted items
risk-control
: matches items that are risk controls; this is equivalent to the relation-based filter "risk-controls":*
Not supported by Simplified KQL:
checked
: matches checked items, i.e. items that need to be controlled (which does not include deferred items)
deferred
: matches deferred items
unresolved
: matches items that are not deferred, not deleted, not controlled, and whose state is neither closed nor resolved
project:PROJECT
Items that are in the given project(s).
This can be useful to filter out items from referenced projects, as opposed to items in the current ("main") project.
PROJECT
is a string list containing one or more project names or Ketryx project IDs. The special value selected
denotes the current project.
in-test-plan:VERSION
Not supported by Simplified KQL
Items that are included in the test plan of a given version.
VERSION
is a string list containing one or more version names or SemVer version numbers. The special value selected
denotes the currently selected version.
updated-after:ISO_DATE_STRING
Items with a record creation date equals or after the provided ISO 8601 date.
Examples:
updated-after:"2024-01-01"
(Date with its time set to 00:00
)
updated-after:"2024-05-05T10:00"
(Date with explicit time component)
assignee:USER
, owner:USER
Items with a given assignee.
USER
is a string list containing one or more user references, which can be given as full names or email addresses (or the special symbol me
).
As a courtesy, owner:
is an equivalent alias for assignee:
.
approved:GROUPS
Not supported by Simplified KQL
Items approved by the given users or groups.
GROUPS
is a string list containing one or more user references or group names. Just like in the assignee:
filter, users can be referenced by full name or email address (or the special symbol me
).
owner
refers to approval by the owner (= assignee) of the item.
full
refers to full approval by all required approval groups (including the owner if necessary).
For group names, the following shorthand values for the standard Ketryx-defined groups are supported:
RD
= "R&D Leads"
PM
= "Product Managers"
QM
= "Quality Managers"
DEV
= Developers
QC
= "Quality Control"
A filter of the form
or
queries items with a given relation to or from a set of other items, optionally filtering for a certain level of depth.
RELATION
is a relation name. The following relations are supported (each specifying the "forward" relation from source to target, and the "reverse" relation in the other direction):
contains
/ "is contained in"
(as specified by field Contained tests)
"found anomaly"
/ "was found by"
(field Found anomalies)
fulfills
/ "is fulfilled by"
(field Fulfilled requirements)
"has parent"
/ "has child"
(fields Parent requirements, Parent software items, Parent hardware items)
implements
/ "is implemented by"
(field Implemented items)
"is risk-controlled by"
/ "risk-controls"
(field Risk control measures)
executes
/ "is executed by"
(field Test being executed)
"relates to"
/ "is related to"
(field Related issues)
"is related to"
/ "is related to"
(field Related items)
tests
/ "is tested by"
(field Tested items)
affects
/ "is affected by"
(field Affected items)
"introduces risk"
/ "is introduced by"
(field Introduced risks)
"results in"
/ "results from"
(field New items)
"is resolved by"
/ resolves
(field Resolved by)
uses
/ "is used by"
(field Used items)
ITEMS
is an arbitrary query expression to filter for allowed targets (in case of forward relations) or sources (in case of reverse relations) of the relation. This expression might involve other, nested filters for relations.
DEPTH
is an optional parameter to specify a restriction on the relation depth. See the description of the to:
filter for details.
This is similar to the to:
and from:
filters, but specifying a particular relation name.
A filter of the form
queries items with a certain value for a given field.
FIELD
is a field name, e.g., Description
or "Rationale for deferring resolution"
. This is case-sensitive.
VALUE
is a single value or a string list denoting the allowed field value(s).
Textual fields (both plain-text and rich text) are matched in a case-insensitive way. If VALUE
is a list of values, all of them need to occur (somewhere) in the item's field value.
Select fields (with a predefined set of options, e.g., the Requirement type) require an exact match of the value (or one of the given values, if a list is specified).
Note: All examples assume the standard configuration of Ketryx. Queries could look differently if Ketryx is configured with different item type names, relations, or fields.
is a sequence of two symbols (some
and text
) without special meaning that are implicitly combined using the and
operator, so this query matches all items whose title contains "some" and "text" (not necessarily in this order and not necessarily directly after each other), e.g., it would match a title of Requirement with some text
as well as This text contains some
.
To match an exact text including whitespace, use quotes (i.e., a string rather than symbols):
matches Requirement with some text
but not This text contains some
.
Quotes are also necessary when matching against pieces of text that have a special meaning as symbols, e.g.,
matches items with a title that contain RQ
(or rq
or Rq
or rQ
, since the matching is case-insensitive), not the item type Requirement.
is a sequence of two symbols (RQ
and SW
) denoting item types that are implicitly combined using the or
operator, so this query matches all items that are either a Requirement or a Software Item Spec.
This is equivalent to:
matches all items that have SAMD-1
as their parent or whose parent has SAMD-1
as their parent, etc., i.e., all direct and indirect descendants of SAMD-1
.
This is equivalent to:
Note that, currently, automated test executions can only be filtered using the shorthand type filter TE
. Other filters do not apply to automated test executions. The matching based on TE
works in simplified KQL filters, e.g., in the context of cross-project references and ; in other contexts such as the All items page, automated test executions are not included.
To filter for particular relations, use the syntax to .
Note that version fields, date fields, and relation fields are not supported at this point. However, relations can be queried using the syntax to .