Metadata for CodeQL queries¶

Metadata tells users important information about CodeQL queries. You must include the correct query metadata in a query to be able to view query results in source code.

About query metadata¶

Any query that is run as part of an analysis includes a number of properties, known as query metadata. Metadata is included at the top of each query file as the content of a QLDoc comment. This metadata tells the CodeQL extension for VS Code and the Code scanning feature in GitHub how to handle the query and display its results correctly. It also gives other users information about what the query results mean. For more information on query metadata, see the query metadata style guide in our open source repository on GitHub.

Note

The exact metadata requirement depends on how you are going to run your query. For more information, see the section on query metadata in “About CodeQL queries.”

Metadata properties¶

The following properties are supported by all query files:

Property	Value	Description
`@description`	`<text>`	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>`	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 CodeQL queries have the following format: `<language>/<brief-description>`.
`@kind`	`problem` `path-problem`	Identifies the query is an alert (`@kind problem`) or a path (`@kind path-problem`). For more information on these query types, see “About CodeQL queries.”
`@name`	`<text>`	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`	These tags group queries together in broad categories to make it easier to search for them and identify them. In addition to the common tags listed here, there are also a number of more specific categories. For more information, see the Query metadata style guide.
`@precision`	`low` `medium` `high` `very-high`	Indicates the percentage of query results that are true positives (as opposed to false positive results). This, along with the `@problem.severity` property, determines how the results are displayed on GitHub.
`@problem.severity`	`error` `warning` `recommendation`	Defines the level of severity of any alerts generated by a non-security query. This, along with the `@precision` property, determines how the results are displayed on GitHub. For more information, see the Query metadata style guide.
`@security-severity`	`<score>`	Defines the level of severity, between 0.0 and 10.0, for queries with `@tags security`. For more information, see the GitHub user documentation.

Example¶

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

For more examples of query metadata, see the standard CodeQL queries in our GitHub repository.