LGTM Enterprise 1.25

About queries

Queries are an essential part of LGTM as they screen codebases and return useful insights into the quality and health of a project.

What is a query and what is it for?

Queries, written using CodeQL, are used by LGTM to analyze project codebases. Each query file has a .ql extension and defines a query to run on a project snapshot. Queries are used to:

  • Calculate metrics for display in LGTM.
  • Identify code that breaks a rule and display a relevant alert message in LGTM.
  • Filter the results of another query.

There are two types of queries in LGTM:

  • Built-in queries—these are queries that come with LGTM. They are part of the default query suite for a given language, and they are run automatically when a project is added to LGTM.

    You can see whether a query is part of the default LGTM suite in the help for that query. For further details, see What are the properties of a query?

    You can hide results of specific built-in queries by configuring the lgtm.yml project configuration file. For more information, see Showing/hiding query results.

  • Custom queries—these are queries that YOU can write to tailor the LGTM analysis to suit your needs better. For further details, see Writing custom queries to include in LGTM analysis. You can run custom queries alongside the built-in queries. There are two types of custom queries:
    • Installation-wide custom queries—these queries are run across all your projects on your installation of LGTM. These can, for example, relate to coding guidelines specific to your organization, and enforce these coding best practices, globally.
    • Per-project custom queries—these queries are linked to a specific project and LGTM will run them for that project only.

What are query packs?

Query packs are named collections of queries. Queries are organized in query packs before they are processed in LGTM.

The naming convention is as follows for built-in queries: com.lgtm/<language-code>-queries. Let's take an example: the C/C++ language code is cpp, so the built-in C/C++ pack is called com.lgtm/cpp-queries. To learn more about language-code, refer to Analysis FAQs.

Installation-wide custom query packs are named <organization-id>/<language-code>-queries, where <organization-id> is a string specified by your LGTM administrator.

For per-project custom queries, LGTM will extract the queries and make them into a query pack. Query pack names are as follows: <organization-id>.<repository-provider>/<project-name>/<language-code>-queries.

How do I add custom queries to LGTM?

To add custom queries to LGTM:

  • For installation-wide custom queries, speak to your LGTM administrator who will be able to add them. Your administrator can upload query packs containing queries (.ql) and related files. To find out your organization's procedure for collecting and uploading custom queries and related files, contact your administrator.
  • For per-project custom queries, simply put the .ql files and any related files in a special directory in the repository for that project, by following these two rules:
    • The name and path of that special directory must be .lgtm/<language-code>-queries or lgtm/<language-code>-queries.
    • The .lgtm or lgtm directory must be created in the root directory of that project.

    LGTM will automatically extract the queries found in the special directory, make them into a query pack, and run them for that project only.

    The lgtm directory is preferred over the .lgtm directory if it exists. If both exist, the .lgtm directory is ignored.

    Custom queries placed in other locations within the repository, or inside a directory whose name doesn't exactly match the name given above won't be recognized by LGTM and won't be run.

    If a query pack fails to upload or doesn't pass the required checks (per-project custom queries only), you can explore the logs in the Logs page to find out why.

    Additionally, there are files related to custom queries that may need to be:

    • Given to your administrator, for inclusion in query packs (for installation-wide custom queries).
    • Placed in the same location inside the repository as the custom queries (for per-project custom queries).

    These files are:

    • The help file for the query—save this file as text file with a .qhelp extension. If you add a .qhelp file, it must have the same base name as the .ql file. It's not compulsory to add a help file for each query, but it's highly recommended to do so. That way, other users can understand the purpose of the query, and use it. Also, LGTM will display the help for that query. For more information, see Writing custom queries and Query help.
    • Any custom libraries you may want to import into the custom queries—save these libraries as text files with a .qll extension. (Library files from the standard libraries are automatically imported so you don't need to add them.)

    Authorization restrictions may apply. For example, users won't see results of queries for projects they are not allowed to see.

The project will be analyzed with the latest custom query sets.

What if I no longer want LGTM to run a custom query?

To stop running:

  • An installation-wide custom query—contact your LGTM administrator to discuss. If it makes sense to remove this query for all projects, your administrator will update the related query pack so it no longer contains that query file (and any related files), and upload the updated query pack to LGTM. If the query is required for other projects, the best solution is to hide its results for your project only.
  • A per-project custom query—remove the query and any related files from the special directory in the repository.

That query will no longer be run, and its results will be hidden in all views.

Related topicsRelated topics