BE-590: hgraph: Refactor entity query handlers into entity/query submodule

[indietyp]

🌟 What is the purpose of this PR?

The entity query request types and their associated HTTP handler functions have been refactored out of a single flat module into a dedicated entity/query submodule hierarchy. As part of this, the old entity_query_request.rs file — which contained a large amount of dead code related to a planned HashQL integration, proxy deserialization structs, and a four-variant subgraph enum — has been removed entirely.

The new QueryEntitiesRequest and QueryEntitySubgraphRequest types are simpler: QueryEntitiesRequest is now a plain struct with a filter field directly (no EntityQuery enum wrapping a filter or raw HashQL value), and QueryEntitySubgraphRequest is a two-variant untagged enum (Paths / ResolveDepths) rather than four variants. The into_params and into_traversal_params methods are now on the request types themselves rather than on a separate EntityQueryOptions struct, removing an intermediate layer.

The Interactive header parameter has also been removed from the query_entities and query_entity_subgraph OpenAPI path definitions, as it was only relevant to the HashQL compilation path that no longer exists in these handlers.

🔗 Related links

• https://linear.app/hash/issue/BE-537/hashql-remove-old-backend-wire-up-hashql-in-the-api

🔍 What does this change?

• Converts entity.rs into entity/mod.rs and extracts query handlers into entity/query/mod.rs and request types into entity/query/request.rs.
• Removes entity_query_request.rs and all dead code it contained: EntityQuery, EntityQueryOptions, FlatQueryEntitiesRequestData, CompilationOptions, HashQL diagnostic rendering, and the four-variant QueryEntitySubgraphRequest.
• Replaces the EntityQuery::Filter / EntityQuery::Query split with a direct filter: Filter<'q, Entity> field on QueryEntitiesRequest.
• Moves into_params and into_traversal_params onto QueryEntitiesRequest and QueryEntitySubgraphRequest respectively, eliminating EntityQueryOptions as a separate type.
• Removes the Interactive header from query_entities and query_entity_subgraph handler signatures and OpenAPI docs.
• Updates benchmark code in tests/graph/benches to use the simplified request types directly, removing the into_parts / from_parts round-trips that previously extracted an EntityQuery and EntityQueryOptions.
• Adds unit tests in entity/query/request.rs covering deserialization of both request types, including required-field validation and correct disambiguation of the Paths vs ResolveDepths subgraph variants.

🛡 What tests cover this?

• New unit tests in libs/@local/graph/api/src/rest/entity/query/request.rs covering minimal and fully-populated QueryEntitiesRequest deserialization, rejection of missing required fields, and correct parsing of both QueryEntitySubgraphRequest variants including edge cases around ontology vs entity traversal edges.

❓ How to test this?

1. Checkout the branch.
2. Run cargo test in libs/@local/graph/api.
3. Exercise the /entities/query, /entities/query/subgraph, and /entities/query/count endpoints and confirm they behave as before.

[cursor]

PR Summary

Medium Risk
Breaking HTTP/OpenAPI contract for clients that still send a query body or Interactive header on entity query endpoints; filter-based callers should behave the same after the structural refactor.

Overview
Entity query HTTP handling moves into entity/query, and the wire format is simplified to filter-only entity queries.

QueryEntitiesRequest is now a single object with a required filter (plus the former options fields inline). The EntityQuery / EntityQueryOptions split, proxy deserialization, HashQL compilation path, and entity_query_request.rs are removed. Handlers no longer read the Interactive header or prime a HashQL heap; they deserialize the request and call into_params / into_traversal_params on the request types directly.

QueryEntitySubgraphRequest collapses from four filter/query × paths/resolve-depth variants to two (Paths vs ResolveDepths) that flatten the shared entity query fields. OpenAPI drops EntityQueryOptions, documents QueryEntitiesRequest as a plain schema, and subgraph requests allOf that base type with traversal fields.

Benchmarks and imports are updated for the new types; entity/query/request.rs adds deserialization tests (required fields, variant disambiguation, unknown fields).

