Method table_valued

lib/sqlalchemy/sql/functions.py:247–351

r"""Return a :class:`_sql.TableValuedAlias` representation of this :class:`_functions.FunctionElement` with table-valued expressions added. e.g. to use the SQLite form of ``generate_series()`` (including hidden columns "start", "stop", "step"): .. sourcecode:: pycon

(
        self, *expr: _ColumnExpressionOrStrLabelArgument[Any], **kw: Any
    )

        return ScalarFunctionColumn(self, name, type_)

    def table_valued(
        self, *expr: _ColumnExpressionOrStrLabelArgument[Any], **kw: Any
    ) -> TableValuedAlias:
        r"""Return a :class:`_sql.TableValuedAlias` representation of this
        :class:`_functions.FunctionElement` with table-valued expressions added.

        e.g. to use the SQLite form of ``generate_series()`` (including
        hidden columns "start", "stop", "step"):

        .. sourcecode:: pycon+sql

            >>> fn = func.generate_series(1, 5).table_valued(
            ...     "value", "start", "stop", "step"
            ... )

            >>> print(select(fn))
            {printsql}SELECT anon_1.value, anon_1.start, anon_1.stop, anon_1.step
            FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1{stop}

            >>> print(select(fn.c.value, fn.c.stop).where(fn.c.value > 2))
            {printsql}SELECT anon_1.value, anon_1.stop
            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 :paramref:`.FunctionElement.table_valued.with_ordinality`,
        illustrated below using PostgreSQL&#x27;s syntax:

        .. sourcecode:: pycon+sql

            >>> fn = func.generate_series(4, 1, -1).table_valued(
            ...     "gen", with_ordinality="ordinality"
            ... )
            >>> 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(gen, ordinality)

        :param \*expr: A series of string column names that will be added to the
         ``.c`` collection of the resulting :class:`_sql.TableValuedAlias`
         construct as columns.  :func:`_sql.column` objects with or without
         datatypes may also be used.

        :param name: optional name to assign to the alias name that&#x27;s generated.