Semmle 1.19
Skip to end of metadata
Go to start of metadata

This topic describes how to run an individual query from the command line.

Overview

When you integrate Semmle analysis into a development process, you may need to run a query from a script or directly from the command line. For example, this is one method of creating a commit gate or build promotion step that is controlled by the results of Semmle analysis. As part of either of these processes, you can run any query from the command line using the runQuery command.

Prerequisites

Before you can run queries from the command line, you need to generate a snapshot database of your code to run queries against. For further information, see Generating a snapshot of your code

Running a query against a snapshot database

You can run a query in the command-line using the runquery command by specifying a query and a snapshot, as follows: 

 odasa runQuery --query <query-path>/query-name.ql --snapshot <snapshot-path>/<snapshot>

In this example:

  • <query-path>/query-name.ql defines the location of the query to run. 
  • <snapshot-path>/<snapshot> defines the location of the snapshot to analyze.

The paths used in the command used with the --query and --snapshot flags must specify locations relative to either the current directory, relative to one of the Semmle variables, or as an absolute path. When you run this command, the tool automatically detects an appropriate database schema and QL library to use for the analysis. In this case, the results generated by the query are output to the console in CSV format. However, if you want to output the results to a CSV file with column headings, then you can specify the --titles and --output-file flags. For further information on the flags available to customize the command, see runQuery.

Note that the runQuery command can accept either compiled or non-compiled queries. For more information about enabling or customizing query compilation using flags, see runQuery. For more general information about compiling queries, see prepareQueries.

Example

To run a custom query, FindErrorInCode.ql, stored in the odasa/queries/custom/java directory on a snapshot database, representing a specific revision of the source code created for the Hadoop project (stored in odasa/projects/Hadoop), you would run the following command from the odasa directory:

 odasa runQuery --query queries/custom/java/FindErrorInCode.ql --snapshot projects/Hadoop/revision-2017-December-14

In this case, the results generated by the FindErrorInCode.ql query would be output to the console in CSV format, without headings.

Customizing the output

The runQuery command only outputs raw query results, which cannot by used to highlight alerts in your source code. If you want to generate formatted results that can be imported into an IDE for code review, then you should use the analyzeSnapshot command. For further information, see Generating query results using command-line tools.