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 wire contract for clients sending query or relying on the Interactive header; core filter-based entity/subgraph/count paths are structurally simpler but need regression on those endpoints.

Overview
Entity query REST code is split into entity/query/ (mod.rs handlers, request.rs types) and entity_query_request.rs is deleted, along with HashQL compilation, EntityQuery / EntityQueryOptions, and the old four-variant subgraph request model.

API shape changes: QueryEntitiesRequest is now a single struct with a required filter (no query vs filter union). QueryEntitySubgraphRequest is a two-variant enum (Paths / ResolveDepths) that flattens the same fields. into_params / into_traversal_params live on those types. OpenAPI drops EntityQueryOptions, the Interactive header on entity query routes, and simplifies QueryEntitySubgraphRequest to compose QueryEntitiesRequest.

Handlers no longer prime a HashQL heap or compile queries; they deserialize and call the store directly. Benchmarks and imports are updated for the new types; unit tests cover deserialization and subgraph variant disambiguation.

^{Reviewed by Cursor Bugbot for commit d9ee377. 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 9, 2026 9:58am

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Jun 9, 2026 9:58am
petrinaut	Skipped		Jun 9, 2026 9:58am

[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-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.73%. Comparing base (3d05f60) to head (d9ee377).

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.55%   59.73%   +0.18%     
============================================================================================
  Files                                                          1348     1349       +1     
  Lines                                                        130870   130919      +49     
  Branches                                                       5884     5891       +7     
============================================================================================
+ Hits                                                          77942    78210     +268     
+ Misses                                                        52021    51795     -226     
- Partials                                                        907      914       +7     

Flag	Coverage Δ
apps.hash-ai-worker-ts	1.39% <ø> (ø)
apps.hash-api	0.00% <ø> (ø)
local.hash-backend-utils	2.81% <ø> (ø)
local.hash-graph-sdk	9.63% <ø> (ø)
local.hash-isomorphic-utils	0.00% <ø> (ø)
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 6 out of 6 changed files in this pull request and generated 1 comment.

[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");
        }
    }
}