Serve the Orbit schema through GraphQL

Michael Angelo Riverarequested to merge
feature/orbit-schema-graphql into master

What does this MR do and why?

The Orbit dashboard now reads the graph schema from GraphQL (Query.orbit.schema) instead of GET /api/v4/orbit/schema. This answers the REST or GraphQL question from !227091 (comment 3158662552), and lets us remove the REST schema endpoints before GA.

query {
  orbit {
    schema {
      nodes { nodes { name domain { name } labelProperty properties { nodes { name dataType } } } }
      edges { nodes { name endpoints { nodes { source { name } target { name } } } } }
    }
  }
}

Backend

  • Query.orbit.schema describes node kinds, edge kinds, and properties as data, in connections. A new or custom kind needs no GraphQL type change. Design: https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/snippets/6069117.
  • Same access check and token scopes as REST: Orbit enabled, the Orbit license check, read_orbit, and api, read_api, or ai_workflows.
  • One gRPC call per request: a second schema selection in the same query returns an error (FieldCallCount).
  • StatusResolvable#call_orbit reuses the existing gRPC error handling.
  • The GraphQL docs generator listed any type that ends in Edge as a pagination edge. It now requires a cursor field, so OrbitSchemaEdge is documented as an object.

Frontend

  • fetchOrbitSchema(apollo) runs getOrbitSchema and maps the result to the shape the dashboard components already read. Only the three callers change.
  • Backend and frontend ship together. The query adds no new arguments, and @gl_introduced makes an older backend return a null schema. The browser tests cover that case.
  • A missing schema shows the Schema page error alert, as a REST error did. Try again skips the Apollo cache.

Evidence. Measured on gitlab-work-vm-1. The branch is on master c175549d0c2b, with Orbit main fa8b3c6d9 and graph schema v109.

Check REST GraphQL
Node kinds, edge kinds, properties, endpoints 33, 60, 422, 122 33, 60, 422, 122 (0 differences)
Schema requests in one tab session (Overview, Schema, Query, Schema) 4 1
Response size, raw and gzip -6 62,170 B and 8,976 B 95,353 B and 8,568 B
GitlabSchema.execute in dev mode, median of 10 gRPC call alone: 22.5 ms 93.4 ms in total, 74.7 ms without gRPC

Not in this MR

  • REST schema, schema/dsl, and schema/format stay until this MR deploys. A follow-up removes them.
  • No version field yet. The proto schema_version is the ontology format (0.1), not the graph version, so it cannot be a cache key.
  • Lists use the default page size of 100. The largest list today is 60 edge kinds.

References

Screenshots or screen recordings

Page Before (REST) After (GraphQL)
Overview before_light_overview final_light_overview
Schema, MergeRequest before_light_schema_mr final_light_schema_mr
Query autocomplete before_light_query_autocomplete final_light_query_autocomplete
State (after) Screenshot
Dark mode after_dark_schema_mr
No schema (older backend or no access) final_null_schema
Try again after no schema final_retry_after_null
GraphQL error final_error_schema

Browser test matrix (headless Chromium on gitlab-work-vm-1, final head):

Case Result
Overview, Schema, Query load real data Pass. 1 getOrbitSchema, 0 REST requests. Page values identical to master.
MergeRequest card Pass. 44 properties, state enum values, 15 connected entities.
Query autocomplete Pass. MATCH (n:Merge suggests the same 3 kinds as master.
Tab session cache Pass. 1 request for Overview, Schema, Query, Schema.
No schema Pass. Error alert, and Try again sends a new request.
GraphQL error Pass. Error alert, and Try again loads the schema.
Dark mode Pass. Same values.
Console Pass. No exceptions.

How to set up and validate locally

  1. Run a GDK with the Orbit stack.
  2. Visit /dashboard/orbit, open the Schema tab, and select MergeRequest.
  3. In the browser network panel, check for one getOrbitSchema GraphQL request and no /api/v4/orbit/schema request.
  4. In /-/graphql-explorer, run the query above.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Merge request reports