Queries allow to perform calculations on a set of values, optionally applying some conditions.
You can think of a query as an structured statement similar to:
[COMPUTE_VALUE] FROM [SCOPE] WHERE [CONDITION]
In this section, you will learn how to compute values, define a scope and write conditions for your queries.
Queries provide the following operators to compute values:
Returns the sum of values returned for a set.
The SUM of values [1, 3, 3, 3, 5, 6] is 21.
Return the maximum or minimum value of a set.
The MAX and MIN of values [1, 3, 3, 3, 5, 6] are 6 and 1 respectively.
Returns the mean of all the values returned for a set.
The AVR of values [1, 3, 3, 3, 5, 6] is 3.5.
Returns the product of all the values returned for a set.
The MUL of values [1, 3, 3, 3, 5, 6] is 810.
Counts the number of elements returned for a set.
The COUNT of values [1, 3, 3, 3, 5, 6] is 6.
The COUNT
operator offers the following variations:
ARTEFACT_TYPE
is one of
FOLDER, APPLICATION,
C_FILE, or other types (or aliases) defined in your model. The scope of this tree-like hierarchy is defined as follows, relative to the current artefact, or node:
NODE
and DESCENDANT
NODE
and CHILDREN
.Defining a condition in your query means filtering out of the scope the results that do not meet
the condition. Several conditions can be added with the AND
and OR
operators,
and OR
takes priority over AND
. A condition consists of an operand,
a comparator, and a value. Note that parentheses are not allowed in the body of a condition. An example is shown below:
<Computation targetArtefactTypes="FUNCTION;FILE;FOLDER; APPLICATION;CLASS;PROGRAM" result="COUNT RULE FROM TREE WHERE NBOCCURRENCES>=1 AND FAMILY=MATURITY" />
All operands described in the section called “Operands” are allowed. Operators allowed for
conditions are: =
,!=
, <
,
>
, <=
and >=
. Note that XML does not allow using <
directly in an attribute, therefore you will need to insert it using an entity:
<
.
If you are using queries to retrieve metrics from artefacts or to count artefacts, your conditions can use regular computation syntax and function. Refer to the section called “Operands”, the section called “Simple Calculation Syntax”and the section called “Functions” for more details.
If you are using queries to retrieve metrics for the number of rules or violations, use the syntax from this section.
NBOCCURRENCES (=, <, >, <=, >=,!=) allows working with the number of occurrences of violations:
COUNT RULE FROM DESCENDANTS WHERE NBOCCURRENCES<10 COUNT RULE FROM DESCENDANTS WHERE NBOCCURRENCES>10 COUNT RULE FROM DESCENDANTS WHERE NBOCCURRENCES=1 COUNT RULE FROM DESCENDANTS WHERE NBOCCURRENCES!=1 COUNT RULE FROM DESCENDANTS WHERE NBOCCURRENCES<=1.0 COUNT RULE FROM DESCENDANTS WHERE NBOCCURRENCES>=1
CATEGORY (=, !=) allows working with scale levels (see the section called “Scales” for more information on scales):
COUNT RULE FROM DESCENDANTS WHERE CATEGORY=SCALE_PRIORITY.REQUIRED COUNT RULE.OCCURRENCES FROM DESCENDANTS WHERE CATEGORY!=SCALE_PRIORITY.REQUIRED
FAMILY (=, !=) allows working with the families set in your model for rules (see the section called “Rules” for more information on rules):
COUNT RULE FROM DESCENDANTS WHERE FAMILY=REQUIRED COUNT RULE FROM DESCENDANTS WHERE FAMILY!=REQUIRED
MEASUREID (=, !=) allows working with the ID of a measure you defined in your analysis model (see the section called “Measures” for more information on measures):
COUNT RULE FROM DESCENDANTS WHERE MEASUREID!=R_NOGOTO
You can combine conditions in a single query:
COUNT FILE FROM DESCENDANTS WHERE LEVEL!=LEVELC OR FAMILY=HIS AND B.LC>10
Since OR
takes priority over AND
,
this will be interpreted as:
(LEVEL!=LEVELC OR FAMILY=HIS) AND B.LC>10
The following examples are explained in details to help you understand how computations work.
This example counts the number of rules in the "required" family that were violated in the selected artefact and all its descendants.
COUNT RULE FROM TREE WHERE NBOCCURRENCES>=1 AND FAMILY=REQUIRED
This example counts the number of violations of the R_COMPOUNDELSE rule in the children of the selected artefact.
COUNT RULE.OCCURRENCES FROM DESCENDANTS WHERE MEASUREID=R_COMPOUNDELSE
This example counts the number of programs with a LEVEL of LEVELG, starting from the children of the considered artefact.
COUNT PROGRAM FROM DESCENDANTS WHERE LEVEL=LEVELG
This example counts the number of required rules that were violated in the selected artefact and all its descendants.
COUNT RULE FROM TREE WHERE NBOCCURRENCES>=1 AND FAMILY=REQUIRED
This example counts the number of issues with the status "fixed" created in the last 60 days
COUNT ISSUE FROM TREE WHERE EQUALS(INFO('STATUS'), 'FIXED') AND DATE_SUBMITTED >= TODAY() - DAYS(60)