DUE TO SPAM, SIGN-UP IS DISABLED. Goto Selfserve wiki signup and request an account.
Motivation
In many streaming applications, particularly real-time analytics and monitoring systems, it is valuable to obtain partial results earlier rather than waiting for full join conditions to finalize. For Flink SQL interval joins, results are typically delayed until watermarks ensure no more matches can occur. This delay can be challenging for scenarios that require fast feedback. Early fire support addresses this by emitting intermediate results speculatively and using retractions or updates to maintain eventual consistency and ensure correctness. This approach can, however, change an append-only stream into a potentially update stream, so the planner and downstream components must be able to handle retraction/upsert messages.
Public Interfaces
Hints for Early Fire
Users can enable and configure early fire support using SQL hints. The following hint syntax is proposed:
SELECT /*+ EARLY_FIRE('delay'='5s','time_mode'='rowtime|proctime') */
A.id, B.value
FROM A
JOIN B
ON B.rowtime BETWEEN A.rowtime - INTERVAL '1' HOUR AND A.rowtime + INTERVAL '1' HOUR;
- DELAY: Specifies the initial delay (in time units such as ms, s, min or h) before the first early fire. Must be > 0.
- TIME_MODE (optional): Determines whether early-fire timers use event time or processing time.
- If omitted, defaults to:
- ROWTIME if it is an event-time interval join
- PROCTIME if it is a processing-time interval join
- If set to ROWTIME, the early fire timers use event time.
- The planner throws an exception indicating that TIME_MODE='ROWTIME' is invalid for a processing-time interval join. Sample error message: “EARLY_FIRE hint requested row-time triggering on a processing-time interval join. Row-time triggering requires a row-time interval join”.
- If set to PROCTIME, the early fire timers use wall-clock (processing) time. For instance, a user might force a processing-time early fire on an event-time interval join if they want partial results to follow wall-clock time rather than event time/watermarks.
- If omitted, defaults to:
- TARGET (optional): the operator type this hint applies to. The only supported value in this FLIP is interval_join. Any other value fails at planning with a clear message. When omitted, the hint applies to interval joins only - see the Compatibility section for the forward-compatibility guarantee.
Alignment With Existing Early-Fire Configurations
Flink already provides configurations like table.exec.emit.early-fire.enabled and table.exec.emit.early-fire.delay primarily for window operators. In this FLIP, we introduce a hint-based approach specifically for interval join. This FLIP deliberately uses a per-query hint for interval join rather than reusing those configs:
- Those configs are window-operator-specific (WindowEmitStrategy), not general ExecutionConfigOptions, so they do not currently apply to interval join.
- A hint scopes early fire to a single join, which is the intended granularity; a global config would affect every operator.
- Unifying interval-join early fire with the table.exec.emit.early-fire.* configs is out of scope here. That broader unification is tracked separately (FLINK-29692) and remains open.
Granularity of the Early Fire Hint
When a single SQL query block contains multiple operators (for example, multiple interval joins or aggregations), the EARLY_FIRE hint might only be intended for a specific operator. This section defines how to scope the hint so that only the desired operator is affected.
Multiple-Joins Example
Consider the following query with two interval joins:
SELECT /*+ EARLY_FIRE('delay'='5s', 'time_mode'='rowtime','target'='interval_join') */
o.*,
s.*,
d.*
FROM Orders o
LEFT JOIN Shipments s
ON o.id = s.order_id
AND o.order_time BETWEEN s.ship_time - INTERVAL '4' HOUR AND s.ship_time
RIGHT JOIN Delivery d
ON d.delivery_id = s.delivery_id
AND d.delivery_time BETWEEN s.ship_time AND s.ship_time + INTERVAL '12' HOUR;
Here, there are two joins:
- Orders ↔ Shipments (interval join)
- Shipments ↔ Delivery (interval join)
A single hint at the top of the query applies to every interval join in the block. In this example both joins would early-fire — and because the early-firing Orders ↔ Shipments join feeds the Shipments ↔ Delivery interval join (which requires insert-only input), the query fails at planning. To early-fire only one join, split into views (below).
Splitting Queries for Fine-Grained Control
To early-fire only one of the joins, split into stages and place the hint in the stage that contains that join. For example, to early-fire only the Orders ↔ Shipments join:
-- Stage 1: Apply EARLY_FIRE to the first join
CREATE VIEW OrdersWithShipments AS
SELECT /*+ EARLY_FIRE('delay'='5s', 'time_mode'='rowtime','target'='interval_join') */
o.*,
s.*
FROM Orders o
LEFT JOIN Shipments s
ON o.id = s.order_id
AND o.order_time BETWEEN s.ship_time - INTERVAL '4' HOUR AND s.ship_time;
-- Stage 2: Perform the second join without EARLY_FIRE (or with a different setting)
SELECT ows.*, d.*
FROM OrdersWithShipments ows
RIGHT JOIN Delivery d
ON d.delivery_id = ows.delivery_id
AND d.delivery_time BETWEEN ows.ship_time AND ows.ship_time + INTERVAL '12' HOUR;
This two-stage approach ensures each interval join (or operator) can have its own EARLY_FIRE configuration.
Additional Operators (Joins, Aggregations)
EARLY_FIRE only affects interval joins. Other operators in the same query — group aggregations, windows, or regular (non-interval) joins — never receive the hint, even when it is written at the top of the query. For example:
SELECT /*+ EARLY_FIRE('delay'='5s', 'time_mode'='rowtime','target'='interval_join') */
buyer, COUNT(*)
FROM Orders o
LEFT JOIN Shipments s
ON o.id = s.order_id
AND o.order_time BETWEEN s.ship_time - INTERVAL '1' HOUR AND s.ship_time
GROUP BY buyer;
The hint applies to the Orders ↔ Shipments interval join — it carries a time predicate, so it is an interval join; the GROUP BY aggregation is unaffected. A join without a time/interval predicate is a regular join and would likewise ignore the hint.
To give an operator its own early-fire setting — or to keep the hint away from operators you do not want it to touch — place the interval join in its own view:
-- Apply EARLY_FIRE to the interval join in a separate view
CREATE VIEW OrdersWithEarlyFire AS
SELECT /*+ EARLY_FIRE('delay'='5s', 'time_mode'='rowtime','target'='interval_join') */ *
FROM Orders o
LEFT JOIN Shipments s
ON o.id = s.order_id
AND o.order_time BETWEEN s.ship_time - INTERVAL '1' HOUR AND s.ship_time;
-- Then aggregate over the view (no early-fire hint here)
SELECT buyer, COUNT(*)
FROM OrdersWithEarlyFire
GROUP BY buyer;
Summary
- EARLY_FIRE applies to interval-join operators. Because it propagates like a standard join hint and takes no per-join argument, a single hint on a query block applies to every interval join in that block. To early-fire only one of several interval joins, scope it by splitting into separate statements or views (shown above), so each interval join sits in its own block. If an early-firing outer join feeds another interval join, planning fails — an interval join requires insert-only input — so the unsafe configuration is rejected at planning time rather than silently mis-emitted.
- Split queries for different early-fire settings. When multiple operators require separate early-fire configurations (or if you want to avoid ambiguity), split the SQL into separate statements (or views). This approach ensures each operator can have its own distinct EARLY_FIRE hint.
Planner Changes
Handling Hints:
- Update StreamPhysicalIntervalJoinRule to parse and propagate early fire hints (RelHint) to the corresponding physical node (StreamPhysicalIntervalJoin).
- Add support for parsing EARLY_FIRE hints in StreamPhysicalIntervalJoinRule.
- Attach early fire configurations (delay, time_mode) to the StreamPhysicalIntervalJoin node.
Propagation:
- Outer joins with early firing can switch from append-only to retraction/upsert mode, requiring updates to FlinkChangelogModeInferenceProgram so downstream operators know to handle retractions.
Planner Awareness:
- Outer joins with early firing can switch from append-only to retraction/upsert mode, requiring updates to FlinkChangelogModeInferenceProgram so downstream operators know to handle retractions.
Runtime Changes
StreamExecIntervalJoin Modifications:
- Modify StreamExecIntervalJoin to support early firing. Introduce two new parameters: earlyFireDelay and earlyFireTimeMode.
State Management:
- Add separate new keyed state(s) for early-fire bookkeeping — a per-row "already early-fired" flag, plus the scheduled early-fire timestamps:
- Gates whether a retraction is needed when a later match arrives, and prevents duplicate early emissions.
- Kept as new, separate state rather than widening the existing per-side cache tuple, so no TypeSerializer/savepoint migration is required for the existing cache — the new state is simply empty on restore from an existing savepoint.
- Checkpointed so processing-time early fire replays correctly across restore.
Event Emission Logic:
- Inner Join:
- Matches are already emitted immediately upon detection. Early fire logic is unnecessary.
- No state changes needed.
- Left Outer Join:
- Emit (A, NULL) early if no match exists at the time of the early fire.
- If a late match arrives, retract (A, NULL) and emit (A, B).
- Right Outer Join:
- Symmetrical to left join, emitting (NULL, B) early for unmatched B events.
- Retract (NULL, B) and emit (A, B) if a late match occurs.
- Full Outer Join:
- Combines the logic of left and right joins for unmatched rows on both sides.
Code Changes
Key Code Paths to Modify:
- FlinkChangelogModeInferenceProgram:
- Check whether the EARLY_FIRE hint set early-fire parameters on the StreamPhysicalIntervalJoin node — early firing is hint-driven, not a configuration option.
- Only an outer join with a non-negative window produces updates. Inner joins (which emit on match) and negative-window joins (which pad immediately, with no interval-join operator) stay INSERT_ONLY even when the hint is present; the hint is logged and ignored there.
- When early firing is enabled:
- ModifyKindSetTrait of IntervalJoin gains UPDATE, becoming {INSERT, UPDATE} — the join emits a speculative padded row and later corrects it with an update; it never emits deletes. This mirrors the existing window-aggregate early-fire precedent.
- UpdateKind can be:
- ONLY_UPDATE_AFTER, if the downstream sink only needs final updates (e.g., supports retract streams but only expects after-updates).
- BEFORE_AND_AFTER, if the downstream sink requires both before- and after-updates.
- Which one you choose depends on the requirements of the target sink. For example, if the sink is known to handle both “before” and “after” updates, we can set BEFORE_AND_AFTER. Otherwise, we can set ONLY_UPDATE_AFTER.
- Insert-only downstream guard: when the early-firing outer join produces updates but the required downstream/sink is insert-only (cannot consume updates), the planner fails at planning time with a tailored error that names the EARLY_FIRE hint — rather than silently producing a changelog stream the sink cannot consume. Sample message: "<requester> is insert-only, but the EARLY_FIRE hint makes this outer interval join produce update changes … Remove the EARLY_FIRE hint, or write into a downstream/sink that accepts update changes."
- When early firing is disabled:
- ModifyKindSetTrait of IntervalJoin is set to INSERT_ONLY (i.e., no retractions or updates are produced).
- UpdateKind of IntervalJoin is set to NONE.
- IntervalJoin Input Requirements (regardless of early firing setting):
- The inputs to an IntervalJoin should provide INSERT_ONLY modifies with NONE updates. In other words, IntervalJoin is designed such that its upstream operators do not send retractions or updates into the join.
- This modification ensures that:
- Downstream operators are aware they might receive retractions / updates
- The planner can properly handle the changelog mode for early firing interval joins
- StreamPhysicalIntervalJoinRule:
- Parse EARLY_FIRE hint and attach configurations to the StreamPhysicalIntervalJoin node.
- StreamPhysicalIntervalJoin:
- Propagate earlyFireDelay and earlyFireTimeMode to StreamExecIntervalJoin.
- TimeIntervalJoin:
- Introduce early fire timers: for each unmatched outer-side row, schedule a single early fire at (event-time or processing-time, per time_mode) + earlyFireDelay.
- Track already-early-fired rows in separate state (see State Management) so each row fires at most once and can be corrected later.
- Implement retraction logic: when a real match arrives for an already-early-fired row, retract the speculative padded row and emit the matched (A, B).
Compatibility, Deprecation, and Migration Plan
This feature is backward compatible for new queries:
- Default behavior remains unchanged unless the EARLY_FIRE hint is explicitly used.
- No impact on existing interval join queries without early fire hints.
Forward compatibility across operators: an EARLY_FIRE hint written without a target applies to interval joins only, and this is a stable guarantee. If a future FLIP adds early fire for another operator (e.g. window join), that operator must be opted in with an explicit target value; an existing untargeted hint will never begin affecting it. A query written today therefore cannot silently change behavior when new early-fire-capable operators are added later.
Note on toggling the hint on an existing job: adding EARLY_FIRE is a query change, not a configuration toggle. Enabling it flips the interval-join operator from append-only to update-producing ({INSERT} → {INSERT, UPDATE}), which changes the operator's output changelog mode and the downstream plan. The interval-join's own state needs no serializer migration — the new early-fire bookkeeping state simply starts empty on restore — but, as with other changelog-mode/plan changes in Flink SQL, restoring a savepoint taken before the hint was added into the hint-enabled job is not guaranteed compatible. The recommendation is to enable early fire from the initial deployment; if you add or remove the hint on a running stateful job, treat it like any other plan change (e.g. allow non-restored state, and confirm the downstream/sink can consume updates).
Test Plan
Unit Tests:
- Verify that early fire hints are correctly parsed and propagated through the planner.
- Validate emission behavior for each join type (inner, left, right, full outer).
Integration Tests:
- Simulate out-of-order events and verify that early-fired results are retracted/updated as expected.
End-to-End Tests:
- Use a streaming job with interval joins to verify correctness with watermarks, late events, and speculative emissions.
Rejected Alternatives
- Hints for Early Fire. Interval (optional): Specifies the interval (in time units) span between subsequent early fires. If not set, the early fire will occur only once, as specified by the DELAY parameter. Must be > 0.
- Immediate Early Firing Without Correction:
- This approach would violate consistency guarantees and was rejected.
- Handle the scenario where a user sets TIME_MODE='ROWTIME' on a processing-time interval join - Ignore and Fallback:
- When the planner detects TIME_MODE=ROWTIME for a processing-time interval join, it logs a warning and silently sets TIME_MODE='PROCTIME' instead.
- Pros: Keeps the query running in some consistent manner (still performs early firing, but by processing time).
- Cons: User may not realize their configuration has been overridden unless they notice the warning.
- Count-based early trigger. This is an early firing strategy that triggers output as soon as a certain number of elements have arrived in the current interval (i.e., before the interval is closed by the watermark).
- Granularity of the Early Fire Hint. Warn or error out if it detects more than one eligible operator in the same statement, unless a more specific rule or user configuration exists.
Future Work
- Per-join scoping: give EARLY_FIRE a way to target a specific join (as other Flink join hints disambiguate, e.g. via a table argument), so multiple interval joins in one statement can each carry their own setting without splitting into views. This removes the multiple-eligible-operator ambiguity by construction.