Data windows

How-to guideApplies to: Unified engine deployments

Give each run an explicit period of data to process. A data window records the intended interval even if execution starts late or the run is repeated later.

Use inclusive start and exclusive end

A window covers [start, end): include the start and exclude the end. Write both conditions in SQL:

ordered_at >= :__window_start
AND ordered_at < :__window_end

The engine supplies typed timestamp values. It does not add this filter to your query. Using only the start bound, or using an inclusive end, can process the wrong rows across adjacent periods.

1. Open a windowed workload

This Manual example includes timestamped orders and enables Use data windows. No external data or stored table is needed. Review the complete definition to see workflow.data_windows.

{
  "name": "Learn - daily order windows",
  "tasks": [
    {
      "name": "daily_sales",
      "sql": "WITH orders(id, ordered_at, amount) AS (\n  VALUES\n    (1, TIMESTAMP '2026-01-01 09:00:00', 20),\n    (2, TIMESTAMP '2026-01-01 18:00:00', 30),\n    (3, TIMESTAMP '2026-01-02 00:00:00', 15),\n    (4, TIMESTAMP '2026-01-02 12:00:00', 40),\n    (5, TIMESTAMP '2026-01-03 00:00:00', 25)\n)\nSELECT COUNT(*) AS order_count, COALESCE(SUM(amount), 0) AS sales\nFROM orders\nWHERE ordered_at >= :__window_start\n  AND ordered_at < :__window_end;",
      "settings": {
        "current_catalog": "default",
        "namespace": [
          "default"
        ],
        "time_zone": "UTC",
        "case_sensitive": false,
        "ansi_enabled": true
      }
    }
  ],
  "dependencies": [],
  "options": {
    "execution_target": "DuckDb"
  },
  "policy": "Manual",
  "workflow": {
    "data_windows": true,
    "notifications": []
  }
}

2. Supply a manual window

Validate and save the workload. Select Start run and enter Window start and Window end. The dialog shows the browser’s time zone. Choose the local times that correspond to January 1, 2026, 00:00 UTC and January 2, 2026, 00:00 UTC. In Asia/Kolkata, these are 05:30 on each date. Start the run and inspect its recorded window. Expect two orders and sales of 50. The order exactly at the end belongs to the next window. You can also start the same window through HTTP. Replace the workload ID in the route, use its saved revision, and use a fresh submission ID for each new run:

POST /api/v1/workloads/{workload_id}/runs
Content-Type: application/json

{
  "submission_id": "33333333-3333-4333-8333-333333333333",
  "expected_revision": 1,
  "parameters": {},
  "data_window": {
    "start_unix_millis": 1767225600000,
    "end_unix_millis": 1767312000000,
    "timezone": "UTC"
  }
}

This is 2026-01-01 00:00 UTC through 2026-01-02 00:00 UTC. Expect two orders and sales of 50. The order exactly at the end belongs to the next window. For the next day, use start 1767312000000 and end 1767398400000, with a new submission ID. Expect two orders and sales of 55. Inspect the recorded window on each run.

3. Generate windows from a schedule

Choose a cron or interval schedule and keep Use data windows enabled. Each due boundary ends its window. An interval uses the previous interval boundary; cron uses the previous calendar boundary in its schedule time zone. For daily midnight UTC, the run due on January 2 processes January 1. A run that starts at 00:12 still uses that same recorded window. If you save a live recurring schedule, it can begin creating runs. Use the manual API example first, and pause recurring work when you finish.

Keep scheduled time and window distinct

:__scheduled_at records the invocation’s logical scheduled time. :__window_start and :__window_end identify the period to process. Current wall-clock time such as CURRENT_TIMESTAMP describes execution time, so it should not replace the recorded window filter. A data window does not freeze source table contents. Repeating it later can read changed data. Choose snapshot reads or a suitable publication strategy when the source can change.

Publish windows safely

Use a destination key or partition strategy that makes repeated processing deliberate. Appending the same window twice can duplicate data. Overwriting the entire destination with one window can erase other windows. Use Backfills for many historical windows and Selective reruns to repeat selected tasks from a recorded run.

Transformation Engine

Learn Laminar

Workloads

SQL reference

HTTP API

Recipes

Operations

Use inclusive start and exclusive end

1. Open a windowed workload

2. Supply a manual window

3. Generate windows from a schedule

Keep scheduled time and window distinct

Publish windows safely

​Use inclusive start and exclusive end

​1. Open a windowed workload

​2. Supply a manual window

​3. Generate windows from a schedule

​Keep scheduled time and window distinct

​Publish windows safely

Use inclusive start and exclusive end

1. Open a windowed workload

2. Supply a manual window

3. Generate windows from a schedule

Keep scheduled time and window distinct

Publish windows safely