Custom queries extend CodeQL's built-in security analysis to detect vulnerabilities and enforce coding standards specific to your codebase.
Custom queries extend CodeQL's built-in security analysis to detect vulnerabilities, coding standards, and patterns specific to your codebase.
Note
Queries run with database analyze have strict metadata requirements. You can also execute queries using the following plumbing-level subcommands:
Queries run with these commands don’t have the same metadata requirements. However, to save human-readable data you have to process each BQRS results file using the bqrs decode plumbing subcommand. Therefore, for most use cases it’s easiest to use database analyze to directly generate interpreted results.
Use custom queries to:
database analyze command using the CodeQL CLI to produce interpreted resultsCustom queries are written in query files, which are saved with the .ql extension. These files also contain important metadata that provides information about the query's purpose and tells the CodeQL CLI how to process results. Required properties include:
@id): Lowercase letters or digits, delimited by / or -@kind): One of:
problem - Simple alertpath-problem - Alert with code location sequencediagnostic - Extractor troubleshootingmetric - Summary metric (requires @tags summary)Note
Metadata requirements may differ if you want to use your query with other applications. For more information, see Metadata for CodeQL queries.
For more information about query metadata, see Metadata for CodeQL queries and the Query metadata style guide.
Query documentation helps users understand what a query detects and how to address identified issues. You can include documentation for your custom queries in two formats:
.qhelp files: Consistent with standard CodeQL queries, but must be converted to Markdown for use with code scanningWhen SARIF files containing query help are uploaded to GitHub, the documentation appears in the code scanning UI for any alerts generated by the query.
For more information, see Query help files.
You can share custom queries with the community by publishing your own query packs. See Publishing and using CodeQL packs.