Synopsis

codeql database run-queries [--threads=<num>] [--ram=<MB>] <options>... -- <database> <query|dir|suite|pack>...

codeql database run-queries [--threads=<num>] [--ram=<MB>] <options>... -- <database> <query|dir|suite|pack>...

Description

[Plumbing] Run a set of queries together.

Run one or more queries against a CodeQL database, saving the results tothe results subdirectory of the database directory.

The results can later be converted to readable formats bycodeql database interpret-results, or query-for-query by withcodeql bqrs decode orcodeql bqrs interpret.

If your queries produce results in a form that can be interpreted assource-code alerts, you may findcodeql database analyze a more convenient way to run them.codeql database analyze combinescodeql database run-queries withcodeql database interpret-results in a single step. In particular,codeql database analyze can produce output in the SARIF format, which can be used with an variety of alert viewers.

Alternatively, if you have only a single query to run, you might prefercodeql query run, which can display human-readable output for quick inspection of results while you're debugging.

Options

Primary Options

<database>

[Mandatory] Path to the CodeQL database to query.

<query|dir|suite|pack>...

Queries to execute. Each argument is in the formscope/name@range:pathwhere:

• scope/name is the qualified name of a CodeQL pack.
• range is a semver range.
• path is a file system path.

If ascope/name is specified, therange andpath are optional. Amissingrange implies the latest version of the specified pack. Amissingpath implies the default query suite of the specified pack.

Thepath can be one of a*.ql query file, a directory containing oneor more queries, or a.qls query suite file. If there is no pack namespecified, then apath must be provided, and will be interpretedrelative to the current working directory of the current process.

To specify apath that contains a literal@ or:, usepath: as aprefix to the argument, like this:path:directory/with:and@/chars.

If ascope/name andpath are specified, then thepath cannot beabsolute. It is considered relative to the root of the CodeQL pack.

If no queries are specified, the CLI will automatically determine asuitable set of queries to run. In particular, if a Code Scanningconfiguration file was specified at database creation time using--codescanning-config then the queries from this will be used.Otherwise, the default queries for the language being analyzed will beused.

--no-rerun

Omit evaluation of queries that already seem to have a BQRS resultstored in the output location.

--no-database-extension-packs

[Advanced] Omit extension packs stored in the database during databasecreation, either from a Code Scanning configuration file or fromextension files stored in the 'extensions' directory of the analyzedcodebase.

--no-database-threat-models

[Advanced] Omit threat model configuration stored in the databaseduring database creation from a Code Scanning configuration file.

Options to control the model packs to be used

--model-packs=<name@range>...

A list of CodeQL pack names, each with an optional version range, to beused as model packs to customize the queries that are about to beevaluated.

Options to control the threat models to be used

--threat-model=<name>...

A list of threat models to enable or disable.

The argument is the name of a threat model, optionally preceded by a'!'. If no '!' is present, the named threat model and all of itsdescendants are enabled. If a '!' is present, the named threat modeland all of its descendants are disabled.

The 'default' threat model is enabled by default, but can be disabledby specifying '--threat-model !default'.

The 'all' threat model can be used to enable or disable all threatmodels.

The --threat-model options are processed in order. For example,'--threat-model local --threat-model !environment' enables all ofthe threat models in the 'local' group except for the 'environment'threat model.

This option only has an effect for languages that support threat models.

Available sincev2.15.3.

Options to control the query evaluator

--[no-]tuple-counting

[Advanced] Display tuple counts for each evaluation step in the queryevaluator logs. If the--evaluator-log option is provided, tuplecounts will be included in both the text-based and structured JSON logsproduced by the command. (This can be useful for performanceoptimization of complex QL code).

--timeout=<seconds>

[Advanced] Set the timeout length for query evaluation, in seconds.

The timeout feature is intended to catch cases where a complex querywould take "forever" to evaluate. It is not an effective way to limitthe total amount of time the query evaluation can take. The evaluationwill be allowed to continue as long as each separately timed part of thecomputation completes within the timeout. Currently these separatelytimed parts are "RA layers" of the optimized query, but that mightchange in the future.

If no timeout is specified, or is given as 0, no timeout will be set(except forcodeql test run, where the default timeout is 5 minutes).

-j, --threads=<num>

