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, C_FILE, or other types (or aliases) defined in your model.

COUNT RULE([<scope>])

Returns the number of rules. You can specify the ruleset to take into account by specifying a scope:

ALL is the entire ruleset for the model, ignoring whether rules are enabled or not
STANDARD is the model ruleset minus the rules that are deactivated by default
CUSTOMER is the ruleset as configured in the web interface using the Analysis Model Editor
PROJECT (default) is the ruleset as configured by the user when going through the project wizard

COUNT RULE([<scope>]).OCCURRENCES([<status>])

Returns the number of times a rule is violated (i.e. the number of findings). You can set a scope for the ruleset to take into account (see RULE above) and also limit the occurrences to a certain status:

ALL returns all findings irrespective of their relaxation status
OPENED (default) returns only findings that are not relaxed
RELAXED returns only relaxed 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="CODE" result="COUNT RULE FROM TREE WHERE HAS_OCCURRENCE() 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.

HAS_OCCURRENCE([<findingStatus>], [<onlyRelaxedInSourceCode>]) allows finding if there are any violations of the specified rules in the specified scope. You can refine the results by specifying the status of the violations you are looking for:
- OPEN (default) to find all violations except the ones that were relaxed
- ALL to find all violations irrespective of their relaxation status
- RELAXED to find all relaxed violations
- RELAXED_DEROGATION to find violations with the Derogation relaxation status
- RELAXED_LEGACY to find violations with the Legacy Code relaxation status
- RELAXED_FALSE_POSITIVE to find violations with the False Positive relaxation status
Additionally, you can specify whether to find violations that were relaxed in the source code directly (as opposed to the web interface) by passing TRUE or in the source code or via the web interface by passing FALSE (default) as the second parameter.
Examples:
1. Find out if there are MISRA violations:
```
COUNT RULE FROM DESCENDANTS WHERE HAS_OCCURRENCE() AND FAMILY=MISRA
```
  or:
```
COUNT RULE FROM DESCENDANTS WHERE HAS_OCCURRENCE(OPEN) AND FAMILY=MISRA
```
2. Find out if there is legacy code with relaxed critical violations:
```
COUNT RULE FROM DESCENDANTS WHERE HAS_OCCURRENCE(RELAXED_LEGACY)
```
3. Find out if the code was modified to relax violations:
```
COUNT RULE FROM DESCENDANTS WHERE HAS_OCCURRENCE(RELAXED, TRUE)
```

NBOCCURRENCES (=, <, >, <=, >=,!=) allows working with the number of occurrences of violations:

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

Warning

NBOCCURRENCES is deprecated and should be replaced with HAS_OCCURRENCE() whenever possible.

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
```
IS_STATUS_FINDING(<findingStatus>, [<onlyRelaxedInSourceCode>]) allows specifying the status of the findings that should be taken into account in your query. The following statuses are supported:
- OPEN (default) to find all violations except the ones that were relaxed
- ALL to find all violations irrespective of their relaxation status
- RELAXED to find all relaxed violations
- RELAXED_DEROGATION to find violations with the Derogation relaxation status
- RELAXED_LEGACY to find violations with the Legacy Code relaxation status
- RELAXED_FALSE_POSITIVE to find violations with the False Positive relaxation status
Additionally, you can specify whether to find violations that were relaxed in the source code directly (as opposed to the web interface) by passing TRUE or in the source code or via the web interface by passing FALSE (default) as the second parameter.

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

Examples

The following examples are explained in details to help you understand how computations work.

Find the number of rules in the "required" family that were violated in the selected artefact and all its descendants:

COUNT RULE FROM TREE WHERE HAS_OCCURRENCE() AND FAMILY=REQUIRED

Find 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

Find the number of relaxed violations of the R_COMPOUNDELSE rule in the children of the selected artefact:

COUNT RULE.OCCURRENCES(RELAXED) FROM DESCENDANTS WHERE MEASUREID=R_COMPOUNDELSE

Find the number of legacy-code-relaxed violations of the R_COMPOUNDELSE rule in the children of the selected artefact:

COUNT RULE.OCCURRENCES(RELAXED) FROM DESCENDANTS WHERE MEASUREID=R_COMPOUNDELSE AND IS_STATUS_FINDING(RELAXED_LEGACY)

Find the number of programs with a rating of LEVELG, starting from the children of the considered artefact:

COUNT PROGRAM FROM DESCENDANTS WHERE LEVEL=LEVELG

Find the number of rules in the MISRA family in the model:

COUNT RULE WHERE FAMILY=MISRA

Find the number of rules in the MISRA family in the model, ignoring all changes made in the Analysis Model Editor:

COUNT RULE(STANDARD) WHERE FAMILY=MISRA

Find the number of rules in the REQUIRED family that were violated in the selected artefact and all its descendants:

COUNT RULE FROM TREE WHERE HAS_OCCURRENCE() AND FAMILY=REQUIRED

Find 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