Skip to content

docs(query-engine): design engine boundaries for ASAPPlanner plans - #935

Draft
milindsrivastava1997 wants to merge 26 commits into
mainfrom
docs/asapplanner-engine-boundaries
Draft

milindsrivastava1997 wants to merge 26 commits into
mainfrom
docs/asapplanner-engine-boundaries

Conversation

@milindsrivastava1997

Copy link
Copy Markdown
Contributor

Design doc for the traits and boundaries ASAPQuery needs in order to run plans from ASAPPlanner (InstallablePlan) and retire asap-planner-rs. Adapters, fallback clients and ingest decoders stay; the precompute engine and SimpleEngine move behind new IngestEngine / QueryEngine traits.

Covers interfaces before → after, the new interfaces, recorded decisions, tabled questions (T1–T4) and open questions (Q3). It is limited to boundaries; engine implementations are out of scope.

The doc is the source of truth and will be updated as decisions change.

🤖 Generated with Claude Code

milindsrivastava1997 and others added 7 commits November 18, 2026 11:39
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…y decisions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ispatcher

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ngest waits

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…isions 34-39

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…dPlan decisions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…solve functions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@zzylol zzylol left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall the interfaces LGTM! Minor changes commented.
I can see when we actually implement these, there will be some missing fields.

put(SummaryKey, SummaryState); get(plan, summary, range); evict_before(plan, summary, ts);
earliest_timestamp_per_summary() -> Map<summary, ts>; // was get_earliest_timestamp_per_aggregation_id
}
struct SummaryKey { plan: PlanId, summary: PhysicalASAPNodeId, window: (i64, i64) }

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does summarykey mean? SummaryId?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was the key of one stored window, which was confusing. I split it into SummaryId { plan, node } and SummaryWindowKey { summary, window }.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

confused, need a call.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SummaryId-> ViewId(plan (plan is a sub-DAG), node (what is node))?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reworked; see the view store model (decisions 43–44). It is now three concepts: ViewDefinitionId (the physical computation), ViewInputDataScope (the data that went in), ViewInstance (the state). Happy to do a call.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Store keys are now (ViewDefinitionId, ViewInputDataScope), not plan and node. The definition id should be a physical view id from ASAPPlanner: ProjectASAP/ASAPPlanner#1429 (decision 44).


