From ba215ed2bb1a588c091db727dff88a395b584784 Mon Sep 17 00:00:00 2001
From: prql-bot <107324867+prql-bot@users.noreply.github.com>
Date: Thu, 27 Jul 2023 12:10:31 -0700
Subject: [PATCH] chore: Backport #3137 to `web` (#3138)

Co-authored-by: Maximilian Roos <5635139+max-sixty@users.noreply.github.com>
---
 web/book/src/reference/stdlib/transforms/join.md | 16 +++++++++++-----
 ...e__stdlib__transforms__join__examples__2.snap | 12 ++++++++++++
 2 files changed, 23 insertions(+), 5 deletions(-)
 create mode 100644 web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__transforms__join__examples__2.snap

diff --git a/web/book/src/reference/stdlib/transforms/join.md b/web/book/src/reference/stdlib/transforms/join.md
index 9dd5a6febf11..12dbdd5cfbee 100644
--- a/web/book/src/reference/stdlib/transforms/join.md
+++ b/web/book/src/reference/stdlib/transforms/join.md
@@ -3,16 +3,14 @@
 Adds columns from another table, matching rows based on a condition.
 
 ```prql no-eval
-join side:{inner|left|right|full} table (conditions)
+join side:{inner|left|right|full} table (condition)
 ```
 
 ## Parameters
 
 - `side` decides which rows to include, defaulting to `inner`.
-- Table reference
-- List of conditions
-  - The result of join operation is a cartesian (cross) product of rows from
-    both tables, which is then filtered to match all of these conditions.
+- Relation reference
+- A condition
   - If name is the same from both tables, it can be expressed with only `==col`.
 
 ## Examples
@@ -27,6 +25,14 @@ from employees
 join side:left p=positions (employees.id==p.employee_id)
 ```
 
+```prql
+from tracks
+join side:left artists (
+  artists.id==tracks.artist_id && artists.country=='UK'
+  # As an alternative to filtering
+)
+```
+
 ## Self equality operator
 
 If the join conditions are of form `left.x == right.x`, we can use "self
diff --git a/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__transforms__join__examples__2.snap b/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__transforms__join__examples__2.snap
new file mode 100644
index 000000000000..95a3480d4135
--- /dev/null
+++ b/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__transforms__join__examples__2.snap
@@ -0,0 +1,12 @@
+---
+source: web/book/tests/documentation/book.rs
+expression: "from tracks\njoin side:left artists (\n  artists.id==tracks.artist_id && artists.country=='UK'\n  # As an alternative to filtering\n)\n"
+---
+SELECT
+  tracks.*,
+  artists.*
+FROM
+  tracks
+  LEFT JOIN artists ON artists.id = tracks.artist_id
+  AND artists.country = 'UK'
+