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

Purpose

Query suites are used to define groups of queries within a single file in order to simplify query management during analysis. When grouping queries within a query suite, you can reference individual queries or other query suite files using the @import directive.  

Structure

When referencing individual queries and other query suite files, the path for each file you are referencing must be one of the following:

  • The location of the main Semmle Core queries directory (represented by the variable ${odasa_queries}) .
  • Relative to one of the predefined variables, such as SEMMLE_HOME.
  • An absolute path.

Individual queries

Each individual query is specified on a separate line using the following format:

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

where:

  • + 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 an optional category to assign the query to. For example Correctness/Logic errors.
  • @<optional query directive> is an optional directive used to alter the behavior of the preceding query. For further information, see Query directives.

Queries are assigned to default categories in the standard query suites included in the Semmle installation. Assigning a query to a category within a custom query suite is optional, but can simplify query management. For example, you can customize your analysis by filtering or disabling whole categories of queries. For further information, see Filtering data and Grouping queries.

Using the @import directive

Each @import directive imports a separate suite file, using the following format: 

@import <path>/<query-suite>

where:

  • <path> is the file path of the query, as defined above.
  • <query-suite> is the query suite file to import.

Example

If you wish to group a number of queries for analysis of 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

# Import a custom query suite defining the core custom queries
@import ${semmle_home}/custom-queries/java/core-custom-queries
 
# Add two extra custom queries
+ ${semmle_home}/custom-queries/java/CustomQuery1.ql: /Advisory/Declarations
+ ${semmle_home}/custom-queries/java/CustomQuery2.ql: /Correctness/Exceptions

The @import ${odasa_queries}/customer/default/java statement imports the default Semmle Core Java query suite  Additionally, @import ${semmle_home}/custom-queries/java/core-custom-queries imports a custom query suite.  Individual custom queries are referenced relative to the directory defined by the SEMMLE_HOME environment variable.

Notice that for @import directives, paths must be absolute or use Semmle variables, such as ${odasa_queries}, to define paths relative to one of the standard predefined variables included in Semmle Core. Any relative paths that do not include variables are assumed to be relative to the current context. In the example above the @import directive uses the ${odasa_queries} variable to define the location of the standard queries directory included with Semmle Core. The ${semmle_home} variable is used to define the location of the custom query suites and the individual custom query files. The java default query suite file contains import directives for each of the query suite files included in the installation for Java (for example: correctnessframeworks). Notice that in this file the paths have been defined relative to the java query suite file. That is, relative to ${odasa_queries}/customer/default/java:

Default Java query suite
@import "../../suites/java/correctness"
@import "../../suites/java/frameworks"
@import "../../suites/java/maintainability"
@import "../../suites/java/readability"
@import "../../suites/java/metrics"
@import "../../suites/java/metric-defects"