Queries

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.

Computing Values

Queries provide the following operators to compute values:

SUM

Returns the sum of values returned for a set.

The SUM of values [1, 3, 3, 3, 5, 6] is 21.

MAX, MIN

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.

AVR

Returns the mean of all the values returned for a set.

The AVR of values [1, 3, 3, 3, 5, 6] is 3.5.

MUL

Returns the product of all the values returned for a set.

The MUL of values [1, 3, 3, 3, 5, 6] is 810.

COUNT

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:

COUNT ARTEFACT_TYPE: Returns the number of artefacts of a certain type. ARTEFACT_TYPE is one of FOLDER, APPLICATION, FILE, or other types defined in your model.
COUNT RULE: Returns the number of rules.
COUNT RULE.OCCURRENCES: Returns the number of times a rule is violated (i.e. the number of findings).

Query Scope

The scope of this tree-like hierarchy is defined as follows, relative to the current artefact, or node:

NODE: The current artefact.
CHILDREN: All artefacts that are direct children of the current artefact.
DESCENDANTS: All children of the current artefact, and their descendants.
TREE: The full tree of artefacts, starting from the current node. This is equivalent to NODE and DESCENDANT
RAKE: The current artefact and all its children. This is equivalent to NODE and CHILDREN.

Query Conditions

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: <.

Artefacts and Measures

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.

Rules / Occurrences

If you are using queries to retrieve metrics for the number of rules or violations, use the syntax from this section.

NBOCCURRENCES (=, <, >, <=, >=,!=)

COUNT RULE FROM DESCENDANTS WHERE NBOCCURRENCES&lt;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&lt;=1.0
COUNT RULE FROM DESCENDANTS WHERE NBOCCURRENCES>=1

CATEGORY (=, !=)

COUNT RULE FROM DESCENDANTS WHERE CATEGORY=SCALE_PRIORITY.REQUIRED
COUNT RULE.OCCURRENCES FROM DESCENDANTS WHERE CATEGORY!=SCALE_PRIORITY.REQUIRED

FAMILY (=, !=) for rules

COUNT RULE FROM DESCENDANTS WHERE FAMILY=REQUIRED
COUNT RULE FROM DESCENDANTS WHERE FAMILY!=REQUIRED

MEASUREID (=, !=)

COUNT RULE FROM DESCENDANTS WHERE MEASUREID!=R_NOGOTO

MULTI-CONDITION

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

ALL (as a shortcut for all available types)

COUNT ALL FROM DESCENDANTS WHERE LEVEL>LEVELC
SUM ALL.TECH_DEBT_TYPE FROM TREE

Examples

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 &gt;= TODAY() - DAYS(60)

Prev	Up	Next
Functions	Home \| ToC	Chapter 6. Configuring Dashboards