Use this many threads to evaluate queries.

Defaults to 1. You can pass 0 to use one thread per core on the machine,or -N to leaveN cores unused (except still use at least onethread).

--[no-]save-cache

[Advanced] Aggressively write intermediate results to the disk cache.This takes more time and uses (much) more disk space, but may speed upthe subsequent execution of similar queries.

--[no-]expect-discarded-cache

[Advanced] Make decisions about which predicates to evaluate, and whatto write to the disk cache, based on the assumption that the cache willbe discarded after the queries have been executed.

--[no-]keep-full-cache

[Advanced] Don't clean up the disk cache after evaluation completes.This may save time if you're going to docodeql dataset cleanup orcodeql database cleanup afterwards anyway.

--max-disk-cache=<MB>

Set the maximum amount of space that the disk cache for intermediatequery results can use.

If this size is not configured explicitly, the evaluator will try to usea "reasonable" amount of cache space, based on the size of the datasetand the complexity of the queries. Explicitly setting a higher limitthan this default usage will enable additional caching which can speedup later queries.

--min-disk-free=<MB>

[Advanced] Set target amount of free space on file system.

If--max-disk-cache is not given, the evaluator will try hard tocurtail disk cache usage if the free space on the file system dropsbelow this value.

--min-disk-free-pct=<pct>

[Advanced] Set target fraction of free space on file system.

If--max-disk-cache is not given, the evaluator will try hard tocurtail disk cache usage if the free space on the file system dropsbelow this percentage.

--external=<pred>=<file.csv>

A CSV file that contains rows for external predicate<pred>.Multiple--external options can be supplied.

--xterm-progress=<mode>

[Advanced] Controls whether to show progress tracking during QLevaluation using xterm control sequences. Possible values are:

no: Never produce fancy progress; assume a dumb terminal.

auto(default): Autodetect whether the command is running in anappropriate terminal.

yes: Assume the terminal can understand xterm control sequences. Thefeature still depends on being able to autodetect thesize of theterminal, and will also be disabled if-q is given.

25x80 (or similar): Likeyes, and also explicitly give the size ofthe terminal.

25x80:/dev/pts/17 (or similar): show fancy progress on adifferentterminal than stderr. Mostly useful for internal testing.

Options for controlling outputting of structured evaluator logs

--evaluator-log=<file>

[Advanced] Output structured logs about evaluator performance to thegiven file. The format of this log file is subject to change with nonotice, but will be a stream of JSON objects separated by either twonewline characters (by default) or one if the--evaluator-log-minifyoption is passed. Please usecodeql generate log-summary <file> toproduce a more stable summary of this file, and avoid parsing the filedirectly. The file will be overwritten if it already exists.

--evaluator-log-minify

[Advanced] If the--evaluator-log option is passed, also passingthis option will minimize the size of the JSON log produced, at theexpense of making it much less human readable.

Options to control RAM usage

-M, --ram=<MB>

The query evaluator will try hard to keep its total memory footprintbelow this value. (However, for large databases it is possible that thethreshold may be broken by file-backed memory maps, which can be swappedto disk in case of memory pressure).

The value should be at least 2048 MB; smaller values will betransparently rounded up.

Options to control QL compilation

--warnings=<mode>

How to handle warnings from the QL compiler. One of:

hide: Suppress warnings.

show(default): Print warnings but continue with compilation.

error: Treat warnings as errors.

--no-debug-info

Don't emit source location info in RA for debugging.

--[no-]fast-compilation

[Deprecated] [Advanced] Omit particularly slow optimization steps.

--no-release-compatibility

[Advanced] Use the newest compiler features, at the cost ofportability.

From time to time, new QL language features and evaluator optimizationswill be supported by the QL evaluator a few releases before they areenabled by default in the QL compiler. This helps ensure that theperformance you experience when developing queries in the newest CodeQLrelease can be matched by slightly older releases that may still be inuse for Code Scanning or CI integrations.

If you do not care about your queries being compatible with other(earlier or later) CodeQL releases, you can sometimes achieve a smallamount of extra performance by using this flag to enable recentimprovements in the compiler early.

In releases where there are no recent improvements to enable, thisoption silently does nothing. Thus it is safe to set it once and for allin your global CodeQL config file.

