From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 14 Jan 2026 18:43:26 +0000 (-0500)
Subject: add additional clarification re: table valued for SQLite vs. PostgreSQL
X-Git-Tag: rel_2_0_46~4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f3560ad2e0179f8c6810e31fe1a4dea5633b5d70;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

add additional clarification re: table valued for SQLite vs. PostgreSQL

Fixes: #13079
Change-Id: I4e96709712a3f365e75b134dadc3bd24fb0cc053
(cherry picked from commit 63885906e8a5f6ad479e591e4f5716b486ef1df6)
---

diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py
index f30b686add..663ced0e43 100644
--- a/lib/sqlalchemy/sql/functions.py
+++ b/lib/sqlalchemy/sql/functions.py
@@ -241,7 +241,8 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative):
         r"""Return a :class:`_sql.TableValuedAlias` representation of this
         :class:`_functions.FunctionElement` with table-valued expressions added.
 
-        e.g.:
+        e.g. to use the SQLite form of ``generate_series()`` (including
+        hidden columns "start", "stop", "step"):
 
         .. sourcecode:: pycon+sql
 
@@ -258,17 +259,33 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative):
             FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1
             WHERE anon_1.value > :value_1{stop}
 
+        Backends like PostgreSQL need the accessed columns to be explicitly
+        named in "AS" clause.  To achieve this, use
+        :meth:`_sql.TableValuedAlias.render_derived`; be sure to consult the
+        :ref:`PostgreSQL-specific documentation for table valued functions
+        <postgresql_table_valued>` for additional examples:
+
+        .. sourcecode:: pycon+sql
+
+            >>> fn = func.generate_series(1, 5).table_valued("value").render_derived()
+
+            >>> print(select(fn))
+            {printsql}SELECT anon_1.value FROM
+            generate_series(:generate_series_1, :generate_series_2) AS anon_1(value){stop}
+
         A WITH ORDINALITY expression may be generated by passing the keyword
-        argument "with_ordinality":
+        argument :paramref:`.FunctionElement.table_valued.with_ordinality`,
+        illustrated below using PostgreSQL's syntax:
 
         .. sourcecode:: pycon+sql
 
             >>> fn = func.generate_series(4, 1, -1).table_valued(
             ...     "gen", with_ordinality="ordinality"
             ... )
-            >>> print(select(fn))
+            >>> print(select(fn.render_derived()))
             {printsql}SELECT anon_1.gen, anon_1.ordinality
-            FROM generate_series(:generate_series_1, :generate_series_2, :generate_series_3) WITH ORDINALITY AS anon_1
+            FROM generate_series(:generate_series_1, :generate_series_2, :generate_series_3)
+            WITH ORDINALITY AS anon_1(gen, ordinality)
 
         :param \*expr: A series of string column names that will be added to the
          ``.c`` collection of the resulting :class:`_sql.TableValuedAlias`
@@ -297,7 +314,7 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative):
 
             :ref:`tutorial_functions_table_valued` - in the :ref:`unified_tutorial`
 
-            :ref:`postgresql_table_valued` - in the :ref:`postgresql_toplevel` documentation
+            :ref:`Table-Valued Functions on PostgreSQL <postgresql_table_valued>` - in the :ref:`postgresql_toplevel` documentation
 
             :meth:`_functions.FunctionElement.scalar_table_valued` - variant of
             :meth:`_functions.FunctionElement.table_valued` which delivers the