Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from space SDmaster and version 1.24
Dont print
Panel
borderColor#39B54A
bgColor#ffffff
titleColor#39B54A
titleBGColor#ffffff

On this page:

Table of Contents
maxLevel2

Related topics:

HIDDEN

Excerpt
hiddentrue

Semmle Core: used in a query suite file to override the default properties of a query or to provide additional information for the calculation.

Purpose

Query directives can be used in a dashboard Configuration or query suite file to override the default properties of a query or to provide additional information for the calculation.

Structure

Query directives act on the preceding query. Each directive must be defined on a separate line.

Directives

The directives supported by queries are:

  • Common directives - supported by queries used to report violations or to calculate metrics (not supported by queries used to filter data)
  • Rule query directives - supported only by queries that report violations of a rule
  • Metric query directives - supported only by queries that calculate metrics
  • Conversion directives - supported only by queries that calculate metrics. Used to define a limit so that a metric query reports violations.

Common directives

Rule and Metric queries all support the following directives:

Directive

Value Example 

Notes

@name

<text> @name Custom name

Use to override the default name for the query. Displayed in client applications.

@description

<text> @description Custom description 

Use to override the default description for the query. Displayed in client applications as a tooltip.

Rule query directives

In addition to the Common directives, rule queries support the following directive:

Directive

Value  Example

Notes

@problem.severity  

<type> @problem.severity warning
@problem.severity error
@problem.severity recommendation

Use to override the severity of the rule. Controls one method of categorizing violations in the Mend application. Also supported by metric queries that have been converted into rules by defining a Conversion directive.

Metric query directives

In addition to the Common directives, metric queries support the following directives:

Directive

Value Example 

Purpose

@treemap.threshold

<number>@treemap.threshold 10

Defines a metric threshold. Used with @treemap.warnOn to define a “danger area” for metric charts.

@treemap.warnOn

<danger> @treemap.warnOn highValues
@treemap.warnOn lowValues 

Defines whether high or low values of the metric are considered dangerous. More dangerous values are typically displayed in a deeper red color in the user interface. For example, the cyclomatic complexity of a method is a metric where high values are dangerous, and the test coverage of a method is a metric where low values are dangerous.

@metricType

<type> 

@metricType file
@metricType callable
@metricType package
@metricType project
@metricType reftype

Defines the element used to calculate the metric. This should not normally be changed using a directive, since it is determined by the query.

@metricAggregate  

 <aggregations>

@metricAggregate avg sum max min

Defines the type of aggregations available to users for this metric. For example, a metric that expresses a percentage should not be aggregated using sum.

Conversion directives

You can change the reporting behavior of a metric query so that it reports violations, instead of a calculation, by defining a conversion directive. Metric queries support the following directives:

Directive

ValueExamplePurpose

@recommendation-from

<number>@recommendation-from 3.4

All values higher than or equal to the value will generate a violation (type recommendation)

@recommendation-to

<number>@recommendation-to 3.3

All values lower than or equal to the value will generate a violation (type recommendation)

@warning-from

<number>@warning-from 5

All values higher than or equal to the value will generate a violation (type warning)

@warning-to

<number>@warning-to 4

All values less than or equal to the value will generate a violation (type warning)

@error-from

<number>@error-from 2

All values higher than or equal to the value will generate a violation (type error)

@error-to

<number>@error-from 1.9
All values less than or equal to x will generate a violation (type error)

If a metric query should be displayed both as a violation (using conversion directives) and as a metric, it must be listed twice – once with and once without the conversion directives. The two occurrences should be placed into different dashboard categories.

Known limitations

When a dashboard configuration file includes an entire directory of queries, any query directives following that inclusion will apply to all queries in the specified directory. This is inappropriate for some directives (like @name and @description); it is therefore considered best practice for dashboard configuration files to include each query individually.