Skip to content

Commit 4489465

Browse files
authored
Doc non-append-only process-time temporal join (#2136)
* Update query-syntax-join-clause.md * Update query-syntax-join-clause.md
1 parent fa6c42f commit 4489465

File tree

1 file changed

+42
-6
lines changed

1 file changed

+42
-6
lines changed

docs/sql/query-syntax/query-syntax-join-clause.md

+42-6
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ ON s1.id = s2.id and s1.window_start = s2.window_start;
112112

113113
## Interval joins
114114

115-
Window joins require that the two sources have the same window type and window size. This requirement can be too strict in some scenarios. If you want to join two sources that have some time offset, you can create an interval join by specifying an accepted internval range based on watermarks.
115+
Window joins require that the two sources have the same window type and window size. This requirement can be too strict in some scenarios. If you want to join two sources that have some time offset, you can create an interval join by specifying an accepted interval range based on watermarks.
116116

117117
The syntax of an interval join is:
118118

@@ -136,23 +136,27 @@ ON s1.id = s2.id and s1.ts between s2.ts and s2.ts + INTERVAL '1' MINUTE;
136136

137137
## Process-time temporal joins
138138

139-
A temporal join is often used to widen a fact table. Its advantage is that it does not require RisingWave to maintain the join state, making it suitable for scenarios where the dimension table is not updated, or where updates to the dimension table do not affect the previously joined results. To further improve performance, you can use the index of a dimension table to form a join with the fact table.
139+
Process-time temporal joins are divided into two categories: append-only process-time temporal join and non-append-only process-time temporal join. Check the following instructions for their differences.
140140

141-
### Syntax
141+
### Append-only process-time temporal join
142+
143+
An append-only temporal join is often used to widen a fact table. Its advantage is that it does not require RisingWave to maintain the join state, making it suitable for scenarios where the dimension table is not updated, or where updates to the dimension table do not affect the previously joined results. To further improve performance, you can use the index of a dimension table to form a join with the fact table.
144+
145+
#### Syntax
142146

143147
```sql
144148
<table_expression> [ LEFT | INNER ] JOIN <table_expression> FOR SYSTEM_TIME AS OF PROCTIME() ON <join_conditions>;
145149
```
146150

147-
### Notes
151+
#### Notes
148152

149153
- The left table expression is an append-only table or source.
150154
- The right table expression is a table, index or materialized view.
151155
- The process-time syntax `FOR SYSTEM_TIME AS OF PROCTIME()` is included in the right table expression.
152156
- The join type is INNER JOIN or LEFT JOIN.
153157
- The Join condition includes the primary key of the right table expression.
154158

155-
### Example
159+
#### Example
156160

157161
If you have an append-only stream that includes messages like below:
158162

@@ -179,11 +183,43 @@ You can use a temporal join to fetch the latest product name and price from the
179183
SELECT transaction_id, product_id, quantity, sale_date, product_name, price
180184
FROM sales
181185
JOIN products FOR SYSTEM_TIME AS OF PROCTIME()
182-
ON product_id = id
186+
ON product_id = id WHERE process_time BETWEEN valid_from AND valid_to;
183187
```
184188

185189
| transaction_id | product_id | quantity | sale_date | product_name | price |
186190
|----------------|------------|----------|------------|--------------|-------|
187191
| 1 | 101 | 3 | 2023-06-18 | Product A | 25 |
188192
| 2 | 102 | 2 | 2023-06-19 | Product B | 15 |
189193
| 3 | 101 | 1 | 2023-06-20 | Product A | 22 |
194+
195+
### Non-append-only process-time temporal join
196+
197+
Compared to the append-only temporal join, the non-append-only temporal join can accommodate non-append-only input for the left table. However, it introduces an internal state to materialize the lookup result for each left-hand side (LHS) insertion. This allows the temporal join operator to retract the join result it sends downstream when update or delete messages arrive.
198+
199+
#### Syntax
200+
201+
The non-append-only temporal join shares the same syntax as the append-only temporal join.
202+
203+
```sql
204+
<table_expression> [ LEFT | INNER ] JOIN <table_expression> FOR SYSTEM_TIME AS OF PROCTIME() ON <join_conditions>;
205+
```
206+
207+
#### Example
208+
209+
Now if you update the table `sales`:
210+
211+
```sql
212+
UPDATE sales SET quantity = quantity + 1;
213+
```
214+
215+
You will get these results:
216+
217+
| transaction_id | product_id | quantity | sale_date | product_name | price |
218+
| --- | --- | --- | --- | --- | --- |
219+
| 1 | 101 | 4 | 2023-06-18 | Product A | 25 |
220+
| 2 | 102 | 3 | 2023-06-19 | Product B | 15 |
221+
| 3 | 101 | 2 | 2023-06-20 | Product A | 22 |
222+
223+
:::note
224+
Every time you update the left-hand side table, it will look up the latest data from the right-hand side table.
225+
:::

0 commit comments

Comments
 (0)