From c1463815161793654bd7d40d54564a0b1940af5c Mon Sep 17 00:00:00 2001
From: Nick Crews <nicholas.b.crews@gmail.com>
Date: Wed, 4 Oct 2023 11:05:23 -0800
Subject: [PATCH] docs: add examples to Value.typeof()

---
 ibis/expr/types/generic.py | 40 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/ibis/expr/types/generic.py b/ibis/expr/types/generic.py
index e76788ab924c..2d95837f151d 100644
--- a/ibis/expr/types/generic.py
+++ b/ibis/expr/types/generic.py
@@ -310,14 +310,52 @@ def least(self, *args: ir.Value) -> ir.Value:
         return ops.Least((self, *args)).to_expr()
 
     def typeof(self) -> ir.StringValue:
-        """Return the data type of the expression.
+        """Return the string name of the datatype of self.
 
         The values of the returned strings are necessarily backend dependent.
+        e.g. duckdb may say "DOUBLE", while sqlite may say "real".
 
         Returns
         -------
         StringValue
             A string indicating the type of the value
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> vals = ibis.examples.penguins.fetch().head(5).bill_length_mm
+        >>> vals
+        ┏━━━━━━━━━━━━━━━━┓
+        ┃ bill_length_mm ┃
+        ┡━━━━━━━━━━━━━━━━┩
+        │ float64        │
+        ├────────────────┤
+        │           39.1 │
+        │           39.5 │
+        │           40.3 │
+        │            nan │
+        │           36.7 │
+        └────────────────┘
+        >>> vals.typeof()
+        ┏━━━━━━━━━━━━━━━━━━━━━━━━┓
+        ┃ TypeOf(bill_length_mm) ┃
+        ┡━━━━━━━━━━━━━━━━━━━━━━━━┩
+        │ string                 │
+        ├────────────────────────┤
+        │ DOUBLE                 │
+        │ DOUBLE                 │
+        │ DOUBLE                 │
+        │ DOUBLE                 │
+        │ DOUBLE                 │
+        └────────────────────────┘
+
+        Different backends have different names for their native types
+
+        >>> ibis.duckdb.connect().execute(ibis.literal(5.4).typeof())
+        'DOUBLE'
+        >>> ibis.sqlite.connect().execute(ibis.literal(5.4).typeof())
+        'real'
         """
         return ops.TypeOf(self).to_expr()