Matrix Requirements Query Language (MRQL)

You can make advanced searches for items in Matrix Requirements. You just prefix your search with "mrql:" and you do ... miracles (MRQL) searches.

A search terms looks this:

Matrix Requirements Query Language (MRQL aka Miracle) syntax

A basic search expression is of the form mrql:subject operator value, e.g. mrql: updated <= 3d is composed like this:

  • updated is the subject, in this case time of the last change

  • <=  is the operator. In this case meaning 'within'

  • 3d is the value, in this case 3 days

Therefore the search expression searches for all items which have been changed in the last 3 days.

Search expression can also have use the keywords and, or and not, to build more complex search expressions, e.g. mrql:updated < 3d and not(updated>2d) will search for items, last changed 3 days ago (changed in the last 3 days, and not after)

The valid letters for the intervals are:

  • d for days

  • w for weeks

  • m for months

  • y for years

  • H for hours

  • M for minutes

Other examples:

  • mrql:domain ~ "xyz" and category = "TC"

   matches all item of the category "TC" who has a field "domain" which includes "xyz"

  • mrql:outdated = 1 and category != "XTC"

   matches all outdated items which are not "XTC" items

  • mrql:updated < 3H

   matches all items modified during the last 3 hours

  • mrql:uplink ~ "REQ" 

   matches all items with an uplink in a category containing REQ (MREQ, FREQ, REQ, ...)

  • mrql:updated<1w and category="REQ"

   requirements updated in last 7 days

Operators

