{"meta":{"title":"数据库运行查询","intro":"[Plumbing] 一起运行一组查询。","product":"安全性和代码质量","breadcrumbs":[{"href":"/zh/code-security","title":"安全性和代码质量"},{"href":"/zh/code-security/reference","title":"Reference"},{"href":"/zh/code-security/reference/code-scanning","title":"代码扫描"},{"href":"/zh/code-security/reference/code-scanning/codeql","title":"CodeQL"},{"href":"/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual","title":"CodeQL CLI 手册"},{"href":"/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-run-queries","title":"数据库运行查询"}],"documentType":"article"},"body":"# 数据库运行查询\n\n\\[Plumbing] 一起运行一组查询。\n\n> \\[!NOTE]\n> 此内容描述了 CodeQL CLI 的最新版本。 有关此版本的详细信息，请参阅 <https://github.com/github/codeql-cli-binaries/releases> 。\n>\n> 若要查看早期版本中此命令可用选项的详细信息，请在终端中使用 <span style=\"white-space: nowrap;\">`--help`</span> 选项运行命令。\n\n## 概要\n\n```shell copy\ncodeql database run-queries [--threads=<num>] [--ram=<MB>] <options>... -- <database> <query|dir|suite|pack>...\n```\n\n## Description\n\n```\n          \\[Plumbing] 一起运行一组查询。\n```\n\n针对 CodeQL 数据库运行一个或多个查询，并将结果保存到数据库目录的结果子目录。\n\n稍后可以通过 [codeql database interpret-results](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-interpret-results) 将结果转换为可读格式，或者通过 [codeql bqrs decode](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/bqrs-decode) 或 [codeql bqrs interpret](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/bqrs-interpret) 进行查询转换。\n\n如果查询以可解释为源代码警报的形式生成结果，你可能会发现 [codeql database analyze](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-analyze) 是运行它们的更方便的方法。\n[codeql database analyze](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-analyze) 在一个步骤中将 codeql database run-queries 与 [codeql database interpret-results](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-interpret-results) 相结合。 具体而言，[codeql database analyze](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-analyze) 可以生成 SARIF 格式的输出，该输出可与各种警报查看器一起使用。\n\n或者，如果只有一个查询要运行，你可能更偏好 [codeql query run](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/query-run)，这可以显示人工可读的输出，以便在调试时快速检查结果。\n\n## 选项\n\n### 主要选项\n\n#### `<database>`\n\n```\n          \\[必选] 要查询的 CodeQL 数据库的路径。\n```\n\n#### `<query|dir|suite|pack>...`\n\n要执行的查询。 每个参数均采用 `scope/name@range:path` 形式，其中：\n\n* `scope/name` 是 CodeQL 包的限定名称。\n* `range` 是语义化版本范围。\n* `path` 是文件系统路径。\n\n如果指定了 `scope/name`，则 `range` 和 `path` 是可选的。 如果没有 `range`，则表示使用指定包的最新版本。 如果缺少 `path`，则使用指定包的默认查询套件。\n\n```\n          `path` 可以是 `*.ql` 查询文件、包含一个或多个查询的目录或 `.qls` 查询套件文件。 如果未指定包名，则必须提供 `path`，并将其解释为相对于当前进程的当前工作目录。\n```\n\n要指定包含文字 `path` 或 `@` 的 `:`，请使用 `path:` 作为参数的前缀，如下所示：`path:directory/with:and@/chars`。\n\n如果指定 `scope/name` 和 `path`，则 `path` 不能是绝对的。 此路径应为 CodeQL 包的根的相对路径。\n\n如果未指定任何查询，CLI 将自动确定要运行的一组合适的查询。 具体而言，如果在创建数据库时使用 `--codescanning-config` 指定了代码扫描配置文件，则将使用来自此路径的查询。\n否则，将使用所分析语言的默认查询。\n\n#### `--no-rerun`\n\n省略对似乎已将 BQRS 结果存储在输出位置的查询的评估。\n\n#### `--no-database-extension-packs`\n\n```\n          \\[高级] 在数据库创建过程中，可以忽略存储在数据库中的扩展包，这些扩展包可能来自代码扫描配置文件或者分析代码库的“扩展”目录中的扩展文件。\n```\n\n#### `--no-database-threat-models`\n\n```\n          \\[高级] 在通过代码扫描配置文件创建数据库期间，忽略数据库中存储的威胁模型配置。\n```\n\n### 用于控制要使用的模型包的选项\n\n####\n\n```\n          `--model-packs=<`\n          <name@range>>...\n```\n\n将用作模型包的 CodeQL 包名称列表，每个包名称都有一个可选的版本范围，用于自定义即将评估的查询。\n\n### 控制要使用的威胁模型的选项\n\n#### `--threat-model=<name>...`\n\n要启用或禁用的威胁模型列表。\n\n该参数是威胁模型的名称，可以选择加“!”前缀。 如果“!”不存在，则启用指定的威胁模型及其所有后代。 如果“!”存在，则禁用指定的威胁模型及其所有后代。\n\n默认启用“default”威胁模型，但可以通过指定“--threat-model !default”来禁用。\n\n“all”威胁模型可用于启用或禁用所有威胁模型。\n\n\\--threat-model 选项按顺序进行处理。 例如，“--threat-model local --threat-model !environment”启用“local”组中除“environment”威胁模型之外的所有威胁模型。\n\n此选项仅对支持威胁模型的语言有效。\n\n自 `v2.15.3` 起可用。\n\n### 控制查询评估器的选项\n\n#### `--[no-]tuple-counting`\n\n```\n          \\[高级] 在查询计算器日志中显示每个评估步骤的元组计数。 如果提供了 `--evaluator-log` 选项，则元组计数将包含在命令生成的基于文本的 JSON 日志和结构化 JSON 日志中。 （这对复杂 QL 代码的性能优化非常有用）。\n```\n\n#### `--timeout=<seconds>`\n\n```\n          \\[高级] 设置查询评估的超时长度（以秒为单位）。\n```\n\n超时功能旨在捕获复杂查询需要“长久时间”来评估的情况。 这不是限制查询评估可花费的总时间的有效方法。 只要计算的每个单独计时部分在超时时间内完成，就允许评估继续进行。 目前，这些单独计时部分是已优化查询的“RA 层”，但将来可能会变化。\n\n如果未指定超时或将其指定为 0，则不会设置超时（[codeql test run](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/test-run) 除外，默认超时为 5 分钟）。\n\n#### `-j, --threads=<num>`\n\n使用如此多的线程来评估查询。\n\n默认值为 1。 可以传递 0 以在计算机上对每个核心都使用一个线程，也可以传递 -N 以将 N 个核心保留为未使用状态（仍至少使用一个线程的情况除外） 。\n\n#### `--[no-]save-cache`\n\n```\n          \\[已弃用] \\[高级] 此标志没有任何作用。\n```\n\n#### `--[no-]expect-discarded-cache`\n\n```\n          \\[高级] 基于查询执行后缓存将被丢弃的假设，决定哪些谓词需要评估，以及哪些内容需要写入磁盘缓存。\n```\n\n#### `--[no-]keep-full-cache`\n\n```\n          \\[高级] 评估完成后，不要清理磁盘缓存。\n```\n\n如果以后要执行 [codeql dataset cleanup](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/dataset-cleanup) 或 [codeql database cleanup](/zh/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-cleanup)，这样可能会节省时间。\n\n#### `--max-disk-cache=<MB>`\n\n设置磁盘缓存可用于中间查询结果的最大空间量。\n\n如果未显式配置此大小，计算器将根据数据集大小和查询复杂性尝试使用“合理的”缓存空间量。 显式设置高于此默认使用量的限制将启用额外的缓存，从而加快以后的查询速度。\n\n#### `--min-disk-free=<MB>`\n\n```\n          \\[高级] 设置文件系统上的目标可用空间量。\n```\n\n如果未提供 `--max-disk-cache`，当文件系统上的可用空间低于此值时，计算器便会努力减少磁盘缓存使用量。\n\n#### `--min-disk-free-pct=<pct>`\n\n```\n          \\[高级] 设置文件系统可用空间的目标部分。\n```\n\n如果未提供 `--max-disk-cache`，当文件系统上的可用空间低于此百分比时，计算器便会努力减少磁盘缓存使用量。\n\n#### `--external=<pred>=<file.csv>`\n\n包含外部谓词 *\\<pred>* 的行的 CSV 文件。\n可以提供多个 `--external` 选项。\n\n#### `--xterm-progress=<mode>`\n\n```\n          \\[高级] 控制在 QL 评估期间是否使用 xterm 控制序列显示进度跟踪。 可能的值为：\n\n          `no`：从不显示高级进度；假设为无交互终端。\n\n          `auto`（默认值）：自动检测命令是否在相应的终端中运行。\n\n          `yes`：假设终端可以理解 xterm 控制序列。 该功能仍取决于能否自动检测终端的大小（抱歉，Windows 系统暂未实现此功能），如果指定了 __，该功能也将被禁用`-q`。\n\n          `25x80`（或类似）：类似于 `yes`，并显式指定终端的大小。 （与 `yes` 不同，此功能应可在 Windows 操作系统上正常运行。）\n\n          `25x80:/dev/pts/17`（或类似）：在_不同于_标准错误输出的终端上显示高级进度。 主要对内部测试有用。\n```\n\n### 用于控制结构化评估器日志输出的选项\n\n#### `--evaluator-log=<file>`\n\n```\n          \\[高级] 将有关计算器性能的结构化日志输出到给定文件。 此日志文件的格式可能会随时更改且不会另行通知，但其内容将是JSON对象的流，其中对象间默认由两个换行符分隔，或在传递`--evaluator-log-minify`选项时由一个换行符分隔。 请使用 `codeql generate log-summary <file>` 生成此文件的更稳定的摘要，并避免直接分析该文件。 如果文件存在，将覆盖该文件。\n```\n\n#### `--evaluator-log-minify`\n\n```\n          \\[高级] 如果传递了 `--evaluator-log` 选项，则另外传递此选项将最大程度地减小生成的 JSON 日志的大小，但代价是降低其用户可读性。\n```\n\n### 用于控制 RAM 使用情况的选项\n\n#### `-M, --ram=<MB>`\n\n查询计算器将努力将其总内存占用情况保持在此值以下。 （不过，对于大型数据库，基于文件的内存映射可能会突破此阈值，在内存紧张时可交换到磁盘）。\n\n该值应至少为 2048 MB；较小的值将以透明方式向上舍入。\n\n### 用于控制 QL 编译的选项\n\n#### `--warnings=<mode>`\n\n如何处理来自 QL 编译器的警告。 下列其中一项：\n\n```\n          `hide`：禁止显示警告。\n\n          `show`（默认值）：输出警告，但继续编译。\n\n          `error`：将警告视为错误。\n```\n\n#### `--no-debug-info`\n\n在 RA 中不要发出源位置信息以供调试。\n\n#### `--[no-]fast-compilation`\n\n```\n          \\[已弃用] \\[高级] 省略特别缓慢的优化步骤。\n```\n\n#### `--no-release-compatibility`\n\n```\n          \\[高级] 使用最新的编译器功能，但代价是可移植性降低。\n```\n\nQL 评估器的部分版本将时不时支持新的 QL 语言功能和计算器优化并会在 QL 编译器中默认启用它们。 这有助于确保你在最新的 CodeQL 版本中开发查询时体验到的性能可以与代码扫描或 CI 集成中可能仍在使用的稍旧版本相匹配。\n\n如果你不关心查询是否与其他 CodeQL 版本（更低版本或更高版本）兼容，有时可以通过使用此标志提前在编译器中启用最新改进来实现少量的额外性能。\n\n如果版本中最近没有要启用的改进，此选项以无提示方式不执行任何操作。 因此，可以安全地在全局 CodeQL 配置文件中一劳永逸地设置它。\n\n自 `v2.11.1` 起可用。\n\n#### `--[no-]local-checking`\n\n仅对所使用的部分 QL 源执行初始检查。\n\n#### `--no-metadata-verification`\n\n为保证有效性，请勿在 QLDoc 注释中检查嵌入的查询元数据。\n\n#### `--compilation-cache-size=<MB>`\n\n```\n          \\[高级] 替代编译缓存目录的默认最大大小。\n```\n\n#### `--fail-on-ambiguous-relation-name`\n\n```\n          \\[高级] 如果在编译期间生成不明确的关系名称，则编译失败。\n```\n\n### 用于设置编译环境的选项\n\n#### `--search-path=<dir>[:<dir>...]`\n\n可在其中找到 QL 包的目录列表。 每个目录可以是一个 QL 包（或在根目录下包含一个 `.codeqlmanifest.json` 文件的多个包），也可以是一个或多个此类目录的直接父目录。\n\n如果路径包含多个目录，则它们的顺序定义了它们之间的优先级：当必须解析的包名称在多个目录树中匹配时，给定的第一个目录树优先。\n\n在查询其中一种语言时，将其指向开源 CodeQL 存储库的签出应该是可行的。\n\n如果已将 CodeQL 存储库签出为未打包的 CodeQL 工具链的同级，则无需提供此选项；将始终在此类同级目录中搜索以其他方式找不到的 QL 包。 （如果此默认值不起作用，强烈建议在每用户配置文件中一次性设置 `--search-path`）。\n\n（注意：在 Windows 上，路径分隔符为 `;`）。\n\n#### `--additional-packs=<dir>[:<dir>...]`\n\n如果给定了此目录列表，则先在这些目录中的搜索包，然后在 `--search-path` 中的目录搜索包。 它们之间的顺序并不重要；如果在此列表的两个不同位置发现同一个包名称，这是一个错误。\n\n如果你正临时开发一个同时出现在默认路径中的新版本的包，这将非常有用。 另一方面，建议不要在配置文件中替代此选项；一些内部操作将动态添加此选项，覆盖任何配置的值。\n\n（注意：在 Windows 上，路径分隔符为 `;`）。\n\n#### `--library-path=<dir>[:<dir>...]`\n\n```\n          \\[高级] 可选目录列表，这些目录将添加到 QL 库的原始导入搜索路径。 只有在使用未打包为 QL 包的 QL 库时，才应使用此选项。\n```\n\n（注意：在 Windows 上，路径分隔符为 `;`）。\n\n#### `--dbscheme=<file>`\n\n```\n          \\[高级] 显式定义应针对哪些 dbscheme 查询进行编译。 这只能由非常确定自己在做什么的调用方提供。\n```\n\n#### `--compilation-cache=<dir>`\n\n```\n          \\[高级] 指定要用作编译缓存的其他目录。\n```\n\n#### `--no-default-compilation-cache`\n\n```\n          \\[高级] 请勿在标准位置（例如在包含查询的 QL 包中或在 CodeQL 工具链目录中）使用编译缓存。\n```\n\n### 用于配置 CodeQL 包管理器的选项\n\n#### `--registries-auth-stdin`\n\n通过传递逗号分隔的 \\<registry\\_url>=\\<token> 对列表，向 GitHub Enterprise Server 容器注册表进行身份验证。\n\n例如，可以传递 `https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2`\n向两个 GitHub Enterprise Server 实例进行身份验证。\n\n这会替代 CODEQL\\_REGISTRIES\\_AUTH 和 GITHUB\\_TOKEN 环境变量。 如果只需向 github.com 容器注册表进行身份验证，则可以改用更简单的 `--github-auth-stdin` 选项进行身份验证。\n\n#### `--github-auth-stdin`\n\n通过标准输入传递 GitHub 应用程序令牌或个人访问令牌，以对 github.com 容器注册表进行身份验证。\n\n若要向 GitHub Enterprise Server 容器注册表进行身份验证，请传递 `--registries-auth-stdin` 或使用 CODEQL\\_REGISTRIES\\_AUTH 环境变量。\n\n这会替代 GITHUB\\_TOKEN 环境变量。\n\n### 常用选项\n\n#### `-h, --help`\n\n显示此帮助文本。\n\n#### `-J=<opt>`\n\n```\n          \\[高级] 为运行命令的 JVM 提供选项。\n```\n\n（请注意，无法正确处理包含空格的选项。）\n\n#### `-v, --verbose`\n\n以增量方式增加输出的进度消息数。\n\n#### `-q, --quiet`\n\n以增量方式减少输出的进度消息数。\n\n#### `--verbosity=<level>`\n\n```\n          \\[高级] 明确将详细级别设置为 errors、warnings、progress、progress+、progress++、progress+++ 之一。 重写 `-v` 和 `-q`。\n```\n\n#### `--logdir=<dir>`\n\n```\n          \\[高级] 将详细日志写入给定目录中的一个或多个文件，其中生成的名称包括时间戳和正在运行的子命令的名称。\n```\n\n（要使用可以完全控制的名称编写日志文件，请根据需要提供 `--log-to-stderr` 并重定向 stderr。）\n\n#### `--common-caches=<dir>`\n\n```\n          \\[高级] 控制磁盘上缓存数据的位置，此位置会在多次运行 CLI（例如下载的 QL 包和已编译查询计划）期间暂留。 如果未明确设置，则默认为用户主目录中名为 `.codeql` 的目录；如果尚不存在，则会创建该目录。\n```\n\n自 `v2.15.2` 起可用。"}