^{Reviewed by Cursor Bugbot for commit 36c00cc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	Jun 12, 2026 12:42pm
petrinaut	Ready	Preview	Jun 12, 2026 12:42pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Jun 12, 2026 12:42pm

[indietyp]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• BE-481: HashQL: Reify null and empty tuple as unit constants #8853
• BE-537: hgraph: REST /hashql endpoint with E2E tests #8827
• BE-592: HashQL: Remove old eval graph path and core value types #8841
• BE-590: hgraph: Refactor entity query handlers into entity/query submodule #8840 👈 (View in Graphite)
• BE-587, BE-588: HashQL: Introduce CodeGenerationContext/CodeExecutionContext split and eval-stage Interner #8839
• BE-581, BE-589: HashQL: Introduce pass::lower/pass::place pipeline facades and fix cached constructor closure bug #8838
• BE-585, BE-591: HashQL: Add MIR interpreter test suite and refactor diagnostic categories #8837
• BE-583, BE-584, BE-586: HashQL: Add HeapPool, improve spans, and propagate Critical severity through diagnostics #8836
• BE-582: HashQL: Change opaque types from invariant to covariant #8835
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 044a4ff. Configure here.}

[codecov]

Codecov Report

❌ Patch coverage is 43.86252% with 343 lines in your changes missing coverage. Please review.
✅ Project coverage is 59.68%. Comparing base (0e47501) to head (36c00cc).

Files with missing lines	Patch %	Lines
.../@local/graph/api/src/rest/entity/query/request.rs	54.03%	221 Missing and 7 partials ⚠️
libs/@local/graph/api/src/rest/entity/query/mod.rs	0.00%	115 Missing ⚠️

Additional details and impacted files

@@                                     Coverage Diff                                      @@
##           bm/be-587-hashql-eval-interner-and-context-restructuring    #8840      +/-   ##
============================================================================================
+ Coverage                                                     59.50%   59.68%   +0.18%     
============================================================================================
  Files                                                          1348     1349       +1     
  Lines                                                        130797   130846      +49     
  Branches                                                       5879     5886       +7     
============================================================================================
+ Hits                                                          77825    78093     +268     
+ Misses                                                        52066    51840     -226     
- Partials                                                        906      913       +7     

Flag	Coverage Δ
rust.hash-graph-api	8.50% <43.86%> (+5.93%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Refactors the entity query REST API by moving query request types and handlers into a dedicated rest/entity/query submodule, while removing the legacy entity_query_request.rs module (including dead/unused HashQL-related code paths). This simplifies the request shapes (direct filter struct field; two-variant subgraph request) and updates benchmarks accordingly.

Changes:

• Extracts entity query handlers to libs/@local/graph/api/src/rest/entity/query/mod.rs and request types (plus deserialization tests) to .../entity/query/request.rs.
• Removes libs/@local/graph/api/src/rest/entity_query_request.rs and the Interactive header from entity query OpenAPI definitions/handlers.
• Updates manual benchmark scaffolding to use the new request types and APIs directly.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/graph/benches/manual_queries/entity_queries/mod.rs	Updates benchmarks to use the refactored request types and the new into_*params APIs.
libs/@local/graph/api/src/rest/mod.rs	Drops the old entity_query_request module inclusion.
libs/@local/graph/api/src/rest/entity/query/request.rs	Introduces simplified request types and adds unit tests for deserialization/variant disambiguation.
libs/@local/graph/api/src/rest/entity/query/mod.rs	Adds extracted handlers and updated OpenAPI path definitions without the Interactive header.
libs/@local/graph/api/src/rest/entity/mod.rs	Wires the new submodule into routing and OpenAPI, removing the inlined legacy handlers/types.
libs/@local/graph/api/src/rest/entity_query_request.rs	Removes the legacy request module (dead HashQL/proxy-related code).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

tests/graph/benches/manual_queries/entity_queries/mod.rs:357

• into_traversal_params_unchecked returns QueryEntitySubgraphParams (not a Result), so the .expect(...) won’t compile. Use the checked into_traversal_params here if you want to preserve limit + traversal validation.

                .expect("failed to read entity subgraph from store");
        }
    }
}

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.