Proposal: remove public search and make traversal cover node discovery. Traversal becomes the graph selection primitive. It has two forms: zero-hop traversal for scoped node discovery, and relationship traversal for edge-backed graph queries. Standalone search should leave the public schema, response schema, compiler, docs, fixtures, and examples. The security rule stays explicit: zero-hop traversal is valid only for traversal-path-scoped entities unless the request is admin-only or internal. Unscoped entities such as User must be reached through an authorized scoped relationship. ## Proposal - Delete search from the query schema, response schema, docs, fixtures, and agent-facing examples. - Remove the Search query type from the compiler enum and lowering dispatch instead of keeping it as a compatibility path. - Add zero-hop traversal: one node, zero relationships, table-centric lowering. - Keep relationship traversal edge-centric. - Preserve search-equivalent behavior for zero-hop traversal: selected columns, default columns, wildcard columns, filters, node IDs, ID ranges, ordering, limits, cursor pagination, redaction, dedup, and virtual column hydration. - Preserve internal Hydration. It is not public Search. <details><summary>Examples</summary> Allowed scoped zero-hop traversal: ```json { "query_type": "traversal", "nodes": [ { "id": "project", "entity": "Project", "columns": ["id", "name", "path_with_namespace"], "filters": { "name": { "contains": "gitaly" } } } ], "relationships": [], "order_by": { "node": "project", "property": "name", "direction": "asc" }, "limit": 25 } ``` Allowed scoped user traversal: ```json { "query_type": "traversal", "nodes": [ { "id": "user", "entity": "User", "columns": ["id", "username", "name"] }, { "id": "project", "entity": "Project", "node_ids": ["gid://gitlab/Project/1"] } ], "relationships": [ { "from": "user", "to": "project", "type": "MEMBER_OF" } ], "limit": 25 } ``` Rejected non-admin standalone user traversal: ```json { "query_type": "traversal", "nodes": [ { "id": "user", "entity": "User", "filters": { "username": { "contains": "admin" } } } ], "relationships": [], "limit": 25 } ``` </details> <details><summary>Implementation sketch</summary> Use the current search lowerer as the base for zero-hop traversal, but keep the compiled query type as traversal: ```rust match input.query_type { QueryType::Traversal if input.relationships.is_empty() => lower_zero_hop_traversal(input), QueryType::Traversal => lower_traversal_edge_only(input), QueryType::Hydration => lower_hydration(input), // Search is gone from the public enum. } ``` Validation should accept exactly one no-edge traversal and reject ambiguous no-edge shapes: ```rust if input.query_type == QueryType::Traversal && input.relationships.is_empty() { ensure!(input.nodes.len() == 1, "zero-hop traversal requires exactly one node"); return Ok(()); } ``` Enforcement should only treat traversal as edge-centric when relationships exist: ```rust let edge_centric = matches!(input.query_type, QueryType::Neighbors) || (input.query_type == QueryType::Traversal && !input.relationships.is_empty()); ``` Hydration should treat zero-hop traversal like the old search path if the lowerer selects static node columns directly: ```rust let zero_hop = input.query_type == QueryType::Traversal && input.relationships.is_empty(); if zero_hop || input.query_type == QueryType::Aggregation { retain_virtual_column_templates_only(&mut templates); } ``` </details> <details><summary>Research notes</summary> Input and schema: - Search is a QueryType variant in [input.rs](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/crates/query-engine/compiler/src/input.rs#L220). - The public query schema still exposes search and requires singular node for search and neighbors in [graph_query.schema.json](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/config/schemas/graph_query.schema.json#L92). - Traversal currently requires at least two nodes and one relationship in [graph_query.schema.json](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/config/schemas/graph_query.schema.json#L141). Loosen this to one node and zero relationships, then keep topology checks in Rust. - Server config validates query override keys against QueryType::VARIANTS in [main.rs](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/crates/gkg-server/src/main.rs#L41). Removing Search means any deployed query.search override becomes a boot failure unless migrated. Compiler passes: - Validation already has the relationship count check in [validate.rs](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/crates/query-engine/compiler/src/passes/validate.rs#L189), but unreferenced-node validation rejects a traversal node with no relationship in [validate.rs](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/crates/query-engine/compiler/src/passes/validate.rs#L602). - Search currently lowers as a direct node-table scan in [lower.rs](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/crates/query-engine/compiler/src/passes/lower.rs#L73). Relationship traversal unwraps the first relationship in [lower.rs](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/crates/query-engine/compiler/src/passes/lower.rs#L154), so zero-hop traversal needs its own lowering branch. - Node filter CTEs support node IDs and filters, but not ID ranges, through [build_node_where](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/crates/query-engine/compiler/src/passes/lower.rs#L431). Zero-hop parity needs ID range support. - Enforcement treats all traversal as edge-centric in [enforce.rs](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/crates/query-engine/compiler/src/passes/enforce.rs#L207). Zero-hop traversal should use the table-centric path. - Hydration gives Search and Aggregation virtual-column-only hydration, but Traversal gets full static hydration in [hydrate.rs](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/crates/query-engine/compiler/src/passes/hydrate.rs#L85). Zero-hop traversal should avoid rehydrating static columns already selected by the base scan. - Dedup already handles Traversal in [deduplicate.rs](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/crates/query-engine/compiler/src/passes/deduplicate.rs). Remove the Search arm and keep zero-hop traversal covered by Traversal. Security, result shape, and docs: - The security pass is AST/table based and should keep working for scoped zero-hop table scans in [security.rs](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/crates/query-engine/compiler/src/passes/security.rs#L35). - User is intentionally skipped for traversal-path filters in [schema.yaml](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/config/ontology/schema.yaml#L87), so non-admin standalone User must be rejected before SQL enforcement. - GraphFormatter has a public Search branch and a traversal branch that extracts nodes then edges in [graph.rs](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/crates/query-engine/formatters/src/graph.rs#L155). Remove the Search branch and rename extract_search_nodes to a neutral helper. - The response schema still lists search and says all five query types in [query_response.json](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/crates/gkg-server/schemas/query_response.json#L5). Update it and bump RAW_OUTPUT_FORMAT_VERSION in the same MR. - Public docs and fixtures still contain search examples, including [query_language.md](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/docs/source/queries/query_language.md#L54), [querying/README.md](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/dbfb6babd7d867a4c941213d1c752a13e7727472/docs/design-documents/querying/README.md#L21), and the query fixtures under fixtures/queries. </details> <details><summary>Acceptance criteria</summary> - Public search queries fail schema validation. - The compiler enum and public schema no longer expose Search. Internal Hydration still compiles and runs. - Zero-hop traversal compiles to a node-table scan, not an edge scan. - Relationship traversal keeps the current edge-centric lowering and enforcement path. - Zero-hop traversal supports filters, columns, wildcard columns, node IDs, ID ranges, order_by, limit, cursor pagination, redaction, dedup, and virtual columns. - Non-admin standalone User/global discovery is rejected unless the entity is reached through an authorized scoped relationship. - Graph responses for zero-hop traversal include nodes, no edges, and query_type set to traversal. - Query docs, generated schemas, fixtures, examples, and response format version are updated. </details> <details><summary>Risks</summary> - Search removal can break deployed query.search config overrides because server startup validates query override keys. - Zero-hop traversal and relationship traversal need different enforcement and hydration behavior. Treating all traversal as edge-centric will break one-node queries. - ID range parity is easy to miss because relationship traversal node-filter CTEs do not currently include it. - Removing public Search must not remove internal Hydration, which still compiles table-scan queries for hydration. - Response defaults may shift for clients that treated search as table-like and traversal as graph-like. </details> <!-- AI-Sessions dir: ~/.codex/sessions/2026/04/25/ rollout-2026-04-25T13-08-56-019dc59d-a65c-7241-8568-edec56c80b6c.jsonl (2026-04-25) rollout-2026-04-25T13-19-47-019dc5a7-94c8-7b72-b907-96972db7820b.jsonl (2026-04-25) rollout-2026-04-25T13-19-53-019dc5a7-ab45-7eb0-8027-845ee49cd03d.jsonl (2026-04-25) rollout-2026-04-25T13-20-01-019dc5a7-ca3b-7910-86ad-6be21578b7d7.jsonl (2026-04-25) rollout-2026-04-25T13-36-00-019dc5b6-6c86-7d02-8d05-393cd73aca32.jsonl (2026-04-25) rollout-2026-04-25T13-36-00-019dc5b6-6ddd-70f2-8c4e-44cc28b354d5.jsonl (2026-04-25) rollout-2026-04-25T13-36-00-019dc5b6-6f4b-7162-ada6-f09d83efd41d.jsonl (2026-04-25) -->