This topic describes queries and how they are used in Semmle Core analysis.
All Semmle analysis is defined by one or more queries. Queries are written using QL – Semmle's query language. QL is an object-oriented language optimized to provide rapid results to hierarchical queries.
Each query file defines a query to run on a project snapshot. Queries are used to:
- Calculate metrics for display in a client application.
- Identify code that breaks a rule and display a relevant alert message.
- Filter the results of another query.
Semmle Core includes a library of standard queries that are installed in the
queries subdirectory. The queries are loosely grouped by type, programming language and by coding standard or purpose. Each query has associate metadata that describe its properties and purpose. You can run queries on a snapshot using several different commands.
How do I define which queries to run?
Analysis is carried out when you run certain commands, using one or more queries. The queries that are run by a command can be specified in different ways, depending on how the command works. For example, the
analyzeSnapshot command has the
--suite flags, which allow you to specify either the individual query files or a query suite file to run on a snapshot. For further information, see generating query results using command line tools.
How do I add a custom query?
You can write your own custom queries using one of the QL plugins or extensions. See Learning QL for details. When you have written a new query, it should be saved in a new directory outside the Semmle Core distribution directory. This simplifies the Semmle Core upgrade process. See Adding custom queries for more information about adding custom queries to Semmle Core analysis.
What happens to my query?
When a query command is run, all of the queries specified with the
--suite flags are evaluated for the chosen snapshot. Queries can be divided into different categories:
- Metric queries – All metric queries are evaluated for the snapshot. The resulting quality measures are recorded and available for display in client applications
- Alert queries – All alert queries are tested on the snapshot. Any violations of the alert are recorded. These queries find code that violates best practice or that may contain defects. The violations can be displayed in client applications
- Filter queries – Each filter query is applied as defined in the query suite. Only results that pass the filter are reported. See Filtering data for more details.
In addition, any metric query can be configured as a rule by defining a limit for the query.