Method columns

lib/sqlalchemy/sql/elements.py:2460–2602

r"""Turn this :class:`_expression.TextClause` object into a :class:`_expression.TextualSelect` object that serves the same role as a SELECT statement. The :class:`_expression.TextualSelect` is part of the :class:`_expression.SelectBase` hierarchy and

(
        self,
        *cols: _OnlyColumnArgument[Any],
        **types: _TypeEngineArgument[Any],
    )

    @util.preload_module("sqlalchemy.sql.selectable")
    def columns(
        self,
        *cols: _OnlyColumnArgument[Any],
        **types: _TypeEngineArgument[Any],
    ) -> TextualSelect:
        r"""Turn this :class:`_expression.TextClause` object into a
        :class:`_expression.TextualSelect`
        object that serves the same role as a SELECT
        statement.

        The :class:`_expression.TextualSelect` is part of the
        :class:`_expression.SelectBase`
        hierarchy and can be embedded into another statement by using the
        :meth:`_expression.TextualSelect.subquery` method to produce a
        :class:`.Subquery`
        object, which can then be SELECTed from.

        This function essentially bridges the gap between an entirely
        textual SELECT statement and the SQL expression language concept
        of a "selectable"::

            from sqlalchemy.sql import column, text

            stmt = text("SELECT id, name FROM some_table")
            stmt = stmt.columns(column("id"), column("name")).subquery("st")

            stmt = (
                select(mytable)
                .select_from(mytable.join(stmt, mytable.c.name == stmt.c.name))
                .where(stmt.c.id > 5)
            )

        Above, we pass a series of :func:`_expression.column` elements to the
        :meth:`_expression.TextClause.columns` method positionally.  These
        :func:`_expression.column`
        elements now become first class elements upon the
        :attr:`_expression.TextualSelect.selected_columns` column collection,
        which then
        become part of the :attr:`.Subquery.c` collection after
        :meth:`_expression.TextualSelect.subquery` is invoked.

        The column expressions we pass to
        :meth:`_expression.TextClause.columns` may
        also be typed; when we do so, these :class:`.TypeEngine` objects become
        the effective return type of the column, so that SQLAlchemy's
        result-set-processing systems may be used on the return values.
        This is often needed for types such as date or boolean types, as well
        as for unicode processing on some dialect configurations::

            stmt = text("SELECT id, name, timestamp FROM some_table")
            stmt = stmt.columns(
                column("id", Integer),
                column("name", Unicode),
                column("timestamp", DateTime),
            )

            for id, name, timestamp in connection.execute(stmt):
                print(id, name, timestamp)