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

Fixes: #13079
Change-Id: I4e96709712a3f365e75b134dadc3bd24fb0cc053

diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py
index d5a9e362f79adafdc7ea3c2d69b4b034f374b399..da21d9a73515f890ca9c015ddd6c5339a39fca41 100644 (file)
--- a/lib/sqlalchemy/sql/functions.py
+++ b/lib/sqlalchemy/sql/functions.py
@@ -248,7 +248,8 @@ class FunctionElement(
         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
 
@@ -265,17 +266,33 @@ class FunctionElement(
             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`
@@ -304,7 +321,7 @@ class FunctionElement(
 
             :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