Available sincev2.11.1.

--[no-]local-checking

Only perform initial checks on the part of the QL source that is used.

--no-metadata-verification

Don't check embedded query metadata in QLDoc comments for validity.

--compilation-cache-size=<MB>

[Advanced] Override the default maximum size for a compilation cachedirectory.

--fail-on-ambiguous-relation-name

[Advanced] Fail compilation if an ambiguous relation name is generatedduring compilation.

Options to set up compilation environment

--search-path=<dir>[:<dir>...]

A list of directories under which QL packs may be found. Each directorycan either be a QL pack (or bundle of packs containing a.codeqlmanifest.json file at the root) or the immediate parent of oneor more such directories.

If the path contains more than one directory, their order definesprecedence between them: when a pack name that must be resolved ismatched in more than one of the directory trees, the one given firstwins.

Pointing this at a checkout of the open-source CodeQL repository oughtto work when querying one of the languages that live there.

If you have checked out the CodeQL repository as a sibling of theunpacked CodeQL toolchain, you don't need to give this option; suchsibling directories will always be searched for QL packs that cannot befound otherwise. (If this default does not work, it is stronglyrecommended to set up--search-path once and for all in a per-userconfiguration file).

(Note: On Windows the path separator is;).

--additional-packs=<dir>[:<dir>...]

If this list of directories is given, they will be searched for packsbefore the ones in--search-path. The order between these doesn'tmatter; it is an error if a pack name is found in two different placesthrough this list.

This is useful if you're temporarily developing a new version of a packthat also appears in the default path. On the other hand, it isnotrecommended to override this option in a config file; some internalactions will add this option on the fly, overriding any configuredvalue.

(Note: On Windows the path separator is;).

--library-path=<dir>[:<dir>...]

[Advanced] An optional list of directories that will be added to theraw import search path for QL libraries. This should only be used ifyou're using QL libraries that have not been packaged as QL packs.

(Note: On Windows the path separator is;).

--dbscheme=<file>

[Advanced] Explicitly define which dbscheme queries should be compiledagainst. This should only be given by callers that are extremely surewhat they're doing.

--compilation-cache=<dir>

[Advanced] Specify an additional directory to use as a compilationcache.

--no-default-compilation-cache

[Advanced] Don't use compilation caches in standard locations such asin the QL pack containing the query or in the CodeQL toolchaindirectory.

Options for configuring the CodeQL package manager

--registries-auth-stdin

Authenticate to GitHub Enterprise Server Container registries by passinga comma-separated list of <registry_url>=<token> pairs.

For example, you can passhttps://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2to authenticate to two GitHub Enterprise Server instances.

This overrides the CODEQL_REGISTRIES_AUTH and GITHUB_TOKEN environmentvariables. If you only need to authenticate to the github.com Containerregistry, you can instead authenticate using the simpler--github-auth-stdin option.

--github-auth-stdin

Authenticate to the github.com Container registry by passing agithub.com GitHub Apps token or personal access token via standardinput.

To authenticate to GitHub Enterprise Server Container registries, pass--registries-auth-stdin or use the CODEQL_REGISTRIES_AUTH environmentvariable.

This overrides the GITHUB_TOKEN environment variable.

Common options

-h, --help

Show this help text.

-J=<opt>

[Advanced] Give option to the JVM running the command.

(Beware that options containing spaces will not be handled correctly.)

-v, --verbose

Incrementally increase the number of progress messages printed.

-q, --quiet

Incrementally decrease the number of progress messages printed.

--verbosity=<level>

[Advanced] Explicitly set the verbosity level to one of errors,warnings, progress, progress+, progress++, progress+++. Overrides-vand-q.

--logdir=<dir>

[Advanced] Write detailed logs to one or more files in the givendirectory, with generated names that include timestamps and the name ofthe running subcommand.

(To write a log file with a name you have full control over, insteadgive--log-to-stderr and redirect stderr as desired.)

--common-caches=<dir>

[Advanced] Controls the location of cached data on disk that willpersist between several runs of the CLI, such as downloaded QL packs andcompiled query plans. If not set explicitly, this defaults to adirectory named.codeql in the user's home directory; it will becreated if it doesn't already exist.

Available sincev2.15.2.