docs(planner): document windowing override

Author: milindsrivastava1997

asap-planner-rs/src/lib.rs

@@ -15,6 +15,7 @@ pub use asap_types::PromQLSchema;
 pub use config::input::ControllerConfig;
 pub use config::input::ElasticDSLControllerConfig;
 pub use config::input::SQLControllerConfig;
+pub use config::input::{WindowingConfig, WindowingType};
 pub use elastic_dsl::ElasticController;
 pub use elastic_dsl::ElasticIndexSchemaBuilder;
 pub use elastic_dsl::ElasticRuntimeOptions;

asap-planner-rs/src/planner/window.rs

@@ -105,7 +105,14 @@ pub fn apply_windowing_override(
             config.slide_interval_ms = config.window_size_ms;
         }
         WindowingType::Sliding => {
-            let divisor = windowing.slide_divisor.expect("validated sliding divisor");
+            let divisor = match windowing.slide_divisor {
+                Some(divisor) => divisor,
+                None => {
+                    return Err(
+                        "windowing.slide_divisor is required for sliding windows".to_string()
+                    )
+                }
+            };
             if !config.window_size_ms.is_multiple_of(divisor) {
                 return Err(format!(
                     "window_size_ms ({}) must be evenly divisible by slide_divisor ({divisor})",

asap-planner-rs/src/promql/generator.rs

@@ -31,6 +31,12 @@ pub fn generate_plan(
 ) -> Result<GeneratorOutput, ControllerError> {
     let metric_schema = schema.clone();
 
+    if let Some(windowing) = &controller_config.windowing {
+        windowing
+            .validate()
+            .map_err(ControllerError::PlannerError)?;
+    }
+
     // Determine cleanup policy
     let cleanup_policy = controller_config
         .aggregate_cleanup

asap-planner-rs/src/sql/generator.rs

@@ -25,6 +25,12 @@ pub fn generate_sql_plan(
     config: &SQLControllerConfig,
     opts: &SQLRuntimeOptions,
 ) -> Result<GeneratorOutput, ControllerError> {
+    if let Some(windowing) = &config.windowing {
+        windowing
+            .validate()
+            .map_err(ControllerError::PlannerError)?;
+    }
+
     let eval_time: f64 = opts.query_evaluation_time.unwrap_or_else(|| {
         SystemTime::now()
             .duration_since(UNIX_EPOCH)

asap-planner-rs/tests/integration.rs

@@ -172,6 +172,39 @@ query_groups: []
         .contains("windowing.slide_divisor is only valid for sliding windows"));
 }
 
+#[test]
+fn explicit_tumbling_window_override_keeps_tumbling_candidates() {
+    let controller = Controller::from_yaml_with_schema(
+        r#"
+windowing:
+  type: "tumbling"
+query_groups:
+  - id: 1
+    queries:
+      - "rate(http_requests_total[1m])"
+    repetition_delay_ms: 60000
+    controller_options:
+      accuracy_sla: 0.99
+      latency_sla: 1.0
+"#,
+        http_requests_schema(),
+        arroyo_opts(),
+    )
+    .unwrap();
+
+    let output = controller.generate().unwrap();
+    let streaming: serde_yaml::Value =
+        serde_yaml::from_str(&output.to_streaming_yaml_string().unwrap()).unwrap();
+    let aggregation = &streaming["aggregations"][0];
+
+    assert_eq!(aggregation["windowType"].as_str(), Some("tumbling"));
+    assert_eq!(
+        aggregation["slideIntervalMs"].as_u64(),
+        aggregation["windowSizeMs"].as_u64()
+    );
+    assert_ne!(aggregation["windowType"].as_str(), Some("sliding"));
+}
+
 /// Schema for binary arithmetic tests: errors_total and requests_total.
 fn binary_arithmetic_schema() -> PromQLSchema {
     PromQLSchema::new()

asap-tools/experiments/CONFIG_PARAMETERS_REFERENCE.md

@@ -204,6 +204,25 @@ These parameters must be provided for all experiment scripts:
 - **Example**: `"10s"`
 - **Usage**: Controls pre-computed metric updates
 
+## Planner Windowing Override
+
+#### `windowing` (object, optional)
+- **Description**: Global manual override for the planner's window type
+- **Default**: Omitted, which preserves tumbling-window planning
+- **Choices**: `tumbling`, `sliding`
+- **Scope**: Applies to PromQL and SQL planner inputs; ElasticDSL is unchanged
+
+#### `windowing.type` (string, required when `windowing` is present)
+- **Description**: Selects the planner window type
+- **Choices**: `tumbling`, `sliding`
+
+#### `windowing.slide_divisor` (int, required for sliding)
+- **Description**: Computes each query's slide interval as
+  `window_size_ms / slide_divisor`
+- **Validation**: Must be at least 2 and must evenly divide every supported
+  query's computed window size; invalid workloads fail plan generation
+- **Constraint**: Do not provide this field for `tumbling`
+
 ---
 
 ## Monitoring Configuration

asap-tools/experiments/config/config.yaml

@@ -99,6 +99,13 @@ query_engine:
 controller:
   punting: true  # Enable query punting based on performance heuristics (should_be_performant check)
 
+# Optional manual planner windowing override. Omit this block to preserve the
+# default tumbling-window behavior. For sliding windows, the divisor must be
+# at least 2 and must evenly divide every query's computed window size.
+# windowing:
+#   type: "sliding"
+#   slide_divisor: 4
+
 # Aggregate cleanup configuration
 # Policy options:
 #   - "circular_buffer": Keep N most recent aggregates (fixed-count cleanup)

asap-tools/experiments/experiment_only_ingest_path.py

@@ -190,6 +190,7 @@ def main(cfg: DictConfig):
                 local_experiment_root_dir,
                 cfg.aggregate_cleanup,
                 cfg.get("sketch_parameters", None),
+                cfg.get("windowing", None),
             )
         )
         sync.rsync_controller_client_configs(

asap-tools/experiments/experiment_run_clickhouse.py

@@ -377,7 +377,10 @@ def main(cfg: DictConfig) -> None:
 
             # Generate and rsync the planner input config to the node
             planner_input_yaml = config.generate_sql_planner_input(
-                ep.query_groups, dataset_cfg, cfg.get("sketch_parameters", None)
+                ep.query_groups,
+                dataset_cfg,
+                cfg.get("sketch_parameters", None),
+                cfg.get("windowing", None),
             )
             local_planner_input = os.path.join(
                 local_controller_dir, "planner_input.yaml"

asap-tools/experiments/experiment_run_e2e.py

@@ -200,6 +200,7 @@ def main(cfg: DictConfig):
             local_experiment_root_dir,
             cfg.aggregate_cleanup,
             cfg.get("sketch_parameters", None),
+            cfg.get("windowing", None),
         )
     )
     sync.rsync_controller_client_configs(