Orbit

A property graph built from GitLab instance data (SDLC metadata and source code structure), queryable over HTTP, gRPC, and MCP.

Language

Product

GitLab Orbit: The product. Previously named GitLab Knowledge Graph. Builds a property graph from GitLab data and serves user-scoped, JWT-authenticated queries against it. Has two parts: the GitLab Orbit API and the GitLab Orbit CLI. Do not shorten to Orbit in docs. Avoid: Orbit, KGaaS, Knowledge Graph Service, Orbit Remote, "Orbit service"

GKG: Retired engineering abbreviation for Orbit ("GitLab Knowledge Graph"). Still present in the binary name (gkg-server), metrics, and pinned wire/database names. Avoid: using GKG in user-facing contexts

GitLab Orbit API: The REST, GraphQL, and MCP endpoints of GitLab Orbit on a GitLab instance. The GitLab Orbit CLI, agents, and GitLab Duo Agent Platform call them. Avoid: remote graph, "the server", "production GKG"

GitLab Orbit CLI: The orbit binary. glab orbit installs it and forwards all verbs to it. query, status, and schema call the GitLab Orbit API, and skills calls it when a credential is available. The workspace group (index, sql, schema, list, mcp serve) uses only the Local graph. grep and context combine both. Both read the Local graph. grep also searches GitLab entities through the GitLab Orbit API grep endpoint. context also reads GitLab entity tokens such as MergeRequest[42] through the context endpoint. Avoid: Orbit CLI, Orbit Local, "local mode", "remote mode"

Local graph: The DuckDB graph the GitLab Orbit CLI builds from a repository on the machine. Part of GitLab Orbit: it covers local code that GitLab Orbit on the GitLab instance does not have. grep and context index the working tree on their own. Avoid: Orbit Local

Skill Placeholder: A line-oriented HTML comment that marks where a local section belongs in the standalone skill that GitLab Orbit serves. Builds require each placeholder to have one matching local section. Both source trees remain independently usable, and the current CLI still serves only its embedded local tree. Avoid: include directive (the source files remain independently usable)

Graph model

Property Graph: A data model where typed Nodes carry properties and typed directed Relationships connect them. The foundational abstraction of Orbit. Avoid: knowledge graph (too vague), graph database (refers to the storage layer)

Node: A typed entity in the property graph representing a GitLab object (e.g., Project, MergeRequest, File, Definition). Each node type is defined in the Ontology and stored in a dedicated table (ClickHouse in GitLab Orbit, DuckDB in the Local graph). Called entity in the Query DSL. Avoid: vertex

Relationship: A typed directed connection between two Nodes (e.g., AUTHORED, CONTAINS, IN_PROJECT). Defined in the Ontology with one or more source→target Node type variants. Stored in physical edge tables. Avoid: interaction, link

Derived Entity: A third Ontology shape alongside Node and Relationship: one or more Pipelines with no node table. A named Rust transform turns their extracted rows into Relationships. Declared per domain in schema.yaml and implemented in config/ontology/derived/. A derived entity stays dormant until its transform.type is registered in Rust. Used for entities (e.g. SystemNote) whose graph shape can't be a SQL row-projection. They need multi-hop datalake reads or free-text parsing. See ADR 015. Avoid: storageless node, derived node

Pipeline: An Ontology ETL unit with extract and transform sections. Nodes, Relationships, and Derived Entities all use this shape. The extract names source tables and cursor ordering. It uses either a .sql.j2 template next to the YAML that references it, or query: generated (optionally with an extract.filter predicate). The transform is datafusion or a registered Rust transform. Avoid: old-style etl block

Ontology: The YAML-defined schema of the property graph. Declares all Node types, Relationship types, Derived Entity definitions, their properties, and valid source→target pairings. Lives in config/ontology/. The single source of truth for what the graph can contain. Avoid: schema (too generic), data model (refers to the broader design)

WorkItem: The unified Node type for all trackable units of work: issues, epics, tasks, incidents, test cases, requirements, objectives, key results. Distinguished by the work_item_type property. There are no separate Issue or Epic node types. Avoid: Issue, Epic (these are work item types, not separate graph entities)

Graph partitions

SDLC (Software Development Lifecycle) Data: The sub-graph of GitLab platform entities: projects, groups, merge requests, work items, pipelines, vulnerabilities, users. Distinguished from Code Graph data. Indexed from the Datalake via the SDLC indexing pipeline. Avoid: namespace graph (outdated alias)

Code Graph: The sub-graph of source code structure and relationships: branches, directories, files, definitions, imported symbols, and their connections (containment, calls, imports, inheritance). Distinguished from SDLC Data. Built by parsing repository contents via Gitaly. Avoid: call graph (refers only to invocation relationships, not the full sub-graph)

YAML Document Type: A declarative config (one YAML file under crates/code-graph/src/v2/langs/generic/yaml/document_types/) tells the Code Graph which YAML files it claims. It claims them by filename, directory, or top-level keys. It also names which of their keys become definitions or imports. Shipped types: GitLab CI, ArgoCD, Helm chart, Helm values, Docker Compose. YAML that no document type claims keeps only its File node plus anchor definitions and alias references. Avoid: YAML dialect, YAML schema (that is the JSON schema the configs are validated against)

Namespace Partitioning: The physical PARTITION BY of every graph table carrying a Traversal Path. It is keyed by a hash bucket of the top-level Namespace (sipHash64(top_level_ns) % N, declared once in settings.partition). Gives each tenant bucket its own ClickHouse part budget so one tenant's reindex burst cannot dead-letter inserts for the rest. A query scoped to a single top-level namespace also prunes to one bucket: the compiler emits the same bucket expression as a predicate. A storage-layer property, distinct from the logical SDLC/Code sub-graphs and from the read-side extraction slices used for parallel initial loads. Avoid: sharding (Orbit does not shard); conflating with the SDLC/Code "graph partitions" sub-graph split.

