CodeQL documentation

Defining the results of a query

You can control how analysis results are displayed in source code by modifying a query’s select statement.

About query results

The information contained in the results of a query is controlled by the select statement. Part of the process of developing a useful query is to make the results clear and easy for other users to understand. When you write your own queries in the CodeQL extension for VS Code there are no constraints on what can be selected. However, if you want to use a query to create alerts for code scanning or generate valid analysis results using the CodeQL CLI, you’ll need to make the select statement report results in the required format. You must also ensure that the query has the appropriate metadata properties defined. This topic explains how to write your select statement to generate helpful analysis results.


Alert queries must have the property @kind problem defined in their metadata. For more information, see “Metadata for CodeQL queries.” In their most basic form, the select statement must select two ‘columns’:

  • Element—a code element that’s identified by the query. This defines the location of the alert.
  • String—a message to display for this code element, describing why the alert was generated.

If you look at some of the existing queries, you’ll see that they can select extra element/string pairs, which are combined with $@ placeholder markers in the message to form links. For example, Dereferenced variable may be null (Java), or Duplicate switch case (JavaScript).


An in-depth discussion of select statements for path queries is not included in this topic. However, you can develop the string column of the select statement in the same way as for alert queries. For more specific information about path queries, see “Creating path queries.”

Developing a select statement

Here’s a simple query to find Java classes that extend other classes.

Basic select statement

 * @kind problem

import java

from Class c, Class superclass
where superclass = c.getASupertype()
select c, "This class extends another class."

This basic select statement has two columns:

  1. An element with a location to display the alert on: c corresponds to Class.
  2. String message to display: "This class extends another class."
Results of basic select statement

Including the name of the superclass

The alert message defined by the basic select statement is constant and doesn’t give users much information. Since the query identifies the superclass, it’s easy to include its name in the string message. For example:

select c, "This class extends the class " + superclass.getName()
  1. Element: c as before.
  2. String message: "This class extends the class "—the string text is combined with the class name for the superclass, returned by getName().
Results of extended select statement

While this is more informative than the original select statement, the user still needs to find the superclass manually.

Further reading

  • © GitHub, Inc.
  • Terms
  • Privacy