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.