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.
Matrix Requirements Query Language (MRQL aka Miracle) syntax
The general form looks like a Boolean expression with the classical AND, OR, NOT, parenthesis.
Each term is in the form variable operator value.
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)
The particular meanings of some variables are:
- category operator "value" : checks the the category of the item (REQ, SPEC, ...)
- title operator "value" : checks the the title of the item
- outdated = 0|1 : checks that the item is outdated (it's parent has been modified after)
- 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
- uplink | downlink operator category : checks that the item has at least one uplink (or downlink) to category. Also != , ~ and !~
- label = "value": selects items that have (or don't have if != is used) this label. The label part must be the internal one as defined in the admin console.
- (new in 2.1) id = itemid (for example id=MREQ-12) : looks specifically for one item
- (new in 2.1) folder = folderid (for example folder=F-MREQ-2) : search all items in that particular folder (does not include items that are some levels lower)
- (new in 2.1) folderm = folderid (for example folder=F-MREQ-2) : search all items in that particular folder and lower folders
- (new in 2.1) uplink = category (for example uplink=MREQ): finds all items which have a direct uplink to items in that category
- (new in 2.1) uplink = item (for example uplink=MREQ-3): finds all items which have a direct uplink to that item
- (new in 2.1) uplink = folder (for example uplink=F-MREQ-2): finds all items which have a direct uplink to an item in that folder
- (new in 2.1) 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)
- (new in 2.1) 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)
- (new in 2.1) 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)
- (new in 2.1) downlink: same as uplink but on the other direction
- (new in 2.1) downlinkm: same as uplinkm but on the other direction
- (new in 2.1) testResult = new (or ok or error or progress): test on the XTC result test
- (new in 2.1) lastXtcTestResult = new (or ok or error or progress): test on the result of the last XTC testing that test item
- (new in 2.1) risk.xxx = yyy: allows to search for specific risk values. See below for full syntax
- all other variables are matches for a field name. If the field name contains a space the variable must be double-quoted
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:"test run result"="af|error|failed"
- matches all failed tests: Since this field "test run result" is a dropdown, the actual value of the field "af|error|failed" differs from the displayed text "automatic - was 'failed' when last saved".
- mrql:updated < 3H
- matches all items modified during the last 3 hours
- mrql:uplink ~ "REQ"
- matchs 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
Signatures: (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
Risk queries (new in 2.1):
- 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
Searches expressions can be shared between team members, see Search Configuration.