This topic describes how to use filter queries to control the results of Semmle analysis.
You can use filter queries to limit the data returned by a query (or query category) during the analysis of your code. Standard filter queries are provided with the Semmle Core installation. You can also write your own filter queries using QL and save them as
.ql files, in the same way as other query files (for more information see Learning QL and Query file requirements). When you add filter queries to the appropriate query suite file, only results that pass the filter will be reported.
Limiting a single query
You can limit the results returned by a single query by editing:
- Query file–use QL to define additional constraints to limit the results that are returned, this limits the results returned by the query for all analyses.
- Query suite file–update the query row to include a filter query, this limits the results returned by the query for all analyses that use this query suite.
You can find the standard filters in the language subdirectories of the
queries directory of your Semmle Core distribution. Custom filters can be developed in an IDE with a QL plugin or extension installed. For information on installing a QL plugin or extension, see QL plugins and extensions. For more information about developing filter queries in your IDE, see Writing a filter query and Running a filter query.
To limit a single query, you can add a filter query in a query suite file using the following format:
<path>/<filter-query> defines the name and location of the filter query,
<path>/<query> defines the name and location of the query that you want to apply the filter to. Optionally, you can assign the filtered results to a specified
A custom query,
custom-query.ql, is referenced in a query suite by specifying its path. Optionally, the query is assigned a category to link it to similar queries. In the example below,
custom-query.ql is assigned to
When you add a filter,
custom-filter.ql, to limit the results generated by
custom-query.ql, the row where the query is referenced is updated to:
When you now analyze a snapshot using a query suite that includes the updated definition of the
custom-rule.ql query, all new results generated for this query are filtered using the
custom-filter.ql. This means that, of the results generated by the
custom-rule.ql, only those that pass through the
custom-filter.ql are output into the results file.
Limiting a category
You also can limit the results returned by all queries that contribute to a particular category by adding a new row to a query suite file using the following format:
<path>/<filter-query> defines the name and location of the filter query and
<category> defines the category that you want to apply the filter to.
To filter all results shown in the standard
Correctness category and sub-categories using a custom filter,
correctness-filter.ql, you would add the following row to the required query suite file:
When you carry out an analysis using a query suite that includes the new filter, all results generated by queries assigned to the
Correctness category are filtered using the
custom-filter.ql. This means that, of the results generated by the queries in the
Correctness category, only the results that are passed by the filter will be output into the results file.
Limiting all results
You can also apply filters to restrict the results generated by all queries referenced in a query suite, if necessary. For example, if a project includes sections of automatically generated code in the source files, you may wish to exclude the results generated during the analysis of these sections. Filter queries that identify and exclude parts of your code that appear to be automatically generated code for different languages are included with the Semmle Core installation. To exclude the results from automatically generated code you need to add one of the following queries to your query suite:
When you use
analyzeSnapshot with a query suite that includes the new filter, all queries are filtered to exclude results from automatically generated code.