Orbit query language

Use the Orbit query language when you need GitLab data as a graph instead of a flat API response. A query is a JSON object. It names the entities to match, the relationships to follow, and the properties to return.

Query shape

Every query has a query_type and either node or nodes.

{
  "query_type": "traversal",
  "node": {
    "id": "mr",
    "entity": "MergeRequest",
    "node_ids": [12345],
    "columns": ["iid", "title", "state"]
  },
  "limit": 1
}

Use node for one node selector. Use nodes for an array of selectors. You cannot use both in the same query.

Query types

Single-node traversal is the search shape. There is no separate search query type.

Top-level fields

Node selectors

A node selector names one entity type in the ontology.

Use node_ids when you already know the graph ID. Use filters when you know a natural property such as username, full_path, state, or path.

Relationships

Relationships connect node selectors by alias.

{
  "type": "AUTHORED",
  "from": "user",
  "to": "mr",
  "direction": "outgoing"
}

For example, merge requests point to projects with IN_PROJECT, and users point to merge requests with AUTHORED.

Filters

Filters can use simple equality:

{
  "filters": {
    "state": "merged"
  }
}

Or they can use an operator:

{
  "filters": {
    "created_at": {"op": "gte", "value": "2026-01-01"},
    "state": {"op": "in", "value": ["opened", "merged"]}
  }
}

Token operators work only on properties with text indexes.

Columns and virtual columns

Most columns come from indexed graph tables in ClickHouse. Some columns are virtual: Orbit fetches them from another service after the graph query returns.

Request virtual columns explicitly in columns. The dynamic_columns option used by path_finding and neighbors excludes virtual columns because they can require external service calls.

The content column is for source code. For merge request diff text, use MergeRequest.diff, MergeRequestDiff.patch, or MergeRequestDiffFile.diff.

Traversal examples

Fetch one merge request with its full diff:

{
  "query_type": "traversal",
  "node": {
    "id": "mr",
    "entity": "MergeRequest",
    "node_ids": [12345],
    "columns": ["iid", "title", "state", "diff"]
  },
  "limit": 1
}

Fetch per-file diff content from diff snapshots:

{
  "query_type": "traversal",
  "nodes": [
    {
      "id": "mr",
      "entity": "MergeRequest",
      "node_ids": [12345],
      "columns": ["iid", "title", "state"]
    },
    {
      "id": "snapshot",
      "entity": "MergeRequestDiff",
      "columns": ["id", "state", "patch"]
    },
    {
      "id": "file",
      "entity": "MergeRequestDiffFile",
      "columns": ["new_path", "old_path", "too_large", "diff"]
    }
  ],
  "relationships": [
    {"type": "HAS_DIFF", "from": "mr", "to": "snapshot"},
    {"type": "HAS_FILE", "from": "snapshot", "to": "file"}
  ],
  "limit": 20
}

Fetch source file content:

{
  "query_type": "traversal",
  "node": {
    "id": "file",
    "entity": "File",
    "filters": {
      "path": {"op": "ends_with", "value": "app/models/project.rb"}
    },
    "columns": ["path", "language", "content"]
  },
  "limit": 5
}

Find merged merge requests in a project:

{
  "query_type": "traversal",
  "nodes": [
    {
      "id": "project",
      "entity": "Project",
      "filters": {"full_path": "gitlab-org/gitlab"},
      "columns": ["name", "full_path"]
    },
    {
      "id": "mr",
      "entity": "MergeRequest",
      "filters": {"state": "merged"},
      "columns": ["iid", "title", "state", "merged_at"]
    }
  ],
  "relationships": [
    {"type": "IN_PROJECT", "from": "mr", "to": "project"}
  ],
  "limit": 25
}

Find every pipeline that ran for one merge request. Always filter Pipeline.source = "merge_request_event" to match what the merge request’s Pipelines tab, the REST /merge_requests/:iid/pipelines endpoint, and the GraphQL mergeRequest.pipelines connection return:

{
  "query_type": "traversal",
  "node": {
    "id": "p",
    "entity": "Pipeline",
    "filters": {
      "merge_request_id": {"op": "eq", "value": 482908721},
      "source": {"op": "eq", "value": "merge_request_event"}
    },
    "columns": ["id", "status", "source", "sha", "ref", "created_at"]
  },
  "order_by": {"node": "p", "property": "created_at", "direction": "DESC"},
  "limit": 100
}

merge_request_id is the merge request’s internal numeric id, not the project-scoped iid. Look it up first with a MergeRequest traversal that filters by iid and project_id, then plug the id into the query above.

