Update the Orbit API query examples to the current query DSL

José M. Requena Plensrequested to merge
gitlab-community/gitlab-org/gitlab:jmrp-orbit-api-query-examples into master

What does this MR do?

Four of the five worked query examples on the Orbit API page are rejected by GitLab.com with 400 compile_error, and the fifth is accepted but documents a response shape the API does not return. The examples were written in March for an earlier version of the query DSL, and GitLab.com now serves version 12 (graph_query/v12, 12.1.9). !254743 (merged) kept them on purpose, as the only worked examples of the Orbit query DSL in the repository, so I think they are worth keeping correct.

This MR rewrites each example in the version 12 shape and replaces every example response with the shape the API returns in the default raw format. I sent each new request body, verbatim, to GitLab.com: all five compile and run with 200 OK.

What each current example gets wrong, with GitLab.com's answer

Every request below was sent verbatim to POST https://gitlab.com/api/v4/orbit/query on 2026-09-28 (Orbit 0.131.0, DSL 12.1.9).

Example Problem GitLab.com answer
Retrieve a user by username search is no longer a query type (gitlab-org/orbit/knowledge-graph#522 (closed)), and a single node became the nodes array 400: schema violation: "nodes" is a required property at ; "search" is not an allowed value. Valid values: traversal, aggregation, path_finding, neighbors at /query_type; Additional properties are not allowed ('node' was unexpected) at
Find merged merge requests in a project The request is valid, but result is an object with nodes, edges and pagination, not a list of flattened p_name and mr_title rows 200
Count merge requests per project Aggregations are keyed by their function ({"count": "mr", "as": "mr_count"}) with a top-level group_by, and at least one node must be bounded 400: schema violation: {"function":"count","target":"mr","group_by":"p","alias":"mr_count"} has more than 2 properties at /aggregations/0; Additional properties are not allowed ('function', 'target', 'group_by', 'alias' were unexpected) at /aggregations/0; .... Translated to version 12 but still unbounded: 400: schema violation: traversal and aggregation queries require node_ids or filters on at least one node to avoid full edge table scans
Find outgoing neighbors of a user node and neighbors.node are gone: the center is the single entry of nodes 400: schema violation: "nodes" is a required property at ; Additional properties are not allowed ('node' was unexpected) at /neighbors; ...
Find the shortest path between two projects rel_types is required on every path query (gitlab-org/orbit/knowledge-graph!1621 (merged)). With it, the query still returns nothing: path finding follows each relationship type only in its defined direction, and the only relationship that starts at a project is CONTAINS to Branch, so no forward path joins two projects. The documented response walks MEMBER_OF backwards. 400: schema violation: path_finding requires rel_types to bound fan-out; without it the frontier expands over every edge type

The Orbit project's own query corpus expects the two-project path to be empty: fixtures/queries/corpus/sdlc.yaml, case q25.

How I checked the new examples
  • Each new request body on the page was sent verbatim to GitLab.com, and each answered 200 OK.
  • The response shapes come from real responses to the same queries against a private project of mine. The values on the page stay illustrative, and I made them consistent across examples (project 8 was "Diaspora Client" in one example and project 5 in another).
  • Two details are as GitLab.com returns them: node IDs are strings, and a merge request's iid is a number in a traversal response and a string in neighbors and path_finding responses.
  • direction defaults to outgoing for neighbors: a query without it returns only the relationships that start at the center node, which is also the default in the compiler (Direction in input.rs). The DSL schema describes the default as both; I reported that in gitlab-org/orbit/knowledge-graph#1330 (closed), with a fix in gitlab-org/orbit/knowledge-graph!2651 (merged).
  • The page links to the Orbit query language guide instead of GET /orbit/schema/dsl and GET /orbit/schema/format, because both routes are hidden in ee/lib/api/orbit/data.rb.
  • markdownlint-cli2 with this repository's configuration reports no issues on the changed page, and Vale with this repository's .vale.ini reports no errors and the same warnings as on master.
Where this comes from

I maintain gitlab-mcp-server, an MCP server that exposes the GitLab API, the Orbit routes included, to AI assistants. While moving its Orbit tools to version 12 of the query DSL (issue 1031) I checked every example I could find against GitLab.com. The project keeps a record of everything it finds in its dependencies and in sibling projects in upstream-bugs.md.

Related issues

Related to #604816 (closed)

Related to gitlab-org/orbit/knowledge-graph#1329 (closed)

Related to gitlab-org/orbit/knowledge-graph#1330 (closed)

Author's checklist

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.

Merge request reports