Define multiversion-safe Elasticsearch GraphQL development process
# Problem statement
Elasticsearch-backed GraphQL fields and arguments typically require significant backend work before they can function correctly. Until that work is finished, frontend development is often blocked.
At the same time, concerns about [multi-version compatibility](https://docs.gitlab.com/development/graphql_guide/reviewing/#multiversion-compatibility) make teams hesitant to expose GraphQL schema elements early, which further delays frontend work.
## Goals
This issue aims to address two explicit requirements when introducing Elasticsearch-backed GraphQL fields or arguments:
1. **Multi-version compatibility**
- New frontend code does not break when talking to older backend versions
- Rolling deployments remain safe
2. **Unblocked frontend development**
- Frontend work can proceed before Elasticsearch mappings, migrations, and query logic are complete
## Key observation
From a multi-version perspective, exposing the GraphQL schema early (with optional / nullable fields or arguments and no-op behaviour) is sufficient to prevent frontend breakage.
However, for frontend development, non-null and predictable responses are often needed to build and validate UI flows (filters, empty states, counts, etc.).
---
Define a standard, phased approach for Elasticsearch-backed GraphQL fields and arguments:
## Phase 1 – Schema-first (multi-version safe)
- Expose the GraphQL field or argument early
- Mark it optional / nullable
- Resolver behaviour is a no-op or returns `null`
- Safe for all frontend and backend versions
```mermaid
flowchart TD
A["<b>Functional requirements</b><br/>design issue"]
--> B["<b>Schema freeze</b>"]
%% Backend preparation block
subgraph S["<b>Backend preparation</b>"]
direction TB
C["<b>Backend schema exposure</b><br/>Multi-version safe"]
D["<b>Backend PG scaffolding</b>"]
C --> D
end
B --> C
%% Parallel development
D --> E["<b>Backend development</b><br/>ES reuse scaffolding query"]
C --> F["<b>Frontend development</b>"]
%% Smaller decision node
F --> DEC{"<b>Behaviour dependent?</b>"}
%% Yes → wait node for backend scaffolding → frontend behaviour validation
DEC -- "Yes" --> W["<b>Wait for backend scaffolding</b>"]
W --> FB["<b>Frontend behaviour validation</b>"]
FB --> G
%% No → go directly to full stack validation
DEC -- "No" --> FS["<b>Full stack validation</b>"]
%% Design issue closed (only on backend path)
E --> DI1["<b>Design issue closed</b>"]
%% ES Migration (red)
DI1 --> M["<b>ES migration</b>"]
%% Both paths converge to cleanup
M --> G["<b>Scaffolding disabled</b><br/>Switch from PG to ES<br/>Change is transparent"]
%% Full stack validation (final step)
G --> FS
%% Styles
class S leftAlign;
class C,D leftAlign;
classDef leftAlign text-align:left;
%% Green styling for Design issue closed
style DI1 fill:#9BE39B,stroke:#2E7D32,stroke-width:2px;
%% Red styling for ES migration
style M fill:#F28B82,stroke:#B71C1C,stroke-width:2px;
%% Decision styling
style DEC fill:#FFF3CD,stroke:#FFB300,stroke-width:2px;
%% Wait + PG scaffolding styling (same color)
style W fill:#E3F2FD,stroke:#1565C0,stroke-width:2px;
style D fill:#E3F2FD,stroke:#1565C0,stroke-width:2px;
%% Frontend behaviour validation styling (optional, subtle emphasis)
style FB fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px;
````
## Phase 2 – Frontend enablement (development only)
- Allow feature-flagged mock responses
- Clearly temporary and removed before or at GA
Truth table:
| API element | Target system | Strategy | When backend stubbing is enough | When backend scaffolding is needed | Pagination / stability |
|------------|---------------|----------|--------------------------|----------------------------|------------------------|
| **Filter arguments** | ES | Stub or scaffold | - Testing wiring and schema usage<br><br>- UX flows, empty states<br><br>- Pagination UI | - Validating real filtering semantics<br><br>- Permissions, feature flags, and domain correctness | **Stub →** ✅ Fully stable (fake data)<br><br>**Scaffold →** ⚠️ Over-fetching applied to mitigate |
| **Count / aggregation queries** | ES | Stub | - UI summaries, charts, badges, empty states<br><br>- Exploratory UI and layout validation | - When counts drive business logic, permissions, or workflow decisions | **Stub →** ✅ Stable (numbers are placeholders)<br><br>**Scaffold →** ⚠️ Stable but complex, still approximate vs ES |
| **Fields not implemented anywhere yet** | ES | Stub | - Always for UI and schema validation<br><br>- Type- and shape-correct placeholders unblock frontend | ❌ Not applicable until domain model exists | **Stub →** ✅ Stable (UI-only contract, deterministic values) |
## Phase 3 – Elasticsearch implementation
- Add mappings, migrations, and query logic
- Enable behaviour gradually behind feature flags
- Remove mock responses
---
# Expected outcome
- Clear guidance for contributors working on Elasticsearch-backed GraphQL fields and arguments
- Reduced frontend blocking on Elasticsearch work
- Improved development speed
- Safer multi-version deployments
epic