{"meta":{"title":"bqrs interpret","intro":"[Plumbing] Interpret data in a single BQRS.","product":"Security and code quality","breadcrumbs":[{"href":"/en/code-security","title":"Security and code quality"},{"href":"/en/code-security/reference","title":"Reference"},{"href":"/en/code-security/reference/code-scanning","title":"Code scanning"},{"href":"/en/code-security/reference/code-scanning/codeql","title":"CodeQL"},{"href":"/en/code-security/reference/code-scanning/codeql/codeql-cli-manual","title":"CodeQL CLI manual"},{"href":"/en/code-security/reference/code-scanning/codeql/codeql-cli-manual/bqrs-interpret","title":"bqrs interpret"}],"documentType":"article"},"body":"# bqrs interpret\n\n[Plumbing] Interpret data in a single BQRS.\n\n> [!NOTE]\n> This content describes the most recent release of the CodeQL CLI. For more information about this release, see https://github.com/github/codeql-cli-binaries/releases.\n>\n> To see details of the options available for this command in an earlier release, run the command with the <span style=\"white-space: nowrap;\">`--help`</span> option in your terminal.\n\n## Synopsis\n\n```shell copy\ncodeql bqrs interpret --format=<format> --output=<output> -t=<String=String> [--threads=<num>] [--source-archive=<sourceArchive>] [--source-location-prefix=<sourceLocationPrefix>] <options>... -- <bqrs-file>\n```\n\n## Description\n\n\\[Plumbing] Interpret data in a single BQRS.\n\nA command that interprets a single BQRS file according to the provided\nmetadata and generates output in the specified format.\n\n## Options\n\n### Primary Options\n\n#### `<bqrs-file>`\n\n\\[Mandatory] The BQRS file to interpret.\n\n#### `--format=<format>`\n\n\\[Mandatory] The format in which to write the results. One of:\n\n`csv`: Formatted comma-separated values, including columns with both\nrule and alert metadata.\n\n`sarif-latest`: Static Analysis Results Interchange Format (SARIF), a\nJSON-based format for describing static analysis results. This format\noption uses the most recent supported version (v2.1.0). This option is\nnot suitable for use in automation as it will produce different versions\nof SARIF between different CodeQL versions.\n\n`sarifv2.1.0`: SARIF v2.1.0.\n\n`graphtext`: A textual format representing a graph. Only compatible with\nqueries with @kind graph.\n\n`dgml`: Directed Graph Markup Language, an XML-based format for\ndescribing graphs. Only compatible with queries with @kind graph.\n\n`dot`: Graphviz DOT language, a text-based format for describing graphs.\nOnly compatible with queries with @kind graph.\n\n#### `-o, --output=<output>`\n\n\\[Mandatory] The output path to write results to. For graph formats\nthis should be a directory, and the result (or results if this command\nsupports interpreting more than one query) will be written within that\ndirectory.\n\n#### `-t=<String=String>`\n\n\\[Mandatory] A query metadata key value pair. Repeat for each piece of\nmetadata. At least the keys 'kind' and 'id' must be specified. Keys\ndo not need to be prefixed with @.\n\n#### `--max-paths=<maxPaths>`\n\nThe maximum number of paths to produce for each alert with paths.\n(Default: 4)\n\n#### `--[no-]sarif-add-file-contents`\n\n\\[SARIF formats only] Include the full file contents for all files\nreferenced in at least one result.\n\n#### `--[no-]sarif-add-snippets`\n\n\\[SARIF formats only] Include code snippets for each location mentioned\nin the results, with two lines of context before and after the reported\nlocation.\n\n#### `--[no-]sarif-add-query-help`\n\n\\[SARIF formats only] \\[Deprecated] Include Markdown query help for\nall queries. It loads query help for /path/to/query.ql from the\n/path/to/query.md file. If this flag is not supplied the default\nbehavior is to include help only for custom queries i.e. those in query\npacks which are not of the form \\`codeql/\\<lang\\&rt;-queries\\`. This\noption has no effect when passed to codeql bqrs interpret.\n\n#### `--sarif-include-query-help=<mode>`\n\n\\[SARIF formats only] Specify whether to include query help in the\nSARIF output. One of:\n\n`always`: Include query help for all queries.\n\n`custom_queries_only` _(default)_: Include query help only for custom\nqueries i.e. those in query packs which are not of the form\n\\`codeql/\\<lang\\&rt;-queries\\`.\n\n`never`: Do not include query help for any queries.\n\nThis option has no effect when passed to codeql bqrs interpret.\n\nAvailable since `v2.15.2`.\n\n#### `--no-sarif-include-alert-provenance`\n\n\\[Advanced] \\[SARIF formats only] Do not include alert provenance\ninformation in the SARIF output.\n\nAvailable since `v2.18.1`.\n\n#### `--[no-]sarif-group-rules-by-pack`\n\n\\[SARIF formats only] Place the rule object for each query under its\ncorresponding QL pack in the `<run>.tool.extensions` property. This\noption has no effect when passed to codeql bqrs interpret.\n\n#### `--[no-]sarif-multicause-markdown`\n\n\\[SARIF formats only] For alerts that have multiple causes, include\nthem as a Markdown-formatted itemized list in the output in addition to\nas a plain string.\n\n#### `--no-sarif-minify`\n\n\\[SARIF formats only] Produce pretty-printed SARIF output. By default,\nSARIF output is minified to reduce the size of the output file.\n\n#### `--sarif-run-property=<String=String>`\n\n\\[SARIF formats only] A key value pair to add to the generated SARIF\n'run' property bag. Can be repeated.\n\n#### `--no-group-results`\n\n\\[SARIF formats only] Produce one result per message, rather than one\nresult per unique location.\n\n#### `--csv-location-format=<csvLocationFormat>`\n\nThe format in which to produce locations in CSV output. One of: uri,\nline-column, offset-length. (Default: line-column)\n\n#### `--dot-location-url-format=<dotLocationUrlFormat>`\n\nA format string defining the format in which to produce file location\nURLs in DOT output. The following place holders can be used {path}\n{start:line} {start:column} {end:line} {end:column}, {offset}, {length}\n\n#### `--[no-]sublanguage-file-coverage`\n\n\\[GitHub.com and GitHub Enterprise Server v3.12.0+ only] Use\nsub-language file coverage information. This calculates, displays, and\nexports separate file coverage information for languages which share a\nCodeQL extractor like C and C++, Java and Kotlin, and JavaScript and\nTypeScript.\n\nAvailable since `v2.15.2`.\n\n#### `--sarif-category=<category>`\n\n\\[SARIF formats only] \\[Recommended] Specify a category for this\nanalysis to include in the SARIF output. A category can be used to\ndistinguish multiple analyses performed on the same commit and\nrepository, but on different languages or different parts of the code.\n\nIf you analyze the same version of a code base in several different ways\n(e.g., for different languages) and upload the results to GitHub for\npresentation in Code Scanning, this value should differ between each of\nthe analyses, which tells Code Scanning that the analyses _supplement_\nrather than _supersede_ each other. (The values should be consistent\nbetween runs of the same analysis for _different_ versions of the code\nbase.)\n\nThis value will appear (with a trailing slash appended if not already\npresent) as the `<run>.automationDetails.id` property.\n\n#### `-j, --threads=<num>`\n\nThe number of threads used for computing paths.\n\nDefaults to 1. You can pass 0 to use one thread per core on the machine,\nor -_N_ to leave _N_ cores unused (except still use at least one\nthread).\n\n#### `--column-kind=<columnKind>`\n\n\\[SARIF only] The column kind used to interpret location columns. One\nof: utf8, utf16, utf32, bytes.\n\n#### `--[no-]unicode-new-lines`\n\n\\[SARIF only] Whether the unicode newline characters LS (Line\nSeparator, U+2028) and PS (Paragraph Separator, U+2029) are considered\nas new lines when interpreting location line numbers.\n\n### Source archive options - must be given together or not at all\n\n#### `-s, --source-archive=<sourceArchive>`\n\nThe directory or zip file containing the source archive.\n\n#### `-p, --source-location-prefix=<sourceLocationPrefix>`\n\nThe file path on the original file system where the source code was\nstored.\n\n### Common options\n\n#### `-h, --help`\n\nShow this help text.\n\n#### `-J=<opt>`\n\n\\[Advanced] Give option to the JVM running the command.\n\n(Beware that options containing spaces will not be handled correctly.)\n\n#### `-v, --verbose`\n\nIncrementally increase the number of progress messages printed.\n\n#### `-q, --quiet`\n\nIncrementally decrease the number of progress messages printed.\n\n#### `--verbosity=<level>`\n\n\\[Advanced] Explicitly set the verbosity level to one of errors,\nwarnings, progress, progress+, progress++, progress+++. Overrides `-v`\nand `-q`.\n\n#### `--logdir=<dir>`\n\n\\[Advanced] Write detailed logs to one or more files in the given\ndirectory, with generated names that include timestamps and the name of\nthe running subcommand.\n\n(To write a log file with a name you have full control over, instead\ngive `--log-to-stderr` and redirect stderr as desired.)\n\n#### `--common-caches=<dir>`\n\n\\[Advanced] Controls the location of cached data on disk that will\npersist between several runs of the CLI, such as downloaded QL packs and\ncompiled query plans. If not set explicitly, this defaults to a\ndirectory named `.codeql` in the user's home directory; it will be\ncreated if it doesn't already exist.\n\nAvailable since `v2.15.2`."}