hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2026-02-12 05:01:06 +01:00
Code Issues Packages Projects Releases Wiki Activity

expand overlay introduction with base/overlay context

Browse Source
This commit is contained in:
Philip Ginsbach
2026-01-19 13:57:19 +00:00
parent 4e478c3629
commit efe413cbd0
1 changed files with 14 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/codeql/ql-language-reference/annotations.rst
View File

@@ -508,11 +508,20 @@ Overlay annotations
===================
Overlay annotations control how predicates behave during **overlay evaluation**, a feature
that enables efficient incremental analysis by dividing QL code into *local* and *global*
parts. During overlay evaluation, local predicates are evaluated separately on "base" (cached
from previous analysis) and "overlay" (newly changed files) data. When a global predicate
calls a local predicate, results from both the base and overlay evaluations are combined,
with stale base results filtered out through a process called "discarding."
that enables efficient incremental analysis of codebases.
In overlay evaluation, a *base database* is created from one version of a codebase, and an
*overlay database* is created by combining the base database with changes from a newer
version (such as a pull request). The goal is to analyze the overlay database as if it
were a fully extracted database at the newer commit, while reusing as much cached data
from the base database as possible. Ideally, analysis time is proportional to the size
of the diff rather than the full codebase.
To achieve this, predicates are divided into *local* and *global* categories. Local
predicates are evaluated separately on base and overlay data, with results combined at
the frontier between local and global code. Global predicates operate on the combined
data. Local predicates typically take time proportional to the diff size, while global
predicates take time proportional to the full codebase.
Overlay evaluation is primarily used internally by GitHub Code Scanning to speed up
pull request analysis. Most QL developers do not need to use these annotations directly,