```rust
// main: the deployment owns the stores and injects them (decision 8).
let summaries = Arc::new(InMemorySummaryStore::new());

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we change the store definition to be "SummaryStore" and "RawDataStore", and make them internally decide whether in memory, or have the on disk part?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. The traits are the boundary, and whether data is in memory or on disk is up to the implementation (decision 8). Caveat: a durable store would need summary ids that survive a restart.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caveat: a durable store would need summary ids that survive a restart. need explain of this.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That caveat is gone. A physical ViewDefinitionId is the same across restarts, so a durable store can key recovered instances by it. Recovery itself is deferred (decision 8).


trait RawDataStore { append(Source, SampleBatch); read(Source, range); evict(retention, now); }

enum SampleBatch {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we reuse the term from current ASAPPlanner? If the SampleBatch refers to data sources?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renamed to RawDataBatch, after ASAPPlanner's read_raw_data. It holds raw input only (decision 13).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need a table definition here? I think no.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, removed. v1 only has TimeSeries.

milindsrivastava1997 and others added 11 commits November 18, 2026 22:18
…ind traits; generic ingest handler

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb
…executor value types

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb
… pipeline (I9)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb
… (I11), T7

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb
put(SummaryWindowKey, SummaryState); get(SummaryId, range); evict_before(SummaryId, ts);
timestamp_range_per_summary() -> Map<SummaryId, (earliest, latest)>; // was get_earliest_timestamp_per_aggregation_id
}
struct SummaryId { plan: PlanId, node: PhysicalASAPNodeId } // one summary

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SummaryId will be changed to ViewId.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ViewId, or a view's definition, should be a sub-DAG (this is defined as a node, mostly a node should be ok? or a DAG data structure in ASAPPlanner?)

@zzylol zzylol Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add comment of "plan id here is for retrieving the whole sub-DAG from a specific plan, given "node""

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renamed to ViewDefinitionId. ASAPPlanner's current definition_id already hashes the view's sub-DAG down to its Scans, but leaves out θ and the window width, so we asked for a physical id: ProjectASAP/ASAPPlanner#1429.

enum NotAnswerableReason { Unmatched, NotReady, EngineError(QueryEngineError) }

trait SummaryStore {
put(SummaryWindowKey, SummaryState); get(SummaryId, range); evict_before(SummaryId, ts);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We miss an indexing definition for SummaryStore, what "keys" we use for indexing?

Should we store index by view (SDS, output from one operator), or store by group-by keys (can be output from multiple operators)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"CapabilityMatched" how can we serve this?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The store is now opaque to how the state is structured. It is keyed by (definition, input data scope), and indexing is up to the implementation (decisions 8 and 43).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not in v1. It needs the ASAPPlanner API: ProjectASAP/ASAPPlanner#1430 (T2).

milindsrivastava1997 and others added 5 commits November 19, 2026 12:55
…stance); wait for ASAPPlanner physical view id

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb

struct ViewDefinitionId { // decision 44
definition_id: DefinitionId, // ASAPPlanner's logical id
physical: PhysicalProperties, // from ASAPPlanner: θ, pane width

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please see the comment in ASAPPlanner #1429

@zzylol zzylol Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

proposed:
ViewDefinitionId = (plan id, definition id)
plan Id = a version of physical DAG plan stored
definition_id: DefinitionId, // ASAPPlanner's logical id refering to root / sub-DAG of a view

We should be clear when defining terms for phyiscal and logical, e.g., regarding views, schema/coverage, plans (physical, logical).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See #935 (comment): views are keyed by (PlanId, PhysicalASAPNodeId, window).

constraints: SelectionConstraints, // from the plan's selection, e.g. label matchers
interval: (i64, i64), // the exact pane (start, end]
}
struct ViewInstanceKey { definition: ViewDefinitionId, scope: ViewInputDataScope }

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The view definition (ASAPPlanner's logical id) contains the input data already, because the e,g, Scan nodes are defined inside already.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So scope: ViewInputDataScope seems not needed

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See #935 (comment): views are keyed by (PlanId, PhysicalASAPNodeId, window).

definition_id: DefinitionId, // ASAPPlanner's logical id
physical: PhysicalProperties, // from ASAPPlanner: θ, pane width
}
struct ViewInputDataScope { // the concrete data that went in

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is defined as data source related nodes in definition id 's DAG already

@zzylol zzylol Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • interval may be needed or inside the constraints?
  • Constraints: need to think about how to define the constraints for easy capability-matching-based query serving, not in v1.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See #935 (comment): views are keyed by (PlanId, PhysicalASAPNodeId, window).

trait ViewStore { // in-memory or on disk; indexing is the implementation's (decision 8)
put(ViewInstanceKey, ViewInstance); // once; never rewritten (I16)
get(&ViewInstanceKey) -> Option<ViewInstance>;
instances(&ViewDefinitionId, &SelectionConstraints, interval) -> Vec<(ViewInputDataScope, ViewInstance)>;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need a concrete algorithm here on

  • SelectionConstraints definition
  • how to match SelectionConstraints to the views.
  • timestamp_range_per_view() -> Map<ViewDefinitionId, (earliest, latest)>; this may not be needed

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question (will raise issue): should a view be bounded batch, or unbounded streaming?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See #935 (comment): views are keyed by (PlanId, PhysicalASAPNodeId, window).

@milindsrivastava1997

milindsrivastava1997 commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor Author

View identity, logical vs physical ids: findings and proposal (replies to the threads on lines 126, 128, 132 and 139, and ProjectASAP/ASAPPlanner#1429)

How ASAPPlanner layers identity today (checked against main):

Level Identifies Id Includes
Coverage (memo group) what is computed, over which rows ViewCoverage { definition_id, selection } the computation and summary type; label matchers and the time range are lifted into selection (aggregate_coverage.rs)
Logical candidate one way to compute it none + operator arguments (tumbling-window width) and θ, which ASAPPlanner calls a logical property (LogicalProperties { parameters })
Physical node one node of one selected plan PhysicalASAPNodeId, plan-scoped + PhysicalProperties { timing, lifetime } and retention_ms

Lifted selection: walking down from a SummaryAgg or Aggregate, the coverage derivation takes the predicates that are a value set or an interval on one source column (label matchers, and the TimeRange/TimeShift as one time interval) out of the definition and records them as selection: which rows went in. Everything else stays in the definition. E.g. KLL quantile_over_time(0.9, m{job="api"}[5m]) has definition "KLL over Scan(m)" (hashed into definition_id) and selection {job ∈ {"api"}, ts ∈ (T−5m, T]}; m{job="web"}[1h] has the same definition_id and a different selection.

Findings:

  1. definition_id is logical, at the coverage level: it excludes θ, the window width and the lifted selection. Two views in one plan that differ only in matchers, or only in θ, share it. So neither (definition_id, selection) nor (plan id, definition_id) identifies a stored view.
  2. We have been misusing "physical properties" (in this doc and in #1429): in ASAPPlanner θ is a logical property, the window width is an operator argument, and physical properties are timing and lifetime.
  3. What #1429 asks for is already in the plan file: every sketch node carries θ (PhysicalASAPDAGNode::parameters, including a SummaryMerge or Filter over states), and a chain node carries its window width.

Proposal for the data plane (v1):

  • A view is identified by (PlanId, PhysicalASAPNodeId). PlanId is the version of the installed physical plan; the node fixes the view's sub-DAG, coverage, θ and window widths. This is close to the earlier "ViewId(plan, node)" suggestion. No hashing, and no new ASAPPlanner field needed.
  • A stored instance is keyed by (PlanId, PhysicalASAPNodeId, window), with window the absolute (start, end]. The window can't come from the selection: its time constraint is relative to the evaluation time. One instance per window holds all group keys' states, which is how the executor reads a view ((window_end, keys, state) rows).
  • ViewInputDataScope and SelectionConstraints are dropped from the store: the node fixes its selection, so constraints are redundant per instance. How to define constraints for capability matching is left for #1430, not v1. ViewStore::instances(view, interval) then returns the stored windows within the interval; exact tiling is the executor's DataStore contract.
  • Cost: reusing views across plans (T1) and durable recovery would need an id that does not depend on the plan. Not needed in v1, which installs once (I14).

Proposed for ASAPPlanner (none blocks v1): reframe #1429 as "a plan-independent id at the logical-candidate level (the sub-DAG with its θ and window widths), for reusing views across plans", and document definition_id as the logical coverage id, not a store key (or rename it, e.g. coverage_id). Capability matching keeps using it.

Also:

  • timestamp_range_per_view (line 139): kept; it feeds runtime info, which experiments use to send queries aligned with when views are computed (decision 45).
  • Bounded or unbounded view (line 139): in this design a view is an unbounded sequence of bounded instances. Each sealed window is one immutable instance; the ingest engine appends windows, the query engine reads whole windows and evicts by time, and open windows are never read (I11, I16). Happy to continue in the issue.

I'll update the doc (terms, interface sketch, decisions 38, 43–44, step order) once we agree.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants