Dark Mode
---
title: Custom CodeQL queries
shortTitle: Custom queries
intro: Custom queries extend {% data variables.product.prodname_codeql %}'s built-in security analysis to detect vulnerabilities and enforce coding standards specific to your codebase.
product: '{% data reusables.gated-features.codeql %}'
versions:
fpt: '*'
ghes: '*'
ghec: '*'
topics:
- Code Security
- Code scanning
- CodeQL
contentType: concepts
---
## What are custom {% data variables.product.prodname_codeql %} queries?
Custom queries extend {% data variables.product.prodname_codeql %}'s built-in security analysis to detect vulnerabilities, coding standards, and patterns specific to your codebase.
{% data reusables.codeql-cli.advanced-query-execution %}
## When to use custom queries
Use custom queries to:
* Detect vulnerabilities specific to your application's architecture or frameworks
* Enforce organization-specific coding standards or best practices
* Find patterns not covered by standard {% data variables.product.prodname_codeql %} query packs
* Analyze {% data variables.product.prodname_codeql %} databases with the `database analyze` command using the {% data variables.product.prodname_codeql_cli %} to produce interpreted results
## Query structure
Custom 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 {% data variables.product.prodname_codeql_cli %} how to process results. Required properties include:
* **Query identifier (`@id`)**: Lowercase letters or digits, delimited by `/` or `-`
* **Query type (`@kind`)**: One of:
* `problem` - Simple alert
* `path-problem` - Alert with code location sequence
* `diagnostic` - Extractor troubleshooting
* `metric` - 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 {% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queri es/metadata-for-codeql-queries/#metadata-for-codeql-queries) .
For more information about query metadata, see [Metadata for {% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queri es/metadata-for-codeql-queries/#metadata-for-codeql-queries) and the [Query metadata style guide](https://github.com/github/codeql/blob/main/docs/query -metadata-style-guide.md).
## Query documentation
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:
* **Markdown files**: Saved alongside the query, can be included in SARIF files and displayed in the {% data variables.product.prodname_code_scanning %} UI
* **`.qhelp` files**: Consistent with standard {% data variables.product.prodname_codeql %} queries, but must be converted to Markdown for use with {% data variables.product.prodname_code_scanning %}
When SARIF files containing query help are uploaded to {% data variables.product.prodname_dotcom %}, the documentation appears in the {% data variables.product.prodname_code_scanning %} UI for any alerts generated by the query.
For more information, see [Query help files](https://codeql.github.com/docs/writing-codeql-queries /query-help-files/#query-help-files).
## Sharing custom queries
You can share custom queries with the community by publishing your own query packs. See [AUTOTITLE](/code-security/tutorials/customize-code-scanning /publishing-and-using-codeql-packs).
## Further reading
* [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabili ties/scan-from-the-command-line/using-custom-queries-with-th e-codeql-cli)
* [{% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queri es/codeql-queries/#codeql-queries)