Query metadata

Any query that is run as part of LGTM analysis includes a number of properties, known as query metadata. For alerts, this metadata tells LGTM how to handle the query and display its results correctly. It also gives other users information about what the query results mean. You can also add metric queries to LGTM. Note that results of metric queries are not shown on LGTM.

Most importantly, LGTM uses the @id to identify a query, so you should choose this value carefully and make sure that it is unique for each query!

The top four properties in the table below apply to all queries:

Property Value Description
@description <text> Mandatory, a sentence or short paragraph to describe the purpose of the query and why the result is useful or important. The description is written in plain text, and uses single quotes (') to enclose code elements.
@id <text> Mandatory, a sequence of words composed of lowercase letters or digits, delimited by / or -, identifying and classifying the query. Each query must have a unique ID. To ensure this, it may be helpful to use a fixed structure for each ID. For example, the standard LGTM queries have the following format: <language>/<brief-description>.
@kind problem or metric Mandatory, tells LGTM whether the query is an alert (@kind problem) or a metric (@kind metric).
@name <text> Mandatory, a statement that defines the label of the query. The name is written in plain text, and uses single quotes (') to enclose code elements.
@tags correctness maintainability readability security ... Optional, these tags group queries together in broad categories to make it easier to search for them and identify them. You can also filter alerts based on their tags. In addition to the common tags listed here, there are also a number of more specific categories. For more information about some of the tags that are already used and what they mean, see Query tags.
@precision medium high very high Optional (for alert queries only) The @precision property indicates the percentage of query results that are true positives (as opposed to false positive results). This affects the alert interest and how the query results are displayed in LGTM.
@problem.severity error warning recommendation Optional (for alert queries only) Defines the severity of the alerts found by this query. Together with other properties (such as @precision), this determines the alert interest. You can also filter alerts based on their severity.
@metricType file callable package project reftype Mandatory (for metric queries only) Defines the code element that the query acts on, and should match the type of result returned by the query.
@metricAggregate avg sum min max Mandatory (for metric queries only) Defines the allowable aggregations for the metric. A space separated list of the four possibilities sum, avg, min and max. If it is not present, it defaults to sum avg.

Example

Here is the metadata for one of the standard Java queries:

image0