Note: This documentation is for the legacy command-line tool odasa.
The final version was released in May 2020. Support for this tool expires in May 2021.

For documentation on the new generation CodeQL CLI, see CodeQL CLI .
In particular, you may find the Notes for legacy QL CLI users useful in planning your migration.

Skip to end of metadata
Go to start of metadata


To simplify the management of your queries for analysis of multiple projects, it is often useful to group them together into query suites. When you modify or update an individual query file, all query suites in which the changed file is referenced will also be updated. 


All queries to be added to your query suite file must have a header section that defines the name, description, and type of query. For use in analysis, this query metadata must include @id and @kind properties. For more information, see Query metadata. Custom queries should be saved in a directory outside the Semmle Core distribution directory and compiled using the prepareQueries command. For more information, see Preparing custom queries.

Adding queries to a query suite

You can add one or more queries to a query suite file in two ways:

  • By directly referencing individual queries.
  • By using the @import directive to reference another query suite, for instance a set of default queries.

Referencing individual queries

The file path for each query must be defined relative to one of the predefined Semmle variables, relative to the location of the main Semmle Core queries directory (${odasa_queries}), or as an absolute path. Each query is specified on a separate line using the following format:

+ <path>/<query>: /<category>/<sub-cateogry>
  @<optional query directive>


  • + indicates that the query should be enabled.
  • <path> is the file path of the query, as defined above.
  • <query> is the query to run.
  • <category>/<sub-category> is the query category, for example Correctness/Logic errors. These categories are used to group queries thematically for advanced analysis. For further information, see Filtering data.
  • @<optional query directive> is an optional directive used to alter the behavior of the preceding query. For further information, see Query directives.

Using the @import directive

You can also use the @import directive to reference one or more existing query suites. When you use @import, all of the individual queries referenced in the imported files are added to the new query suite. The file path for the query suite you are importing must be defined relative to one of the predefined variables, relative to the location of the query suite it is being imported into, or as an absolute path. For example:

  • The language-specific query suites, used to group standard queries thematically for a particular language, are located in the ${odasa_queries}/suites/<language> directory. 
  • ${odasa_queries}/customer/default contains query suites that assemble default sets of queries for each language by referencing the query suites in ${odasa_queries}/suites/<language>
  • You can store custom queries in a chosen location and provide an appropriate file path in your query suite file to include them in your analysis.

The following example is taken from a query suite for analyzing Java projects. Each @import directive imports a separate suite file.

# Import the standard rules for analyzing Java projects
@import ${odasa_queries}/customer/default/java
# Import the default security queries
@import ${odasa_queries}/suites/security/java/default
# Import custom queries
@import ${semmle_home}/custom-queries/query-suite


If you wish to group a number of queries for analysis of multiple Java projects then your query suite may look like this:

Configuration file using query suites
# Import the default query suites for Java analysis
@import ${odasa_queries}/customer/default/java

# Add one or more standard queries
+ semmlecode-queries/Likely Bugs/Comparison/BitwiseSignCheck.ql: /Correctness/Arithmetic
+ semmlecode-queries/Likely Bugs/Comparison/NoComparisonOnFloats.ql: /Correctness/Arithmetic
+ semmlecode-queries/Likely Bugs/Arithmetic/CondExprTypes.ql: /Correctness/Arithmetic
+ semmlecode-queries/Likely Bugs/Arithmetic/OctalLiteral.ql: /Correctness/Arithmetic
# Add two extra custom queries
+ ${semmle_home}/custom-queries/java/CustomQuery1.ql: /Advisory/Declarations
+ ${semmle_home}/custom-queries/java/CustomQuery2.ql: /Correctness/Exceptions

In this example, the @import ${odasa_queries}/customer/default/java statement imports the default Semmle Core Java query suite. The four standard queries are referenced by their relative path, and the custom queries are stored in the location defined by environment variable SEMMLE_HOME

Disabling queries

You may find that some queries referenced in a query suite are not relevant to a particular project. When this is the case, you can disable these queries using the following format:

- /<category>/<sub-category>/<query>


  • - indicates that the query should be disabled.
  • /<category>/<sub-category> is the dashboard category that the query results have been assigned to.
  • <query> is the query to disable.

You can also disable an entire category or sub-category of queries by using the syntax: - /<category>/<sub-category>. This will disable all queries that you have referenced in the query suite that match <category>/<sub-category>, whether they have been individually referenced or imported from another query suite file using @import.

LGTM query suites

The LGTM query suites are included with the QL command-line tools, so you can run exactly the same queries offline as are run in an analysis by LGTM. You can then upload your data to LGTM for further analysis. For information on generating data to upload to LGTM, see Preparing snapshots to upload to LGTM.

The LGTM query suites can be found at the following locations:
  • C/C++ LGTM query suite: ${semmle_home}/queries/customer/default/cpp-lgtm
  • C# LGTM query suite: ${semmle_home}/queries/customer/default/csharp-lgtm
  • Go LGTM query suite: ${semmle_home}/language-packs/go/config/suites/lgtm
  • Java LGTM query suite:  ${semmle_home}/queries/customer/default/java-lgtm
  • JavaScript LGTM query suite: ${semmle_home}/queries/customer/default/javascript-lgtm
  • Python LGTM query suite: ${semmle_home}/queries/customer/default/python-lgtm

where $(semmle-home) is the top-level QL command-line tools directory containing the queriesprojects and tools directories.

Extracting query metadata

The metadata defined in a query file provides detailed information about the query which may be useful to store in a results file of its own. You can extract the metadata associated with the queries referenced in a query suite using the exportQueryMetadata command. This command takes a query suite, or one or more query files, and outputs the metadata into a SARIF v2 results file. For example, to extract the metadata defined in the queries referenced in a custom query suite, you would run the following command:

odasa exportQueryMetadata --suite ${semmle_home}/custom-queries/query-suite --output custom-suite-metadata.sarif 

where  ${semmle_home}/custom-queries/query-suite is the path of your custom query suite and custom-suite-metadata.sarif is the SARIF v2 file to store the metadata in. See exportQueryMetadata for more information about the command and Query metadata for more information about query file metadata.

What next?

After defining a query suite you can generate query results using the command line tools.