From ce8684a3b4cec3d9f914644927bf8063fc94e096 Mon Sep 17 00:00:00 2001
From: prql-bot <107324867+prql-bot@users.noreply.github.com>
Date: Mon, 31 Jul 2023 12:01:19 -0700
Subject: [PATCH] chore: Backport #3190 to `web` (#3194)

Co-authored-by: Maximilian Roos <5635139+max-sixty@users.noreply.github.com>
---
 .../src/reference/stdlib/transforms/join.md   | 21 ++++++++++++++-----
 web/book/src/reference/syntax/keywords.md     |  3 ++-
 ...stdlib__transforms__join__examples__3.snap | 11 ++++++++++
 3 files changed, 29 insertions(+), 6 deletions(-)
 create mode 100644 web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__transforms__join__examples__3.snap

diff --git a/web/book/src/reference/stdlib/transforms/join.md b/web/book/src/reference/stdlib/transforms/join.md
index c2e6c99f8f7a..6d8c2cc9f8de 100644
--- a/web/book/src/reference/stdlib/transforms/join.md
+++ b/web/book/src/reference/stdlib/transforms/join.md
@@ -9,11 +9,12 @@ join side:{inner|left|right|full} table (condition)
 ## Parameters
 
 - `side` specifies which rows to include, defaulting to `inner`.
-- _table_ - a reference to a relation, possibly including an assignment, e.g.
-  `var= ...`
+- _table_ - a reference to a relation, possibly including an alias, e.g.
+  `a=artists`
 - _condition_ - a boolean condition
-  - If the condition evaluates to True, the rows will be joined
-  - If name is the same from both tables, it can be expressed with only `==col`.
+  - If the condition evaluates to true for a given row, the row will be joined
+  - If name is the same from both tables, it can be expressed with only
+    `(==col)`.
 
 ## Examples
 
@@ -30,8 +31,18 @@ join side:left p=positions (employees.id==p.employee_id)
 ```prql
 from tracks
 join side:left artists (
+  # This adds a `country` condition, as an alternative to filtering
   artists.id==tracks.artist_id && artists.country=='UK'
-  # As an alternative to filtering
+)
+```
+
+[`this` & `that`](../../syntax/keywords.md#this--that) can be used to refer to
+the current & other table respectively:
+
+```prql
+from tracks
+join side:inner artists (
+  this.id==that.artist_id
 )
 ```
 
diff --git a/web/book/src/reference/syntax/keywords.md b/web/book/src/reference/syntax/keywords.md
index 57c796025ac0..7c13a9eda2c0 100644
--- a/web/book/src/reference/syntax/keywords.md
+++ b/web/book/src/reference/syntax/keywords.md
@@ -23,7 +23,8 @@ aggregate (
 )
 ```
 
-Within a `join`, `that` refers to the other table:
+Within a [`join`](../stdlib/transforms/join.md), `that` refers to the other
+table:
 
 ```prql
 from invoices
diff --git a/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__transforms__join__examples__3.snap b/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__transforms__join__examples__3.snap
new file mode 100644
index 000000000000..4f98b7e6b369
--- /dev/null
+++ b/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__transforms__join__examples__3.snap
@@ -0,0 +1,11 @@
+---
+source: web/book/tests/documentation/book.rs
+expression: "from tracks\njoin side:inner artists (\n  this.id==that.artist_id\n)\n"
+---
+SELECT
+  tracks.*,
+  artists.*
+FROM
+  tracks
+  JOIN artists ON tracks.id = artists.artist_id
+