The operators can be:

  • = for equal (case sensitive)

  • != for not equal (case sensitive)

  • ~ for "include" (case insensitive)

  • !~ for "doesn't include" (case insensitive)

  • < or > for smaller than or bigger than (only for updated age

Search Subjects

Query by id, title or category

  • category operator "value" : checks the the category of the item (REQ, SPEC, ...)

  • title operator "value" : checks the the title of the item 

  • id = itemid (for example id=MREQ-12) : looks specifically for one item

Query by label

  • label = "value": selects items that have (or don't have if  != is used) this label. 

The value of the label must be it's internal id not the display name (because that can be changed over time or depending of the status)

 Query by field names

To search by a field name combine the field name with the operator and the comparison value, e.g.

  • mrql:Tester=Joe

  • mrql:Description~"Hello world"

If the field name contains a space the variable must be double-quoted

Matrix distinguishes between empty and non existing fields, e.g. if you have some items in a category REQ and after a while you add a checkbox field (called "my checkbox") to the category, some of the items might have never be changed after the configuration change therefore

  • mrql:"my checkbox"=false → will return all items with a checkbox field, which is unset

  • mrql:not("my checkbox") → will return all items with a checkbox 

therefore to get all REQ without the checkbox set, use

  • mrql:not("my checkbox"=true) and category=REQ

Query by folder content queries

  • mrql:folder = folderid (for example folder=F-MREQ-2) : search all items in that particular folder (does not include items that are some levels lower)

  • mrql:folderm = folderid (for example folder=F-MREQ-2) : search all items in that particular folder and lower folders 

Query by traceability and Folder content queries

uplink | downlink operator category : checks that the item has at least one uplink (or downlink) to category. Also != , ~ and !~

  • mrql:uplink = category (for example uplink=MREQ): finds all items which have a direct uplink to items in that category

  • mrql:uplink = item (for example uplink=MREQ-3): finds all items which have a direct uplink to that item

  • mrql:uplink = folder (for example uplink=F-MREQ-2): finds all items which have a direct uplink to an item in that folder

  • mrql:uplinkm = category (for example uplink=MREQ): finds all items which have an uplink to items that have uplink items to that category at any level)

  • mrql:uplinkm = item (for example uplink=MREQ-3): finds all items which have an uplink to that item via some others items eventually (at any level)

  • mrql:uplinkm = folder (for example uplink=F-MREQ-2): finds all items which have an uplink to an item in that folder via some others items eventually (at any level)

  • mrql:downlink: same as uplink but on the other direction 

  • mrql:downlinkm: same as uplinkm but on the other direction

  • mrql:outdated = 0|1 : checks that the item is outdated (it's parent has been modified after). Note: for SIGN and XTC it’s the creation date which is compared to the last modification date of their DOC / XTC.

Last Children

There is the possibility to find the last XTC for a test or the last SIGN for a DOC through mrql:

  • mrql:lastChild = item : looks for all the last children of an item (if REQ-3 has SPEC-6 and SPEC-12 as children, lastChild=REQ-3 would be SPEC-12) (new in 2.3)

Examples:

mrql:lastChild=1 and category=SIGN // returns all the latest SIGNs 
mrql:lastChild=1 and category=XTC // returns all the latest XTCs
mrql:lastChild=2 and uplink=TC-3 // returns the last two XTCs created from TC-3

Note: “last” means the ones with the highest id

Note: running it for anything but XTCs and SIGN works but the results might be meaningless or hard to understand, depending on the project configuration

Searches for authors of changes:

  • mrql:createdBy = user : looks for items created by that user (author of v1 of the item) (new in 2.3)

  • mrql:editedBy = user : looks for items edited at least once by that user (any version including 1 one) (new in 2.3)

  • mrql:lastEditedBy = user : looks for items with the last edited by that user (new in 2.3)

Query by signature

Note: (joe below is a login name, enclose in double quotes if login contains a dot)

  • mrql:needSignature = joe

    • Looks for all SIGN items where joe has not signed

  • mrql:needSignature = any

    • Looks for all SIGN items where someone still needs to sign

  • mrql:needSignature != joe

    • Looks for all SIGN items where joe has signed or was not supposed to sign

  • mrql:needSignature != any

    • Looks for all SIGN items where all users that were supposed to sign did sign

Query by risk details

  • mrql:risk.probability = 3

    • (also <, >, <=, >=, !=) -- probability can be any of the numerical variable involved in the risk

  • mrql:risk.probability.a = 3

    • (also <, >, <=, >=, !=) for after mitigation

  • mrql:risk.field=text

    • (also !=, ~, !~) -- field can be any text subfield from the risk field

  • mrql:risk.ram= 20

    • (also <, >, <=, >=, !=) , also rbm

  • mrql:risk.zone = green

    • (also red, yellow), also risk.zone.a for after mitigation

Query by test status

  • mrql:testResult = new (or ok or error or progress): test on the XTC result test

  • mrql:lastXtcTestResult = new (or ok or error or progress): test on the result of the last XTC testing that test item1

  • mrql:lastExecutedTest = F-TC-5 : looks for all the last XTC generated from tests in F-TC-5 or its subfolders (new in 2.3)

Query by review status

  • mrql:reviewItem = item (for example reviewitem=MREQ-3): finds all review items where MREQ-3 was reviewed

  • mrql:reviewItem = folder (for example reviewitem=F-MREQ-20): finds all review items where any child of F-MREQ-20 (at any level) was reviewed

  • mrql:hasReview=1 : looks for items covered by a review (new in 2.3)

  • mrql:modAfterReview=1 : looks for items modified after their last review (new in 2.3)
    modAfterReview=1 shows all items that have a review but have been modified after the last review

    modAfterReview=0 shows all items that had a review and are the same since the review (it doesn't show non-reviewed items)

  • mrql:reviewedBy = REVIEW-N : looks for items reviewed by that review item “REVIEW-N” (new in 2.3)

Query by time

  • mrql:updated < | > Nx : checks that the last modification date of an item is lower or higher than a duration. Duration is expressed as integer followed by a letter:

    • y for year

    • m for month

    • w for week

    • d for day

    • H for hour

    • M for minute 

  • mrql:created < | > NX: same as above but for the creation date of the item (the version 1) – (new in 2.3)

  • mrql:field < | > NX: same as above but for any field containing a date (like a CAPA review date, or a supplier evaluation renewal date, or the date a test has ran) – (new in 2.3)

Query file attachments

If you have a file attachment field named "Attachments" you can find items with attached files with:

  • mrql:attachments ~ ","

(the reason why this is working is that we store the attachment field as a json array of objects. If the array contains at least an element, there's at least a comma)

Search Values

Search values can depend on the subject (e.g. for times or test results, you need to compare the subject to specific values).

Use normal double quotes for string with spaces.

Search Macros

There are two macros which can be used as search values:

When searching you can use the macros _me_ for (your user name) or _this_ (for an item), e.g. you can now search using macros like

  • _me_ (this will find all items where your user id is mentioned in any field)

  • mrql:Tester=_me_ (this will find all items (e.g. XTCs where you are assigned as Tester)

  • mrql:needSignature=_me_ (this will find all documents you need to sign)

  • mrql:uplinkm=_this_ (this will find all items which have an uplink over one or more levels to the currently selected item)

These macros are only available/useful in the web-client, not through the API.

Sharing Searches

You can define and share search expressions with the team. This can can be done in the admin client: Search Configuration.

These predefined searches show up in the search drop down in the client

Cascading Searches

(new in 2.3)

Sometime you need to make a secondary search after a primary one. For example you look for all requirements that are risk controls of a risk higher than this. Or you want to look for all requirements that have a test which failed

Syntax:

  • mrql:search1 THEN search2 THEN search3 ...

or

  • mrql:search1 ==> search2 ==> search3 ==> ...

in order to use in search2 the results from search1 you can use the following constructs:

  • uplink=previous : keep the items that have a direct uplink to the previous set

  • uplinkm=previous : keep the items that have an uplink to the previous set, at any level

  • downlink=previous : keep the items that have a direct downlink to the previous set

  • downlinkm=previous : keep the items that have a downlink to the previous set, at any level

  • in=previous : keep the items from the previous search

  • reviewItem=previous : keep the items that are reviewed in the review list computed by the previous set

  • reviewedBy=previous : keep the reviews items that review any of the items computed by the previous set

(you can use != as well for any of the above)

Here are some actual examples:

  • mrql:lastXtcTestResult=error THEN downlinkm=previous : shows you the tests that resulted in an error last time they were executed

  • mrql:risk.severity>=3 ==> uplink=previous: shows all the risk controls of the risks with severity >= 3

  • mrql:category=VER and label!=ABC ==> in=previous or (downlink=previous and category=DRQ and label=ABC)