CodeQL glossary¶

An overview of the technical terms and concepts in CodeQL.

`.bqrs` file¶

A binary query result set (BQRS) file. BQRS is the binary representation of the raw result of a query, with the extension .bqrs. A BQRS file can be interpreted into meaningful results and related to your source code. For example, alert query results are interpreted to display a string at the location in the source code where the alert occurs, as specified in the query. Similarly, path query results are interpreted as pairs of locations (sources and sinks) between which information can flow. These results can be exported as a variety of different formats, including SARIF.

CodeQL database¶

A database (or CodeQL database) is a directory containing:

queryable data, extracted from the code.
a source reference, for displaying query results directly in the code.
query results.
log files generated during database creation, query execution, and other operations.

DIL¶

DIL stands for Datalog Intermediary Language. It is an intermediate representation between QL and relation algebra (RA) that is generated during query compilation. DIL is useful for advanced users as an aid for debugging query performance. The DIL format may change without warning between CLI releases.

When you specify the --dump-dil option for codeql query compile, CodeQL prints DIL to standard output for the queries it compiles. You can also view results in DIL format when you run queries in VS Code. For more information, see “Analyzing your projects” in the CodeQL for VS Code help.

Extractor¶

An extractor is a tool that produces the relational data and source reference for each input file, from which a CodeQL database can be built.

QL database schema¶

A QL database schema is a file describing the column types and extensional relations that make up a raw QL dataset. It is a text file with the .dbscheme extension.

The extractor and core QL pack for a language each declare the database schema that they use. This defines the database layout they create or expect. When you create a CodeQL database, the extractor copies its schema into the database. The CLI uses this to check whether the CodeQL database is compatible with a particular CodeQL library. If they aren’t compatible you can use database upgrade to upgrade the schema for the CodeQL database.

There is currently no public-facing specification for the syntax of schemas.

`.qlo` files¶

.qlo files are optionally generated during query compilation. If you specify the --dump-qlo option for codeql query compile, CodeQL writes .qlo files for the queries it compiles. They can be used as an aid for debugging and performance tuning for advanced users.

.qlo is a binary format that represents a compiled and optimized query in terms of relational algebra (RA) or the intermediate DIL format. .qlo files can be expanded to readable text using codeql query decompile.

The exact details of the .qlo format may change without warning between CLI releases.

SARIF file¶

Static analysis results interchange format (SARIF) is an output format used for sharing static analysis results. For more information, see “SARIF output.”

Source reference¶

A source reference is a mechanism that allows the retrieval of the contents of a source file, given an absolute filename at which that file resided during extraction. Specific examples include:

A source archive directory, within which the requested absolute filename maps to a UTF8-encoded file.
A source archive, typically in ZIP format, which contains the UTF8-encoded content of all source files.
A source archive repository, typically in git format, typically bare, which contains the UTF8-encoded content of all source files.

Source references are typically included in CodeQL databases.

TRAP file¶

A TRAP file is a UTF-8 encoded file generated by a CodeQL extractor with the extension .trap. To save space, they are usually archived. They contain the information that, when interpreted relative to a QL database schema, is used to create a QL dataset.