Both Pipeline.merge_request_id and the MergeRequest --TRIGGERED--> Pipeline edge link an MR to every CI pipeline spawned in its context, including the downstream child pipelines (source = "parent_pipeline") that the top-level MR pipelines trigger. Without the source = "merge_request_event" filter, the result over-counts by a large factor on any MR that uses parent-child pipeline fan-out, and does not match the MR UI or the REST and GraphQL definitions of “pipelines for this MR”. Apply the same filter when traversing MergeRequest --TRIGGERED--> Pipeline in a multi-node query.

MergeRequest --HAS_HEAD_PIPELINE--> Pipeline is a different edge. It points to the single most recent pipeline running against the tip of the merge request’s source branch. Use it for “what is currently running”, not for pipeline history.

Aggregation

Aggregation queries use aggregations.

Use top-level group_by to group aggregation rows. It applies to every aggregation in the query. Do not put grouping inside an individual aggregation.

Group keys support these shapes:

If you omit alias, node groups use the node ID as the output key. Property groups use the property name when it is unique in the group_by list, or <node>_<property> when needed to avoid ambiguity. Duplicate group or aggregate output names are rejected.

Property groups must reference a real ClickHouse-backed, filterable property that the caller is allowed to use. Virtual fields and unfilterable fields are rejected during validation.

Count merged merge requests per project:

{
  "query_type": "aggregation",
  "nodes": [
    {
      "id": "project",
      "entity": "Project",
      "filters": {"full_path": "gitlab-org/gitlab"}
    },
    {
      "id": "mr",
      "entity": "MergeRequest",
      "filters": {"state": "merged"}
    }
  ],
  "relationships": [
    {"type": "IN_PROJECT", "from": "mr", "to": "project"}
  ],
  "group_by": [{"kind": "node", "node": "project"}],
  "aggregations": [
    {"function": "count", "target": "mr", "alias": "merged_mrs"}
  ],
  "aggregation_sort": {"column": "merged_mrs", "direction": "DESC"},
  "limit": 10
}

Count detected vulnerabilities by severity:

{
  "query_type": "aggregation",
  "nodes": [
    {
      "id": "v",
      "entity": "Vulnerability",
      "filters": {"state": "detected"}
    }
  ],
  "group_by": [
    {"kind": "property", "node": "v", "property": "severity", "alias": "severity"}
  ],
  "aggregations": [
    {"function": "count", "target": "v", "alias": "vulnerability_count"}
  ],
  "aggregation_sort": {"column": "vulnerability_count", "direction": "DESC"},
  "limit": 10
}

Aggregation responses are table-shaped. columns describes computed aggregate values, group_columns describes grouping keys, and rows carries group values plus metric values. Node-grouped rows store the grouped entity under the group key. Property-grouped rows store the scalar bucket under the group key.

collect is listed in the input type but currently rejected by validation.

Path finding

Path finding queries use path.

Both endpoints must be bounded by node_ids, filters, or an id_range with a span of 500 or less. If either endpoint uses filters or id_range, provide rel_types.

{
  "query_type": "path_finding",
  "nodes": [
    {"id": "start", "entity": "Project", "node_ids": [278964]},
    {"id": "end", "entity": "User", "node_ids": [1]}
  ],
  "path": {
    "type": "shortest",
    "from": "start",
    "to": "end",
    "max_depth": 3,
    "rel_types": ["CREATOR", "AUTHORED", "IN_PROJECT"]
  },
  "limit": 5
}

Neighbors

Neighbor queries use one node selector and a neighbors object. The center node must be bounded by node_ids, filters, or a narrow id_range.

{
  "query_type": "neighbors",
  "node": {
    "id": "mr",
    "entity": "MergeRequest",
    "node_ids": [12345]
  },
  "neighbors": {
    "node": "mr",
    "direction": "both",
    "rel_types": ["AUTHORED", "IN_PROJECT", "HAS_DIFF"]
  },
  "options": {
    "dynamic_columns": "default"
  },
  "limit": 25
}

Set options.dynamic_columns to "*" if you need all non-restricted ClickHouse-backed columns for dynamically discovered neighbor or path nodes. Virtual columns still require an explicit request in a traversal query.

Validation limits

Orbit rejects broad or ambiguous queries before compiling SQL.

Traversal and aggregation queries must include at least one selective node: node_ids, filters, or an id_range with a span of 100,000 or less.

Single-node traversal also requires selectivity. To inspect a broad entity, add a filter, provide IDs, or use a narrow id_range.

Options

Most callers should leave performance options unset.