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-3Note: “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 reviewmodAfterReview=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)
Labels queries (new in 2.3.4)
To look for labels based on their value displayed on the screen when the label is set (not the internal id), you can use the following syntax:
mrql:label=["for US"] : looks for items with the “for US” label
mrql:label!=["for US"] : looks for items without the “for US” label
The displayed value is the Label Set text, Label Unset or the print text are not used. Also, if the label does not have a Label Set text then the search will fall back to the label id.
Dropdown queries (new in 2.3.4)
To look for dropdowns based on the values displayed in the dropdown selection, MRQL allows you to find items with only a single value, one value among possibly others, etc:
mrql:dropname=[value] : to find a dropdown with only that value
mrql:dropname~[value] : to find a dropdown with that value and perhaps others
mrql:dropname!=[value] : to find a dropdown with only one value which is not that one
mrql:dropname!~[value] : to find a dropdown without that value
If the value contains a space, it needs to be enclosed in double quotes:
mrql:dropname=["the value"]
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 all the requirements and other items that are uplinks to tests that failed the last time they were executedmrql:risk.severity>=3 ==> uplink=previous
shows all the risk controls of the risks with severity >= 3mrql:category=VER and label!=ABC ==> in=previous or (downlink=previous and category=DRQ and label=ABC)
shows all VER items without the ABC label, and also shows the DRQ uplinks from the previous part with the ABC labelmrql:folderm=F-REQ-12 ==> uplink=previous and category=SPEC and label=x ==> uplink=previous and category=TC and label=y
shows the TC items with label y who has a SPEC uplink with label x, which have an uplink in one of the folders and subfolders of F-REQ-12