BE-590: hgraph: Refactor entity query handlers into `entity/query` submodule by indietyp · Pull Request #8840 · hashintel/hash

indietyp · 2026-06-08T11:41:49Z

🌟 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?

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

chore: add new dependency chore: format feat: error module feat: introduce hashql_eval interner chore: checkpoint feat: checkpoint feat: checkpoint chore: remove old value module feat: checkpoint feat: checkpoint feat: checkpoint feat: checkpoint feat: checkpoint chore: checkpoint feat: move entity query into its own modul fix: query request feat: checkpoint (it compiles!) feat: checkpoint feat: checkpoint feat: checkpoint fix: issue around cached thunking feat: covariance for opaque inners fix: cfgattr serde chore: remove graph module fix: merge fuckup

cursor · 2026-06-08T11:41:57Z

PR Summary

High Risk
Removes public REST endpoints and changes request/OpenAPI shapes, so existing clients using query, search, summarize, or the Interactive header must migrate.

Overview
Entity query HTTP handlers and request types move into entity/query, replacing the monolithic entity_query_request.rs layer with QueryEntitiesRequest as a single struct and a two-variant QueryEntitySubgraphRequest.

Breaking API / contract changes: entity queries now require a filter body field only (no query / HashQL wire-up, no EntityQueryOptions split). OpenAPI drops the Interactive header on query routes. POST /entities/search and POST /entities/query/summarize are removed from the entity router; POST /entities/query/count is added. QueryEntitySubgraphResponse can return optional count and facet maps when includeCount / related include* flags are set on the request.

Benchmarks and deserialization tests are updated for the flattened request types and subgraph variant disambiguation.

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

vercel · 2026-06-08T11:42:00Z

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

Project	Deployment	Actions	Updated (UTC)
hash	Error		Jun 30, 2026 12:50pm
petrinaut	Ready	Preview	Jun 30, 2026 12:50pm

1 Skipped Deployment

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

indietyp · 2026-06-08T11:42:01Z

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-614: HashQL: Generate synthetic closure bodies for intrinsics used as first-class values #8895
BE-615: HashQL: Introduce the concept of synthetic closures in the MIR #8894
BE-607: HashQL: Refactor ModuleRegistry into builder/immutable split with allocator-generic stdlib construction #8887
BE-538: HashQL: Permission system integration #8882
BE-71: HashQL: Consolidate AST special-form expansion stages into one #8870
BE-481: HashQL: Reify null and empty tuple as unit constants #8853
BE-537, 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.

codecov · 2026-06-08T11:45:52Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 59.58%. Comparing base (a5659a4) to head (57dccbf).

Additional details and impacted files

@@                                    Coverage Diff                                    @@
##           bm/be-587-hashql-eval-interner-and-context-restructuring    #8840   +/-   ##
=========================================================================================
  Coverage                                                     59.58%   59.58%           
=========================================================================================
  Files                                                          1349     1349           
  Lines                                                        131875   131875           
  Branches                                                       5946     5946           
=========================================================================================
  Hits                                                          78574    78574           
  Misses                                                        52393    52393           
  Partials                                                        908      908

Flag	Coverage Δ
apps.hash-ai-worker-ts	`1.39% <ø> (ø)`
local.hash-backend-utils	`2.82% <ø> (ø)`
local.hash-graph-sdk	`9.63% <ø> (ø)`
local.hash-isomorphic-utils	`0.00% <ø> (ø)`

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 no new comments.

Copilot

Pull request overview

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

+    params(
+        ("X-Authenticated-User-Actor-Id" = ActorEntityUuid, Header, description = "The ID of the actor which is used to authorize the request"),
+        ("after" = Option<String>, Query, description = "The cursor to start reading from"),
+        ("limit" = Option<usize>, Query, description = "The maximum number of entities to read"),
+    ),


+    params(
+        ("X-Authenticated-User-Actor-Id" = ActorEntityUuid, Header, description = "The ID of the actor which is used to authorize the request"),
+        ("after" = Option<String>, Query, description = "The cursor to start reading from"),
+        ("limit" = Option<usize>, Query, description = "The maximum number of entities to read"),
+    ),


Copilot

Pull request overview

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

Comments suppressed due to low confidence (1)

libs/@local/graph/api/src/rest/entity/mod.rs:4

This refactor moves QueryEntitiesRequest / QueryEntitySubgraphRequest under entity::query, but the previous public re-exports from hash_graph_api::rest::entity::* are gone. Since hash-graph-api is a published crate, this is a breaking Rust API change for downstream users even though HTTP behavior is unchanged.

Consider re-exporting the request/error types from entity to preserve the old import path (or add a deprecation cycle if you want to force the new path).

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 7cc1ed6. Configure here.}

-        EntityValidationType, HasPermissionForEntitiesParams, LinkDataStateError,
-        LinkDataValidationReport, LinkError, LinkTargetError, LinkValidationReport,
-        LinkedEntityError, MetadataValidationReport, PatchEntityParams,
+        ClosedMultiEntityTypeMap, CountEntitiesParams, CreateEntityParams, DiffEntityParams,


