Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc non-append-only process-time temporal join #2136

Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 42 additions & 6 deletions docs/sql/query-syntax/query-syntax-join-clause.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ ON s1.id = s2.id and s1.window_start = s2.window_start;

## Interval joins

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.
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.

The syntax of an interval join is:

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

## Process-time temporal joins

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.
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.

### Syntax
### Append-only process-time temporal join

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.

#### Syntax

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

### Notes
#### Notes

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

### Example
#### Example

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

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

| transaction_id | product_id | quantity | sale_date | product_name | price |
|----------------|------------|----------|------------|--------------|-------|
| 1 | 101 | 3 | 2023-06-18 | Product A | 25 |
| 2 | 102 | 2 | 2023-06-19 | Product B | 15 |
| 3 | 101 | 1 | 2023-06-20 | Product A | 22 |

### Non-append-only process-time temporal join

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.

#### Syntax

The non-append-only temporal join shares the same syntax as the append-only temporal join.

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

#### Example

Now if you update the table `sales`:

```sql
UPDATE sales SET quantity = quantity + 1;
```

You will get these results:

| transaction_id | product_id | quantity | sale_date | product_name | price |
| --- | --- | --- | --- | --- | --- |
| 1 | 101 | 4 | 2023-06-18 | Product A | 25 |
| 2 | 102 | 3 | 2023-06-19 | Product B | 15 |
| 3 | 101 | 2 | 2023-06-20 | Product A | 22 |

:::note
Every time you update the left-hand side table, it will look up the latest data from the right-hand side table.
:::
Loading