feat(query): wire GQL into remote queries

What does this MR do and why?

Remote callers still need JSON even though the compiler supports graph query text. This connects the read-only openCypher subset to remote queries while retaining JSON defaults and named queries.

Relates to https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/issues/1258.

Testing

Local tests pass, including CLI HTTP calls and the ClickHouse path checks. Clippy, formatting, and docs lint pass. The full security suite still needs a run.

Performance Analysis

SQL planning is unchanged. This MR has no benchmark.

  • This merge request does not introduce any performance regression. If a performance regression is expected, explain why.
Agent context
  • Adds a separate QueryLanguage enum (JSON=0, GQL=1) and keeps QueryType as JSON=0 and NAMED=1. Rails sets the language from the orbit_gql_queries flag, so REST and MCP clients have no language selector. The CLI has no language flag: orbit query 'CALL db.schema()' sends inline query text, and an existing file, -, or no argument reads a request envelope.
  • Keeps the full clickhouse_json_dsl and clickhouse_gql presets. Path resolution and compilation receive the same frontend; authorization and response formats remain shared.
  • Omits query source excerpts from GQL syntax errors. Tests check literal suppression, scope boundaries, cursor binding, selector rejection, and query/response bytes.
  • Earlier local checks: 373 compiler, 269 server, 15 shared, 180 CLI unit, 6 CLI HTTP, and 183 local integration tests passed. The ClickHouse path-resolution test, clippy, formatting, and changed-doc markdownlint also passed.

Rollout

JSON and GQL are both supported, with the frontend selected per request. JSON remains the default. There is no separate GQL feature flag or server mode.

  1. Publish the Go protobuf module containing the GQL enum after this MR merges, or land the protobuf update separately first.
  2. Pin that module in the companion Rails/Workhorse branch and deploy its forwarding support.
  3. Deploy Orbit's GQL support and dual-language command catalogs after Rails and Workhorse can forward GQL. Verify REST, MCP, and agent-command queries.

Do not deploy the new catalogs before the forwarding support. If protobuf publication requires deploying Orbit first, split out the protobuf update.

JSON deprecation will target a separately announced Orbit release after client migration. No removal version is set here. Named queries render in the request's language.

The flag-rollout issue is superseded by this plan. Feature tracking remains in the openCypher issue.

Open gates

Current check after removing the flag: 243 Orbit server unit tests pass. Rails syntax checks pass; request specs remain blocked by unavailable local PostgreSQL.

The published Workhorse protobuf dependency (v0.100.0) does not yet contain the new enum, so the Workhorse tests cannot compile until step 1. Rails specs are written but not run locally (no PostgreSQL). An earlier full security run passed 58/59 scenarios; the JSON-only aggregation_user_reachable_via_path_compiles case failed with UNKNOWN_IDENTIFIER p.id and needs a rerun. Agent evals have not run.

Edited by Aaron Algutifan

Merge request reports

Loading
Loading