Ketryx Query Language

Reference of the Ketryx Query Language (KQL)

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.

Simplified KQL vs. full KQL

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

1. When using KQL in the Ketryx web application or document templating engine, full KQL can be used

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

Examples

Some frequently used examples:

KQL	Meaning	Supported in Simplified KQL
SAMD-1 SAMD-2 SAMD-3	Items with a Jira issue key of SAMD-1, SAMD-2, or SAMD-3	yes
RC	Risk controls	yes
RQ SW	Requirements and Software Item Specs	yes
assignee:me	Items assigned to me	yes
project:selected RQ	All Requirement items of the current project	yes
not is:controlled and not is:deferred	Items that are not in a controlled state and are not deferred	partly (is:deferred not supported)
not approved:me and not approved:(RD,QM)	Not approved by me and not approved by the groups R&D Leads or Quality Managers	no
SW and fulfills:RQ	Software Item Specs that fulfill a Requirement	yes
"Test type":"Verification (unit)"	Tests with a Test type of Verification (unit)	yes
TC and (tests:RC or RC) and intestplan:"Version 1.0"	Tests for risk controls or that are risk controls themselves, that are in the test plan of Version 1.0	partly (intestplan not supported)
tests:(diff:(new,changed))	Tests that test a new or changed item	no (diff not supported)
"is risk-controlled by":(diff:removed)	Risks with a risk control that was removed in the currently selected version compared to the previous release	partly (diff not supported)
"Requirement type":("Use case", "Intended use")	Requirements of type Use case or Intended use	yes
"has parent"::("Requirement type":"Use case")	Descendants of Requirements of type Use case	yes
to:(0,*):("Requirement type":("Intended use","Use case"))	Items with any relation to Requirements of type Intended use or Use case, including those Requirements themselves	yes
TC and (tests:CR or tests:("is affected by":CR or diff:(new,changed,removed)) or diff:new)	All TCs that either test a Change Request, are affected by a new,changed,removed CR, or are considered new	yes

Syntax

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

Type	Examples
Symbol	x v1.2.3 SAMD-12
String	"x"
Boolean operator	condition1 and condition2 not cond1
Grouping	(cond1 and cond2) or (cond3 and cond4)
Sequence	(item1, item2) (item1 item2)
Filter	filter:arg1:arg2

Symbols

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)

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 System of Systems; in other contexts such as the All items page, automated test executions are not included.

Besides these special cases, symbols are treated like strings and are matched against the title of an item (in a case-insensitive way).

Strings

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

Boolean operators are evaluated in the following order of decreasing precedence: not before and before or. For instance,

a or not x and y or z

is equivalent to:

a or ((not x) and y) or z

Boolean operators can also be written in upper-case (NOT, AND, OR), or using the special characters ! (not), && (and), and || (or).

Boolean operator keyword	Equivalent operator character
not	!
and	&&
or	||

For instance,

a or not x and y or z

can also be written as:

a || !x && y || z

Depending on the operand, the operators and and or can be omitted entirely (see Sequences below).

Sequences

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

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. [e-mail]). 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.:

to:(0 1):TC

To filter for particular relations, use the syntax to filter by relation.

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"

Filter by relation

A filter of the form

RELATION:ITEMS

or

RELATION:DEPTH:ITEMS

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.

Filter by field value

A filter of the form

FIELD:VALUE

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 that version fields, date fields, and relation fields are not supported at this point. However, relations can be queried using the syntax to filter by relation.

Additional examples and explanations

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.

Item title

some text

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):

"some text"

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

"RQ"

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.

Requirement or Software Item Spec

RQ SW

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:

type:Requirement or type:"Software Item Spec

All descendants of a particular item

"has parent"::SAMD-1

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:

"has parent":*:(id:"SAMD-1")