Authorization

Traversal Path: The slash-delimited ancestor Namespace hierarchy for an entity (e.g., "42/100/1000/"). Encodes Organization, group, and subgroup lineage. Used for hierarchical permission filtering: queries are scoped to paths the user is authorized for via prefix matching. Avoid: traversal ID, traversal_ids (these refer to the array encoding of the same concept)

Namespace: A GitLab group at any level of the hierarchy. The root namespace (top-level group) is the unit of indexing dispatch and deletion. The full namespace hierarchy is encoded in the Traversal Path of descendant entities. Represented in the graph as a Group Node. Avoid: tenant (Orbit uses Organization for tenant isolation)

Organization: The top-level tenant boundary. The first segment of every Traversal Path. All data within Orbit is segregated by organization at the storage layer. Avoid: org, tenant (too informal / too generic)

Redaction: Post-query authorization filtering where the service calls GitLab Rails to check per-resource permissions (Ability.allowed?). Rows the user cannot access are removed from the result. Handles cases that Traversal Path filtering cannot catch: confidential issues, runtime access controls, role-gated entities. Avoid: filtering (too generic), content masking (misleading: entire rows are removed, not obscured)

Data pipeline

CDC (Change Data Capture): The pattern of capturing row-level changes from a source database as a stream of events. In Orbit, CDC flows from the GitLab PostgreSQL database through Siphon into the Datalake. Avoid: replication (too broad)

Dispatch ID: A UUID stamped on each indexing request message. It identifies one dispatch unit: per (namespace × cycle) for SDLC namespace dispatch, and per cycle for the global and code dispatchers. Propagated to the IndexingObserver and tracing spans for correlation. Avoid: request ID, trace ID (dispatch_id groups many requests, not a single one)

Campaign: The parent correlation above Dispatch ID: one campaign per "re-index everything" decision, null in steady state. Today a campaign is a schema migration: opened (migration-v<N>) when the dispatcher marks a version migrating, and closed when the migration completes (promotion to active). Every dispatch during the migration carries it. Held in process memory (CampaignState), not persisted. Lets analysts aggregate the cost of one re-index across pipelines without time-based joins. Avoid: batch, job (a campaign spans many dispatches and both pipelines)

Migration ledger: config/schema-migrations.yaml, one entry per SCHEMA_VERSION bump declaring how much of the graph that version invalidates (scope: "*" | sdlc | code, optional entities). A clone-based schema migration reads it to decide what to clone versus rebuild. Entries are auto-derived from a fingerprint snapshot by mise schema:bump; humans may only widen them. Avoid: changelog, migration script (there is no per-version SQL)

Siphon: The GitLab CDC service. Captures PostgreSQL logical replication events and publishes them to NATS JetStream. External to Orbit, owned by the Analytics team. Avoid: CDC bridge, producer

Datalake: The ClickHouse database containing raw CDC rows replicated from GitLab PostgreSQL via Siphon. Tables are prefixed siphon_. The source data for ETL into graph tables. Avoid: data lake, raw data tables, lake

Query system

Query DSL: The JSON-based query language for the property graph. Supports four query types: traversal, aggregation, path_finding, and neighbors. Compiled to parameterized ClickHouse SQL. Versioned by QUERY_DSL_VERSION. Avoid: intermediate query language, intermediary LLM query language, JSON query language

Orbit Query Frontend: A compiler-level interface for Orbit's read-only graph language. The gql frontend module converts Pest pairs into a typed syntax tree, then lowers it into compiler Input. Rails selects it per user with the default-off orbit_gql_queries feature flag and sets the protobuf QueryLanguage enum, independently of raw or named source kind. JSON Query DSL and GQL are mutually exclusive modes, not client-selected languages. Avoid: Describing Orbit Query as the default query language

Named Query: A graph query defined in YAML under config/named_queries/ and invoked by name. Each definition carries a JSON Query DSL spelling and a GQL spelling of the same shape; Rails sets QUERY_TYPE_NAMED and a separate QueryLanguage value. That language selects both the spelling and the matching compiler frontend. Trusted templates encode client values and bind caller identity separately. Both rendered examples compile against the ontology in orbit-server unit tests so drift fails CI. Avoid: preset query, query template

Hop: A single Relationship traversal in the graph. Multi-hop queries traverse multiple relationships in sequence. Hard-capped at 3 hops for security and performance. Avoid: depth (ambiguous with tree depth)

Denormalized Join: A linear chain of tables declared under settings.denormalized_joins and pre-joined into one gl_denorm_<name> table. ClickHouse materialized views on each source table keep it current. Adjacent tables join on the ID that links them; every scoped table keeps its own Traversal Path in the row and the compiler filters each. Lets the compiler answer the matching Hops with one scan. Avoid: materialized table (the ClickHouse materialized views only feed it), projection (ClickHouse feature we deliberately do not use here). Distinct from the edge-tag denormalization settings block, which copies selected node properties onto edge rows.

Hydration: Fetching properties for Nodes discovered dynamically during query execution. Required for PathFinding and Neighbors queries where the result set's node types aren't known upfront. Avoid: enrichment, decoration

TOON (Token-Oriented Object Notation): A standard compact text encoding, used for every format=llm response. Query results list one table per node type, then an edge table. Schema, status, and health responses use it too. It replaced GOON (ADR 012). Avoid: GOON, LLM format

GQL Response Format: A cypher-shell style result table. Columns are node aliases, and cells hold node literals such as (:Label {id: 1, ...}). Used when queries specify format=gql (ADR 019). Avoid: Cypher output