Module « sqlalchemy »

Fonction text - module sqlalchemy

Signature de la fonction text

def text(text, bind=None) 

Description

text.__doc__

Construct a new :class:`_expression.TextClause` clause,
        representing
        a textual SQL string directly.

        E.g.::

            from sqlalchemy import text

            t = text("SELECT * FROM users")
            result = connection.execute(t)

        The advantages :func:`_expression.text`
        provides over a plain string are
        backend-neutral support for bind parameters, per-statement
        execution options, as well as
        bind parameter and result-column typing behavior, allowing
        SQLAlchemy type constructs to play a role when executing
        a statement that is specified literally.  The construct can also
        be provided with a ``.c`` collection of column elements, allowing
        it to be embedded in other SQL expression constructs as a subquery.

        Bind parameters are specified by name, using the format ``:name``.
        E.g.::

            t = text("SELECT * FROM users WHERE id=:user_id")
            result = connection.execute(t, user_id=12)

        For SQL statements where a colon is required verbatim, as within
        an inline string, use a backslash to escape::

            t = text("SELECT * FROM users WHERE name='\:username'")

        The :class:`_expression.TextClause`
        construct includes methods which can
        provide information about the bound parameters as well as the column
        values which would be returned from the textual statement, assuming
        it's an executable SELECT type of statement.  The
        :meth:`_expression.TextClause.bindparams`
        method is used to provide bound
        parameter detail, and :meth:`_expression.TextClause.columns`
        method allows
        specification of return columns including names and types::

            t = text("SELECT * FROM users WHERE id=:user_id").\
                    bindparams(user_id=7).\
                    columns(id=Integer, name=String)

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

        The :func:`_expression.text` construct is used in cases when
        a literal string SQL fragment is specified as part of a larger query,
        such as for the WHERE clause of a SELECT statement::

            s = select(users.c.id, users.c.name).where(text("id=:user_id"))
            result = connection.execute(s, user_id=12)

        :func:`_expression.text` is also used for the construction
        of a full, standalone statement using plain text.
        As such, SQLAlchemy refers
        to it as an :class:`.Executable` object, and it supports
        the :meth:`Executable.execution_options` method.  For example,
        a :func:`_expression.text`
        construct that should be subject to "autocommit"
        can be set explicitly so using the
        :paramref:`.Connection.execution_options.autocommit` option::

            t = text("EXEC my_procedural_thing()").\
                    execution_options(autocommit=True)

        .. deprecated:: 1.4  The "autocommit" execution option is deprecated
           and will be removed in SQLAlchemy 2.0.  See
           :ref:`migration_20_autocommit` for discussion.

        :param text:
          the text of the SQL statement to be created.  Use ``:<param>``
          to specify bind parameters; they will be compiled to their
          engine-specific format.

          .. warning:: The :paramref:`.text.text` argument to :func:`.text` can be passed as a Python string argument, which will be treated as **trusted SQL text** and rendered as given.  **DO NOT PASS UNTRUSTED INPUT TO THIS PARAMETER**.



        :param bind:
          an optional connection or engine to be used for this text query.

          .. deprecated:: 1.4 The :paramref:`_sql.text.bind` argument is deprecated and will be removed in SQLAlchemy 2.0.



        .. seealso::

            :ref:`sqlexpression_text` - in the Core tutorial