From f4b67e5225fa036a7ca22ea4055545db34365eb8 Mon Sep 17 00:00:00 2001
From: Gil Forsyth <gil@forsyth.dev>
Date: Fri, 26 Jan 2024 17:11:55 -0500
Subject: [PATCH] docs(random): document behavior of repeated use of
 ibis.random() instance

---
 ibis/expr/api.py | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/ibis/expr/api.py b/ibis/expr/api.py
index 5b3ebd14b14b..56ee85d1c005 100644
--- a/ibis/expr/api.py
+++ b/ibis/expr/api.py
@@ -648,6 +648,35 @@ def random() -> ir.FloatingScalar:
 
     Similar to [](`random.random`) in the Python standard library.
 
+    ::: {.callout-note}
+    ## Repeated use of `random`
+
+    `ibis.random()` will generate a column of distinct random numbers even if
+    the same instance of `ibis.random()` is re-used.
+
+    When Ibis compiles an expression to SQL, each place where `random` is used
+    will render as a separate call to the given backend's random number
+    generator.
+
+    ```python
+    >>> from ibis.interactive import *
+    >>> t = ibis.memtable({"a": range(5)})
+    >>> r_a = ibis.random()
+    >>> t.mutate(random_1=r_a, random_2=r_a)  # doctest: +SKIP
+    ┏━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓
+    ┃ a     ┃ random_1 ┃ random_2 ┃
+    ┡━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩
+    │ int64 │ float64  │ float64  │
+    ├───────┼──────────┼──────────┤
+    │     0 │ 0.191130 │ 0.098715 │
+    │     1 │ 0.255262 │ 0.828454 │
+    │     2 │ 0.011804 │ 0.392275 │
+    │     3 │ 0.309941 │ 0.347300 │
+    │     4 │ 0.482783 │ 0.095562 │
+    └───────┴──────────┴──────────┘
+    ```
+    :::
+
     Returns
     -------
     FloatingScalar