Matrix Requirements Query Language (MRQL)

/code

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)

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 item

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

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 

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

Search