This is an automated email from the ASF dual-hosted git repository.
RocMarshal pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/flink.git
The following commit(s) were added to refs/heads/master by this push:
new e80ab887899 [FLINK-40174][docs] Document the EARLY_FIRE hint for
interval joins
e80ab887899 is described below
commit e80ab887899dd9de76546ad4fafa95376136c574
Author: weiqingy <[email protected]>
AuthorDate: Sat Jul 18 13:06:49 2026 -0700
[FLINK-40174][docs] Document the EARLY_FIRE hint for interval joins
Document the EARLY_FIRE join hint for SQL interval joins in the EN and ZH
join docs: its semantics (speculative null-padded emission and later
correction), the target/delay/time-mode options, the outer-join-only
scope, and its relationship to the table.exec.emit.* configuration.
---
.../content.zh/docs/sql/reference/queries/joins.md | 26 ++++++++++++++++++++++
docs/content/docs/sql/reference/queries/joins.md | 26 ++++++++++++++++++++++
2 files changed, 52 insertions(+)
diff --git a/docs/content.zh/docs/sql/reference/queries/joins.md
b/docs/content.zh/docs/sql/reference/queries/joins.md
index 012d8b14327..2a0cbaa52e1 100644
--- a/docs/content.zh/docs/sql/reference/queries/joins.md
+++ b/docs/content.zh/docs/sql/reference/queries/joins.md
@@ -104,6 +104,32 @@ AND o.order_time BETWEEN s.ship_time - INTERVAL '4' HOUR
AND s.ship_time
对于流式查询，对比 regular join，interval join 只支持有时间属性的非更新表。
由于时间属性是递增的，Flink 从状态中移除旧值也不会影响结果的正确性。
+### Outer Interval Join 的提前触发（Early Fire）
+
+默认情况下，outer interval join 会等到未匹配行的时间窗口完全关闭后，才将该行以 null 补齐的形式输出。`EARLY_FIRE`
提示可以缩短这个等待：未匹配的 outer 行会在可配置的 `delay` 之后被推测性地以 null
补齐输出，如果之后在窗口内出现真正的匹配，则会进行更正。这会将仅追加（append-only）的结果变为更新（updating）结果，因此下游 sink
必须能够接受更新。
+
+```sql
+SELECT /*+ EARLY_FIRE('delay'='5s') */ o.id, s.ship_time
+FROM Orders o
+LEFT OUTER JOIN Shipments s
+ON o.id = s.order_id
+AND o.order_time BETWEEN s.ship_time - INTERVAL '1' HOUR AND s.ship_time
+```
+
+当某个订单还没有对应的发货记录时，在 `delay` 时间过去后，join 会输出一次 `+I[id,
NULL]`，而不必等到该订单一小时的窗口关闭。如果之后在窗口内到达了一条匹配的发货记录，则该推测行会先被 `-U[id, NULL]` 撤回，再以
`+U[id, ship_time]` 更正。每个 outer 行至多触发一次；该提示不会周期性地输出。
+
+该提示支持以下选项：
+
+| 选项 | 是否必填 | 描述 |
+| --- | --- | --- |
+| `target` | 否 | 该提示所作用的算子类型。目前仅支持 `interval_join`，其他取值会报错。省略时，该提示作用于 interval
join。 |
+| `delay` | 是 | 一个至少为 1 毫秒的时间长度（例如 `'5s'`）。在 `rowtime` 模式下从行的时间属性开始计算；在
`proctime` 模式下从该行被处理时的墙上时钟时间开始计算。窗口内没有匹配时，在该延迟过去后输出推测性的 null 补齐行。 |
+| `time-mode` | 否 | 取值为 `rowtime` 或
`proctime`，用于控制延迟是相对水位线（`rowtime`）还是相对墙上时钟（`proctime`）来计算。事件时间 join 默认为
`rowtime`，处理时间 join 默认为 `proctime`。在事件时间 join 上设置 `'time-mode'='proctime'`
会改为按墙上时钟触发提前触发，适用于水位线稀疏或停滞的场景；匹配和状态清理仍按事件时间进行，并且 join
会在每一侧输入上额外维护状态，用于记录待触发的提前触发。在处理时间 join 上设置 `'time-mode'='rowtime'` 会报错。 |
+
+该提示仅对 outer join（`LEFT`、`RIGHT`、`FULL`）生效。在 inner join 以及窗口跨度为负的 join
上会被忽略，这些情况仍保持仅追加。
+
+**注意：** `EARLY_FIRE` 与 `table.exec.emit.early-fire.*` 配置无关，后者用于控制窗口聚合的提前触发，而非
interval join。
+
Temporal Joins
--------------
diff --git a/docs/content/docs/sql/reference/queries/joins.md
b/docs/content/docs/sql/reference/queries/joins.md
index 2a5a4b07182..761fa0cb16e 100644
--- a/docs/content/docs/sql/reference/queries/joins.md
+++ b/docs/content/docs/sql/reference/queries/joins.md
@@ -109,6 +109,32 @@ The following predicates are examples of valid interval
join conditions:
For streaming queries, compared to the regular join, interval join only
supports append-only tables with time attributes.
Since time attributes are quasi-monotonic increasing, Flink can remove old
values from its state without affecting the correctness of the result.
+### Early Fire for Outer Interval Joins
+
+By default an outer interval join waits for the time window of an unmatched
row to fully close before emitting that row null-padded. The `EARLY_FIRE` hint
shortens this wait: an unmatched outer row is emitted speculatively with a
null-padded counterpart after a configurable `delay`, and corrected later if a
real match arrives within the window. This trades the append-only result for an
updating one, so the downstream sink must accept updates.
+
+```sql
+SELECT /*+ EARLY_FIRE('delay'='5s') */ o.id, s.ship_time
+FROM Orders o
+LEFT OUTER JOIN Shipments s
+ON o.id = s.order_id
+AND o.order_time BETWEEN s.ship_time - INTERVAL '1' HOUR AND s.ship_time
+```
+
+When an order has no shipment yet, the join emits `+I[id, NULL]` once the
`delay` has elapsed, instead of waiting for the order's one-hour window to
close. If a matching shipment later arrives inside the window, the speculative
row is corrected with `-U[id, NULL]` followed by `+U[id, ship_time]`. Each
outer row fires at most once; the hint does not emit periodically.
+
+The hint accepts the following options:
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `target` | no | The operator kind the hint applies to. Currently only
`interval_join` is supported; any other value is an error. When omitted, the
hint applies to the interval join. |
+| `delay` | yes | A duration of at least 1 millisecond (for example `'5s'`).
In `rowtime` mode it is measured from the row's time attribute; in `proctime`
mode it is measured from the wall-clock time at which the row is processed. The
speculative null-padded row is emitted once this delay elapses without a match.
|
+| `time-mode` | no | Either `rowtime` or `proctime`. Controls whether the
delay is measured against the watermark (`rowtime`) or wall-clock time
(`proctime`). Defaults to `rowtime` for an event-time join and `proctime` for a
processing-time join. Setting `'time-mode'='proctime'` on an event-time join
triggers early fire on wall-clock time instead of the watermark, which helps
when watermarks are sparse or stalled; matching and state cleanup still follow
event time, and the join keeps ext [...]
+
+The hint only affects outer joins (`LEFT`, `RIGHT`, `FULL`). It is ignored on
inner joins and on joins whose window has a negative span, both of which remain
append-only.
+
+**Note:** `EARLY_FIRE` is unrelated to the `table.exec.emit.early-fire.*`
configuration, which controls early firing for windowed aggregations rather
than interval joins.
+
Temporal Joins
--------------
