ensure intro to "functions have types" is not misleading

zzzeek · zzzeek · commit e9d3e49601d0 · 2024-07-06T12:24:51.000-04:00
make sure it's clear that there is normally not a return type for SQL functions Fixes: sqlalchemy#11578 Change-Id: Ia0b66e7fe685dad427822345dd232eb47a0fc44f
diff --git a/doc/build/tutorial/data_select.rst b/doc/build/tutorial/data_select.rst
@@ -1410,11 +1410,18 @@ as opposed to the "return type" of a Python function.
 
 The SQL return type of any SQL function may be accessed, typically for
 debugging purposes, by referring to the :attr:`_functions.Function.type`
-attribute::
+attribute; this will be pre-configured for a **select few** of extremely
+common SQL functions, but for most SQL functions is the "null" datatype
+if not otherwise specified::
 
+    >>> # pre-configured SQL function (only a few dozen of these)
     >>> func.now().type
     DateTime()
 
+    >>> # arbitrary SQL function (all other SQL functions)
+    >>> func.run_some_calculation().type
+    NullType()
+
 These SQL return types are significant when making
 use of the function expression in the context of a larger expression; that is,
 math operators will work better when the datatype of the expression is