+use error_stack::{Report, ResultExt as _};
+use hash_graph_store::{
+    entity::{
+        ClosedMultiEntityTypeMap, CountEntitiesParams, EntityPermissions, EntityQueryCursor,


+            Json(QueryEntitySubgraphResponse {
+                subgraph: response.subgraph.into(),
+                cursor: response.cursor.map(EntityQueryCursor::into_owned),
+                count: response.count,


+                count: response.count,
+                closed_multi_entity_types: response.closed_multi_entity_types,
+                definitions: response.definitions,
+                web_ids: response.web_ids,


+                closed_multi_entity_types: response.closed_multi_entity_types,
+                definitions: response.definitions,
+                web_ids: response.web_ids,
+                created_by_ids: response.created_by_ids,


+            include_count: self.include_count,
+            include_entity_types: self.include_entity_types,
+            temporal_axes: self.temporal_axes,
+            include_web_ids: self.include_web_ids,


+            include_entity_types: self.include_entity_types,
+            temporal_axes: self.temporal_axes,
+            include_web_ids: self.include_web_ids,
+            include_created_by_ids: self.include_created_by_ids,


+            temporal_axes: self.temporal_axes,
+            include_web_ids: self.include_web_ids,
+            include_created_by_ids: self.include_created_by_ids,
+            include_edition_created_by_ids: self.include_edition_created_by_ids,


+            include_web_ids: self.include_web_ids,
+            include_created_by_ids: self.include_created_by_ids,
+            include_edition_created_by_ids: self.include_edition_created_by_ids,
+            include_type_ids: self.include_type_ids,


+            include_created_by_ids: self.include_created_by_ids,
+            include_edition_created_by_ids: self.include_edition_created_by_ids,
+            include_type_ids: self.include_type_ids,
+            include_type_titles: self.include_type_titles,


Copilot

Pull request overview

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

Comments suppressed due to low confidence (2)

libs/@local/graph/api/src/rest/entity/mod.rs:226

This router change removes previously-exposed endpoints (/entities/search and /entities/query/summarize) and introduces /entities/query/count, but the PR description frames this as a refactor of entity query handlers and says the endpoints should behave as before. Also, the checked-in OpenAPI snapshot still contains /entities/search and /entities/query/summarize and does not contain /entities/query/count (see libs/@local/graph/api/openapi/openapi.json around the paths section). Please confirm whether these endpoints were intended to be removed/added; if so, update/regenerate the OpenAPI accordingly, and if not, restore the routes/handlers.
libs/@local/graph/api/openapi/openapi.json:1655
The OpenAPI snapshot appears out of sync with the current router/handler set: it still documents /entities/query/summarize and /entities/search (operationIds summarize_entities / search_entities), and it does not document the newly-added /entities/query/count endpoint. This will break client generation and makes it unclear what the supported API surface is. Regenerate/update openapi.json from the current utoipa definitions (or restore the removed endpoints if they are still intended to exist).

          {
            "name": "after",
            "in": "query",
            "description": "The cursor to start reading from",
            "required": false,

+    let request = QueryEntitiesRequest::deserialize(&*request)
+        .map_err(Report::from)
+        .map_err(report_to_response)?;


+    let request = QueryEntitySubgraphRequest::deserialize(&request)
+        .map_err(Report::from)
+        .map_err(report_to_response)?;


+            CountEntitiesParams::deserialize(&request)
+                .map_err(Report::from)
+                .map_err(report_to_response)?,


indietyp added 3 commits June 8, 2026 12:36

chore: cleanup

1d0c399

chore: remove unused file

890cfa8

Copilot AI review requested due to automatic review settings June 8, 2026 11:41

indietyp mentioned this pull request Jun 8, 2026

BE-582: HashQL: Change opaque types from invariant to covariant #8835

Merged

indietyp mentioned this pull request Jun 8, 2026

BE-583, BE-584, BE-586: HashQL: Add HeapPool, improve spans, and propagate Critical severity through diagnostics #8836

Merged

graphite-app Bot assigned indietyp Jun 8, 2026

Copilot started reviewing on behalf of indietyp June 8, 2026 11:41 View session

vercel Bot temporarily deployed to Preview – petrinaut June 8, 2026 11:42 Inactive

github-actions Bot added area/libs Relates to first-party libraries/crates/packages (area) type/eng > backend Owned by the @backend team area/tests New or updated tests labels Jun 8, 2026

This was referenced Jun 8, 2026

BE-585, BE-591: HashQL: Add MIR interpreter test suite and refactor diagnostic categories #8837

Merged

BE-581, BE-589: HashQL: Introduce pass::lower/pass::place pipeline facades and fix cached constructor closure bug #8838

Merged

cursor Bot reviewed Jun 8, 2026

View reviewed changes

Comment thread libs/@local/graph/api/src/rest/entity/query/request.rs

Copilot AI reviewed Jun 8, 2026

View reviewed changes

Comment thread libs/@local/graph/api/src/rest/entity/query/request.rs Outdated

vercel Bot deployed to Preview – hash June 8, 2026 11:50 View deployment

indietyp force-pushed the bm/be-590-hgraph-entity-query-request-refactor branch from 044a4ff to c1e8a90 Compare June 8, 2026 11:55

indietyp force-pushed the bm/be-587-hashql-eval-interner-and-context-restructuring branch from 8af8844 to 82bb954 Compare June 8, 2026 11:55

vercel Bot deployed to Preview – petrinaut June 8, 2026 12:01 View deployment

vercel Bot deployed to Preview – hash June 8, 2026 12:03 View deployment

feat: add deny_unknown_fields

d2c0721

Copilot AI review requested due to automatic review settings June 8, 2026 12:22

cursor Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread libs/@local/graph/api/src/rest/entity/query/request.rs

vercel Bot deployed to Preview – hash June 16, 2026 09:10 View deployment

indietyp mentioned this pull request Jun 18, 2026

BE-538: HashQL: Permission system integration #8882

Open

6 tasks

indietyp force-pushed the bm/be-590-hgraph-entity-query-request-refactor branch from 8a4c804 to 877c368 Compare June 19, 2026 08:15

indietyp force-pushed the bm/be-587-hashql-eval-interner-and-context-restructuring branch from 90ab940 to 7cb3ed3 Compare June 19, 2026 08:15

vercel Bot deployed to Preview – petrinaut June 19, 2026 08:21 View deployment

vercel Bot deployed to Preview – hash June 19, 2026 08:24 View deployment

Copilot AI review requested due to automatic review settings June 19, 2026 15:14

indietyp force-pushed the bm/be-590-hgraph-entity-query-request-refactor branch from 877c368 to 3de4e61 Compare June 19, 2026 15:14

indietyp force-pushed the bm/be-587-hashql-eval-interner-and-context-restructuring branch from 7cb3ed3 to 233e8eb Compare June 19, 2026 15:14

Copilot started reviewing on behalf of indietyp June 19, 2026 15:14 View session

indietyp mentioned this pull request Jun 19, 2026

BE-607: HashQL: Refactor ModuleRegistry into builder/immutable split with allocator-generic stdlib construction #8887

Open

3 tasks

Copilot AI reviewed Jun 19, 2026

View reviewed changes

vercel Bot deployed to Preview – petrinaut June 19, 2026 15:18 View deployment

vercel Bot deployed to Preview – hash June 19, 2026 15:22 View deployment

indietyp force-pushed the bm/be-590-hgraph-entity-query-request-refactor branch from 3de4e61 to 5ac6afb Compare June 22, 2026 10:51

indietyp force-pushed the bm/be-587-hashql-eval-interner-and-context-restructuring branch from 233e8eb to 0f62210 Compare June 22, 2026 10:51

vercel Bot deployed to Preview – petrinaut June 22, 2026 10:55 View deployment

vercel Bot deployed to Preview – hash June 22, 2026 11:00 View deployment

indietyp force-pushed the bm/be-587-hashql-eval-interner-and-context-restructuring branch from 0f62210 to e9a1230 Compare June 22, 2026 12:02

Copilot AI review requested due to automatic review settings June 22, 2026 12:02

indietyp force-pushed the bm/be-590-hgraph-entity-query-request-refactor branch from 5ac6afb to 7083934 Compare June 22, 2026 12:02

Copilot started reviewing on behalf of indietyp June 22, 2026 12:02 View session

Copilot AI reviewed Jun 22, 2026

View reviewed changes

This was referenced Jun 22, 2026

BE-615: HashQL: Introduce the concept of synthetic closures in the MIR #8894

Open

BE-614: HashQL: Generate synthetic closure bodies for intrinsics used as first-class values #8895

Open

Copilot AI reviewed Jun 23, 2026

View reviewed changes

cursor Bot reviewed Jun 30, 2026

View reviewed changes

Comment thread libs/@local/graph/api/src/rest/entity/query/mod.rs

github-advanced-security AI found potential problems Jun 30, 2026

View reviewed changes

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

BE-590: hgraph: Refactor entity query handlers into `entity/query` submodule#8840
indietyp wants to merge 8 commits into
bm/be-587-hashql-eval-interner-and-context-restructuringfrom
bm/be-590-hgraph-entity-query-request-refactor

indietyp commented Jun 8, 2026

Uh oh!

cursor Bot commented Jun 8, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 8, 2026 •

edited

Loading

Uh oh!

indietyp commented Jun 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

codecov Bot commented Jun 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

indietyp commented Jun 8, 2026

🌟 What is the purpose of this PR?

🔗 Related links

🔍 What does this change?

🛡 What tests cover this?

❓ How to test this?

Uh oh!

cursor Bot commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

vercel Bot commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

indietyp commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

cursor Bot commented Jun 8, 2026 •

edited

Loading

vercel Bot commented Jun 8, 2026 •

edited

Loading

indietyp commented Jun 8, 2026 •

edited

Loading

codecov Bot commented Jun 8, 2026 •

edited

Loading