BE-455: HashQL: Introduce evaluation orchestrator#8586
Merged
indietyp merged 7 commits intoMay 25, 2026
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
3 Skipped Deployments
|
github-actions
Bot
added
area/deps
This was referenced Mar 26, 2026
Merged
Member
Author
This was referenced Mar 26, 2026
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #8586 +/- ##
==========================================
+ Coverage 58.82% 58.97% +0.14%
==========================================
Files 1328 1340 +12
Lines 126882 129010 +2128
Branches 5790 5832 +42
==========================================
+ Hits 74644 76080 +1436
- Misses 51357 52032 +675
- Partials 881 898 +17
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
3 tasks
3 tasks
indietyp
force-pushed
the
bm/be-455-hashql-create-evaluation-target-coordinator
branch
from
95af2dc to
8045f18
Compare
|
Deployment failed with the following error: |
Contributor
Dependency ReviewThe following issues were found:
VulnerabilitiesCargo.lock
License Issueslibs/@local/hashql/eval/Cargo.toml
OpenSSF ScorecardScorecard details
Scanned Files
|
3 tasks
3 tasks
indietyp
force-pushed
the
bm/be-455-hashql-create-evaluation-target-coordinator
branch
from
8045f18 to
2c34639
Compare
indietyp
force-pushed
the
bm/be-306-hashql-postgres-translation
branch
from
1024ba5 to
1e966bd
Compare
3 tasks
indietyp
force-pushed
the
bm/be-455-hashql-create-evaluation-target-coordinator
branch
from
a412453 to
f722e52
Compare
indietyp
force-pushed
the
bm/be-455-hashql-create-evaluation-target-coordinator
branch
from
f722e52 to
83bf74a
Compare
indietyp
force-pushed
the
bm/be-523-hashql-suspendable-interpreter-with-structured-values-and
branch
from
dae3f47 to
0a89a10
Compare
indietyp
force-pushed
the
bm/be-455-hashql-create-evaluation-target-coordinator
branch
from
83bf74a to
e30f552
Compare
indietyp
force-pushed
the
bm/be-523-hashql-suspendable-interpreter-with-structured-values-and
branch
from
0a89a10 to
b2d61fe
Compare
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
This was referenced May 4, 2026
TimDiekmann
previously approved these changes
May 22, 2026
There was a problem hiding this comment.
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 38e5398. Configure here.
TimDiekmann
approved these changes
May 25, 2026
Contributor
Benchmark results
|
| Function | Value | Mean | Flame graphs |
|---|---|---|---|
| resolve_policies_for_actor | user: empty, selectivity: high, policies: 2002 | Flame Graph | |
| resolve_policies_for_actor | user: empty, selectivity: low, policies: 1 | Flame Graph | |
| resolve_policies_for_actor | user: empty, selectivity: medium, policies: 1001 | Flame Graph | |
| resolve_policies_for_actor | user: seeded, selectivity: high, policies: 3314 | Flame Graph | |
| resolve_policies_for_actor | user: seeded, selectivity: low, policies: 1 | Flame Graph | |
| resolve_policies_for_actor | user: seeded, selectivity: medium, policies: 1526 | Flame Graph | |
| resolve_policies_for_actor | user: system, selectivity: high, policies: 2078 | Flame Graph | |
| resolve_policies_for_actor | user: system, selectivity: low, policies: 1 | Flame Graph | |
| resolve_policies_for_actor | user: system, selectivity: medium, policies: 1033 | Flame Graph |
policy_resolution_medium
| Function | Value | Mean | Flame graphs |
|---|---|---|---|
| resolve_policies_for_actor | user: empty, selectivity: high, policies: 102 | Flame Graph | |
| resolve_policies_for_actor | user: empty, selectivity: low, policies: 1 | Flame Graph | |
| resolve_policies_for_actor | user: empty, selectivity: medium, policies: 51 | Flame Graph | |
| resolve_policies_for_actor | user: seeded, selectivity: high, policies: 269 | Flame Graph | |
| resolve_policies_for_actor | user: seeded, selectivity: low, policies: 1 | Flame Graph | |
| resolve_policies_for_actor | user: seeded, selectivity: medium, policies: 107 | Flame Graph | |
| resolve_policies_for_actor | user: system, selectivity: high, policies: 133 | Flame Graph | |
| resolve_policies_for_actor | user: system, selectivity: low, policies: 1 | Flame Graph | |
| resolve_policies_for_actor | user: system, selectivity: medium, policies: 63 | Flame Graph |
policy_resolution_none
| Function | Value | Mean | Flame graphs |
|---|---|---|---|
| resolve_policies_for_actor | user: empty, selectivity: high, policies: 2 | Flame Graph | |
| resolve_policies_for_actor | user: empty, selectivity: low, policies: 1 | Flame Graph | |
| resolve_policies_for_actor | user: empty, selectivity: medium, policies: 1 | Flame Graph | |
| resolve_policies_for_actor | user: system, selectivity: high, policies: 8 | Flame Graph | |
| resolve_policies_for_actor | user: system, selectivity: low, policies: 1 | Flame Graph | |
| resolve_policies_for_actor | user: system, selectivity: medium, policies: 3 | Flame Graph |
policy_resolution_small
| Function | Value | Mean | Flame graphs |
|---|---|---|---|
| resolve_policies_for_actor | user: empty, selectivity: high, policies: 52 | Flame Graph | |
| resolve_policies_for_actor | user: empty, selectivity: low, policies: 1 | Flame Graph | |
| resolve_policies_for_actor | user: empty, selectivity: medium, policies: 25 | Flame Graph | |
| resolve_policies_for_actor | user: seeded, selectivity: high, policies: 94 | Flame Graph | |
| resolve_policies_for_actor | user: seeded, selectivity: low, policies: 1 | Flame Graph | |
| resolve_policies_for_actor | user: seeded, selectivity: medium, policies: 26 | Flame Graph | |
| resolve_policies_for_actor | user: system, selectivity: high, policies: 66 | Flame Graph | |
| resolve_policies_for_actor | user: system, selectivity: low, policies: 1 | Flame Graph | |
| resolve_policies_for_actor | user: system, selectivity: medium, policies: 29 | Flame Graph |
read_scaling_complete
| Function | Value | Mean | Flame graphs |
|---|---|---|---|
| entity_by_id;one_depth | 1 entities | Flame Graph | |
| entity_by_id;one_depth | 10 entities | Flame Graph | |
| entity_by_id;one_depth | 25 entities | Flame Graph | |
| entity_by_id;one_depth | 5 entities | Flame Graph | |
| entity_by_id;one_depth | 50 entities | Flame Graph | |
| entity_by_id;two_depth | 1 entities | Flame Graph | |
| entity_by_id;two_depth | 10 entities | Flame Graph | |
| entity_by_id;two_depth | 25 entities | Flame Graph | |
| entity_by_id;two_depth | 5 entities | Flame Graph | |
| entity_by_id;two_depth | 50 entities | Flame Graph | |
| entity_by_id;zero_depth | 1 entities | Flame Graph | |
| entity_by_id;zero_depth | 10 entities | Flame Graph | |
| entity_by_id;zero_depth | 25 entities | Flame Graph | |
| entity_by_id;zero_depth | 5 entities | Flame Graph | |
| entity_by_id;zero_depth | 50 entities | Flame Graph |
read_scaling_linkless
| Function | Value | Mean | Flame graphs |
|---|---|---|---|
| entity_by_id | 1 entities | Flame Graph | |
| entity_by_id | 10 entities | Flame Graph | |
| entity_by_id | 100 entities | Flame Graph | |
| entity_by_id | 1000 entities | Flame Graph | |
| entity_by_id | 10000 entities | Flame Graph |
representative_read_entity
| Function | Value | Mean | Flame graphs |
|---|---|---|---|
| entity_by_id | entity type ID: https://blockprotocol.org/@alice/types/entity-type/block/v/1
|
Flame Graph | |
| entity_by_id | entity type ID: https://blockprotocol.org/@alice/types/entity-type/book/v/1
|
Flame Graph | |
| entity_by_id | entity type ID: https://blockprotocol.org/@alice/types/entity-type/building/v/1
|
Flame Graph | |
| entity_by_id | entity type ID: https://blockprotocol.org/@alice/types/entity-type/organization/v/1
|
Flame Graph | |
| entity_by_id | entity type ID: https://blockprotocol.org/@alice/types/entity-type/page/v/2
|
Flame Graph | |
| entity_by_id | entity type ID: https://blockprotocol.org/@alice/types/entity-type/person/v/1
|
Flame Graph | |
| entity_by_id | entity type ID: https://blockprotocol.org/@alice/types/entity-type/playlist/v/1
|
Flame Graph | |
| entity_by_id | entity type ID: https://blockprotocol.org/@alice/types/entity-type/song/v/1
|
Flame Graph | |
| entity_by_id | entity type ID: https://blockprotocol.org/@alice/types/entity-type/uk-address/v/1
|
Flame Graph |
representative_read_entity_type
| Function | Value | Mean | Flame graphs |
|---|---|---|---|
| get_entity_type_by_id | Account ID: bf5a9ef5-dc3b-43cf-a291-6210c0321eba
|
Flame Graph |
representative_read_multiple_entities
| Function | Value | Mean | Flame graphs |
|---|---|---|---|
| entity_by_property | traversal_paths=0 | 0 | |
| entity_by_property | traversal_paths=255 | 1,resolve_depths=inherit:1;values:255;properties:255;links:127;link_dests:126;type:true | |
| entity_by_property | traversal_paths=2 | 1,resolve_depths=inherit:0;values:0;properties:0;links:0;link_dests:0;type:false | |
| entity_by_property | traversal_paths=2 | 1,resolve_depths=inherit:0;values:0;properties:0;links:1;link_dests:0;type:true | |
| entity_by_property | traversal_paths=2 | 1,resolve_depths=inherit:0;values:0;properties:2;links:1;link_dests:0;type:true | |
| entity_by_property | traversal_paths=2 | 1,resolve_depths=inherit:0;values:2;properties:2;links:1;link_dests:0;type:true | |
| link_by_source_by_property | traversal_paths=0 | 0 | |
| link_by_source_by_property | traversal_paths=255 | 1,resolve_depths=inherit:1;values:255;properties:255;links:127;link_dests:126;type:true | |
| link_by_source_by_property | traversal_paths=2 | 1,resolve_depths=inherit:0;values:0;properties:0;links:0;link_dests:0;type:false | |
| link_by_source_by_property | traversal_paths=2 | 1,resolve_depths=inherit:0;values:0;properties:0;links:1;link_dests:0;type:true | |
| link_by_source_by_property | traversal_paths=2 | 1,resolve_depths=inherit:0;values:0;properties:2;links:1;link_dests:0;type:true | |
| link_by_source_by_property | traversal_paths=2 | 1,resolve_depths=inherit:0;values:2;properties:2;links:1;link_dests:0;type:true |
scenarios
| Function | Value | Mean | Flame graphs |
|---|---|---|---|
| full_test | query-limited | Flame Graph | |
| full_test | query-unlimited | Flame Graph | |
| linked_queries | query-limited | Flame Graph | |
| linked_queries | query-unlimited | Flame Graph |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🌟 What is the purpose of this PR?
Introduce the evaluation orchestrator: the runtime layer that drives HashQL query execution across the interpreter and PostgreSQL, handling suspension fulfillment, row hydration, continuation decoding, and result assembly.
When the MIR interpreter suspends on a
GraphRead, it yields a description of the data it needs but can't fetch itself. The orchestrator takes that suspension, looks up the pre-compiled SQL, encodes parameters, executes the query, hydrates each result row into a typedValuetree, runs any client-side filter chains (which may themselves interleave interpreter and postgres execution), decodes continuation state for multi-island queries, and packages the result into aContinuationthat resumes the interpreter.🔍 What does this change?
Orchestrator (
eval/src/orchestrator/)mod.rs: top-levelOrchestratorthat owns the database client and query registry. Providesrun_infor full query execution andfulfill_infor resolving a single suspension.request/graph_read.rs: per-suspension handler that drives the query-execute-hydrate-filter-collect loop forGraphReadsuspensions.partial.rs: three-state hydration (Skipped/Null/Value) that assembles flat result columns into nested vertex value trees matching the HashQL type hierarchy.codec/decode: deserializes JSON column values fromtokio_postgresrows into typedValues, guided by the HashQL type system.codec/encode: serializes runtimeValues and query parameters into formstokio_postgrescan send to the database.postgres.rs: continuation state for multi-island execution. When a compiled query returns continuation columns (target block, locals, serialized values), this hydrates and validates them, then flushes the decoded state into the interpreter's callstack.events.rs: opt-in event tracing with zero-cost()sink.AppendEventLogcollects events into aVecfor test assertions.tail.rs: result accumulation strategies (currentlyCollectinto aList).error.rs: structured bridge errors. All variants useSeverity::Bugbecause if the bridge fails, the compiler or runtime produced something invalid.seed.rs,inputs.rs,directives.rs: test infrastructure for constructing orchestrator inputs from J-Expr test files.Postgres extensions (
eval/src/postgres/)types.rs: recursive type-tree navigation for resolving struct fields to concrete types.continuation.rs: naming conventions and expression helpers for continuation LATERAL subqueries.parameters.rs: new parameter kinds for temporal axes and continuation locals.traverse.rs: mapping fromEntityPathto physical PostgreSQL columns (temporal ranges decomposed to JSONB intervals, edition/identity columns).filter/: client-side filter chain changes for multi-island filter bodies.Compilation pipeline (
compiletest/src/pipeline.rs)Pipelinestruct that drives the full J-Expr to prepared-SQL compilation sequence with staged access to intermediate results. Used by the orchestrator test harness and compiletest.Test harness (
eval/tests/orchestrator/).jsoncUI test files and programmatic Rust builders.Pre-Merge Checklist 🚀
🚢 Has this modified a publishable library?
This PR:
📜 Does this require a change to the docs?
The changes in this PR:
🕸️ Does this require a change to the Turbo Graph?
The changes in this PR:
🐾 Next steps
GraphReadtail strategies beyondCollect(e.g. streaming, pagination).🛡 What tests cover this?
eval/tests/orchestrator/): end-to-end tests against a real PostgreSQL instance covering simple reads, filtered reads, diamond CFG filters, link data, metadata fields, let bindings, sequential filters, and entity type projections.orchestrator/codec/decode/tests.rs,codec/encode/tests.rs): round-trip encoding/decoding of values, parameters, and edge cases.eval/tests/ui/postgres/): snapshot tests for SQL output.❓ How to test this?
cargo nextest run --package hashql-evalcargo test --package hashql-eval --doc