Using the query console
The query console is a place:
- To run existing queries, see how they are structured and understand how they work.
- To write your own queries, try them out by running them on one or more analyzed projects or project lists and refine them further.
You can also write and run queries locally using the CodeQL for Visual Studio Code extension. Go to the Integrations tab for a project and install the extension. Then you can import and query any project database downloaded from LGTM. For more information, see Running queries in your IDE.
There are several ways to get to the query console. For further information, refer to About the query console.
You can use the query console to run existing queries, such as the built-in queries.
To run existing queries:
- Find the query in LGTM, using the search functionality. You can search for queries by keyword, language, and/or tag.
- In the list of returned results, identify the query and click on it. This displays the Query help page for the query.
- Click Open in query console. LGTM compiles the query.
- Select projects and project lists to query using the Project: selector. For further information on the query console user interface, refer to What does the query console look like?
- Click Run.
You'd typically follow these steps when writing and running a query in the LGTM query console:
You might wonder why you need to select the language before you can start writing a query. This is because each programming language has a tailored database schema. Choosing a language tells the compiler which database schema to validate the query against.
To select a language, click Select a language (or Language: language name if the box is already populated) and click the language you wish to query. A very basic query is displayed in the console's code box. You can use it as a starting point for your query.
For more information on the query console user interface, refer to What does the query console look like?
As you type in the code box, or when the very basic query is displayed in the console (see step 3 in the section above), LGTM checks it contains valid syntax, and compiles the query.
If the query cannot be compiled, you'll see a red warning symbol in the left margin (see below for an example) and the query is marked as invalid. Hover over the icon to display the error message. When you've resolved the problem, the button in the bottom right of the console will be titled either Run (if you've selected a project to run on) or Select projects to query (if you haven't selected a project yet).
Once you've selected a language, you can select one or more projects and project lists to run the query on.
To select projects and project lists:
- Click Project/Project list. The exact caption of the drop-down list depends on whether projects and project lists are already selected ( below).
- Select projects and project lists in the drop-down list, as required. That list contains the following categories ( below):
- Selected projects—this section will be empty if you don't currently have any projects selected.
- Selected project lists—this section will be empty if you don't currently have any project lists selected.
- Your projects—these are the projects that are present in your
My projects (Default)list.
- Project lists—these are the custom project lists that you have created in the Project lists page.
You can select each project individually by selecting the adjacent check box, or select them in bulk using the select all option ( below).
When you select a language on the Query console tab, the start of a very basic query is displayed in the code box. You can use it as a starting point, or you can load a simple example query. Queries normally start by importing a library (
import statement). This provides a wide range of predicates and classes that you can use in your query. For more resources for learning CodeQL, see Learning CodeQL.
Autocomplete suggestions are displayed as you type: when you press the space bar, or if you press Ctrl+space. Use the arrow keys to navigate the list. Press Tab or Return to insert the currently highlighted suggestion.
When you hover over a type or method, any QLDoc comment associated with that element is displayed in a tooltip. You can also press F3 to jump to the definition of the element (CodeQL library files are opened in new tabs in the console).
More in-depth information about query writing is provided in Writing custom queries to include in LGTM analysis. Refer to this topic for tips and tricks.
When you're ready to run your query, click Run ( below) in the bottom right corner of the query console's code box:
If there are any problems, or if you need to select a project and/or a project list before you can run your query, a message is displayed in place of the Run button.
While the analysis is running, the Run button is renamed Running. After a short while, the names of the projects you are analyzing are listed on the page—each with a progress bar. Hover over the progress bar to see the percentage of the analysis that is complete:
Results are displayed immediately if the query has already been run on the most recent snapshot of the project, otherwise it may take a couple of minutes—depending on the size of the project and complexity of the query.
There is a runtime limit for queries run from the query console. Your LGTM administrator can configure the timeout. If a query takes longer to run, LGTM will abort the process and let you know it timed out.
When you click Run, LGTM starts running the query on the selected projects. A global color-coded progress bar ( below) shows the progress for the analysis for each project:
- Hover over a colored segment to display a tooltip with further information on the run status:
Finished with results
Finished without results
- Click a colored segment to only show results that match the chosen status.
If the query is still running, the results become stale as runs move from incomplete to finished/failed states. When this happens, click the Reload results button ( below) to refresh the results view. Similarly, if you have selected a filter, you can return to the full results view by clicking Clear project filter( below).
LGTM displays up to 10 projects per page by default. To navigate through results, click the arrow icons adjacent to the Displaying projects X to Y label ( below)
The default order of results is arbitrary. You can customize the sort order by using the Order query runs by drop-down menu ( above). The availability of a sort order depends on the type of query being run. For more information on query types, see Writing custom queries to include in LGTM analysis.
|Option||Description||Queries the option applies to|
|Query execution time||Time taken to run the query on each individual project||All|
|Project size||Number of lines of code (LOC)||All|
|Alert count||Number of alerts reported||Queries generating alerts (
|Alert density||Alert count/LOC||Queries generating alerts (
|Result count||Number of result rows generated for the query||Queries that do not generate alerts.|
By default, results for alert and path queries are displayed as code snippets with inline alert messages ( above). For LGTM to correctly recognize and process these two query types, you need to ensure that your query has the correct metadata and
select statement. For further details, see Writing custom queries to include in LGTM analysis. For path queries, you can explore paths directly from the alert message.
If a file has multiple alert results, LGTM only displays one code snippet for that file. This snippet contains all of the alerts found in that file, up to a maximum of 10. LGTM always reports the total number of alerts found in a file.
To open the complete file, and jump to the alert location within it, click the arrow icon () ( above).
You can switch to a table view for both query types, by using the View as: Alert/Table toggle ( above) associated with the query results. For an example, see View as Alert/Table below.
Only new results will be displayed as code snippets. You won't see this format if you have saved an LGTM link for old query console results.
Click the down arrow () at the bottom of the list of displayed alerts for a project to display more results for that project. A maximum of 100,000 results is reported for queries written in the query console (this limitation doesn't apply to the alerts found by LGTM analysis).
The reported alert count can differ from the reported number of results in the table view. This is because multiple rows in the table are grouped into the same alert if they have identical locations, and because results from outside the source code are not counted as alerts in the project.
Additional options or information may be displayed alongside the project name in the results. For example:
- Show n non-source results (table view only)
- View as: Alert/Table toggle
Non-source results are accessible from the table view only. The example above shows query results for one project. The query found 48 results in the source files analyzed, and another 40 in code that originates outside this project. Any results found in imported or library files ("non-source results") are omitted from the default view because the source code isn't available in LGTM, so they're less interesting. Click the message if you want to display all the results.
The following results are for the Contradictory type checks query, run against a revision of the apache/hadoop Java project:
This query has
/** @kind problem */ in its metadata, which tells LGTM that it's an alert query. The query
select statement should agree with the
@kind property, as defined in Defining the results of a query. Here's the
select statement for our example query:
select e, "Variable $@ cannot be of type $@ here, since $@ ensures that it is not of type $@.", v, v.getName(), t, t.getName(), f, "this expression", sup, sup.getName()
This statement uses placeholders (
$@) to add links to the alert message. You can choose whether to display the results in the form of an alert code snippet (see screenshot above), or as a simple table of columns, by using the View as: Alert/Table toggle:
The number of columns and the format of the results is controlled by the
select statement of the query. Most queries return results in which you can click the entries in one of the columns to open the source viewer and see the code that matched the query.