注意：本文已于 2023 年 1 月从 CodeQL 文档网站迁移。
关于自定义查询和 CodeQL CLI
可以通过编写自己的查询来突出显示特定漏洞或错误来自定义 CodeQL 分析。
本主题专门介绍如何编写要与数据库分析命令一起使用的查询，用于生成解释结果。
注意：使用 database analyze 运行的查询具有严格的元数据要求。 还可使用以下管道级子命令执行查询：
- database run-queries，此命令以称为 BQRS 的中间二进制格式输出非解释结果。
- query run，此命令将输出 BQRS 文件，或将结果表直接输出到命令行。 直接在命令行中查看结果对于使用 CLI 进行迭代查询开发可能很有用。
使用这些命令运行的查询具有不同的元数据要求。 但是，若要保存人类可读数据，必须使用 bqrs decode 管道子命令处理每个 BQRS 结果文件。 因此，对于大多数用例，最简单的方法是使用数据库分析直接生成解释结果。
编写有效查询
在运行自定义分析之前，需要编写有效的查询，并将其保存在扩展名为的 .ql 文件中。 有大量文档可帮助你编写查询。 有关详细信息，请参阅“CodeQL 查询”。
包括查询元数据
查询元数据包含在每个查询文件的顶部。 它为用户提供有关查询的信息，并告知 CodeQL CLI 如何处理查询结果。
使用 database analyze 命令运行查询时，必须包含以下两个属性，以确保正确解释结果：
-
查询标识符 (
@id)：由小写字母或数字组成的单词序列，由/或-分隔，用于标识查询并对其进行分类。 -
查询类型 (
@kind)：将查询标识为简单警报 (@kind problem)、由一系列代码位置记录的警报 (@kind path-problem)、用于提取器故障排除 (@kind diagnostic) 或摘要指标（@kind metric和@tags summary）。
有关这些元数据属性的详细信息，请参阅“CodeQL 查询的元数据”和查询元数据样式指南。
注意：如果要将查询与其他应用程序一起使用，则元数据要求可能会有所不同。 有关详细信息，请参阅“CodeQL 查询的元数据”。
打包自定义 QL 查询
注意：CodeQL 包管理功能（包括 CodeQL 包）目前作为 beta 版本提供，可能会发生变化。 在 beta 版本发布期间，CodeQL 包只能使用 GitHub 包，即 Container registry。 若要使用此 beta 版本功能，请从以下位置安装最新版本的 CodeQL CLI 捆绑包： https://github.com/github/codeql-action/releases 。
如果要编写自己的查询以与他人共享时，应将其保存在自定义 CodeQL 包中。 可以将包作为 CodeQL 包发布到 GitHub Packages - GitHub Container registry。 有关详细信息，请参阅“关于 CodeQL 包”。
CodeQL 包可组织 CodeQL 分析中使用的文件，并且可以存储查询、库文件、查询套件和重要元数据。 其根目录必须包含名为 qlpack.yml 的文件。 自定义查询应保存在 CodeQL 包根目录或其子目录中。
对于每个 CodeQL 包，qlpack.yml 文件包含的信息指示 CodeQL CLI 如何编译查询、包所依赖的其他 CodeQL 包和库，以及在哪里可以找到查询套件定义。 有关要包含在此文件中的内容的详细信息，请参阅“关于 CodeQL 包”。
参与 CodeQL 存储库
如果要与其他 CodeQL 用户共享查询，可以在 CodeQL 存储库中打开拉取请求。 有关详细信息，请参阅 参与 CodeQL。