fhueske commented on code in PR #28737:
URL: https://github.com/apache/flink/pull/28737#discussion_r3596867160
##########
docs/content.zh/docs/sql/reference/queries/joins.md:
##########
@@ -295,6 +295,74 @@ WHERE
- SQL 中可以定义 temporal table DDL，但不能定义 temporal table 函数;
- temporal table DDL 和 temporal table function 都支持 temporal join 版本表，但只有
temporal table function 可以 temporal join 任何表/视图的最新版本（即"处理时间 Temporal Join"）。
+LATERAL SNAPSHOT Join
+--------------
+
+{{< label Streaming >}}
+
+A `LATERAL SNAPSHOT` join is a *stream enrichment* join that augments an
append-only table (the *probe* side) with the current state of an updating
table (the *build* side).
+Unlike an [event-time temporal join](#event-time-temporal-join), it does not
correlate each probe-side row with a specific historical version of the build
side.
+Instead, every probe-side row is joined with the build-side state that is
current at the time the row is processed, similar to a [processing-time
temporal join](#processing-time-temporal-join), but with well-defined behavior
at query start-up.
+
+The `LATERAL SNAPSHOT` join is designed for scenarios where the other temporal
joins are a poor fit:
+
+- The build side updates **infrequently**. An event-time temporal join relies
on continuous build-side watermarks to emit results, so a build side that
rarely advances its watermark stalls the join and lets probe-side state
accumulate. A `LATERAL SNAPSHOT` join does not stall when the build side goes
idle.
+- The application has **low-latency** requirements that are incompatible with
the watermark-induced delay of an event-time temporal join.
+- The build side has **no primary key**. Event-time and processing-time
temporal joins require the build-side primary key to appear in the equi-join
condition; a `LATERAL SNAPSHOT` join does not.
+
+The build side is wrapped in the `SNAPSHOT` table function inside a `LATERAL
TABLE` clause. Both `INNER JOIN` and `LEFT [OUTER] JOIN` are supported. The
join requires at least one conjunctive equality predicate; additional non-equi
predicates are allowed in the `ON` clause.
+
+```sql
+SELECT [column_list]
+FROM probe_table
+[LEFT] JOIN LATERAL TABLE(
+ SNAPSHOT(
+ input => TABLE build_table,
+ [ load_completed_condition => <'compile_time' | 'user_time'>, ]
+ [ load_completed_time => <timestamp_ltz>, ]
+ [ load_completed_idle_timeout => <interval>, ]
+ [ state_ttl => <interval> ])) AS s
+ON probe_table.key = s.key
+```
+
+The `SNAPSHOT` function accepts the following arguments:
+
+| Argument | Type | Required | Description |
+| --- | --- | --- | --- |
+| `input` | TABLE | yes | The build-side table. It may use any [changelog
mode]({{< ref "docs/sql/reference/queries/changelog" >}}) (inserts, updates,
and deletes) and must declare a [watermark]({{< ref
"docs/concepts/sql-table-concepts/time_attributes" >}}#event-time). |
+| `load_completed_condition` | STRING | no | Determines when the initial load
phase completes. One of `'compile_time'` (default) or `'user_time'`. With
`'compile_time'`, the load phase completes once the build-side watermark
reaches the wall-clock time at which the query was compiled. With
`'user_time'`, it completes once the build-side watermark reaches the explicit
`load_completed_time`. |
Review Comment:
Do you mean a nested table in the arguments table?
Not sure how well this is supported by the docs framework.
TBH, I also don't know what else to add to the description of both
conditions. `compile_time` is just sets the `load_completed_time` to the
current system time, while `user_time` requires users to explicitly set it.
But I noticed that the table discusses about LOAD phase before it had been
discussed.
So, I'll move the paragraph about the internals of the join up above the
syntax.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
