- add an example of text.columns

- correct the scalar() example output

1 files changed, 19 insertions, 4 deletions

diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index e3ce6adad..2f904d828 100644
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -902,10 +902,9 @@ database results.  Here's a brief tour:
       {sql}>>> query.scalar() #doctest: +NORMALIZE_WHITESPACE
       SELECT users.id AS users_id
       FROM users
-      WHERE users.name LIKE ? ORDER BY users.id
-       LIMIT ? OFFSET ?
-      ('%ed', 1, 0)
-      {stop}7
+      WHERE users.name = ? ORDER BY users.id
+      ('ed',)
+      {stop}1
 
 .. _orm_tutorial_literal_sql:
 
@@ -982,11 +981,27 @@ completely "raw", using string names to identify desired columns:
     ('ed',)
     {stop}[(1, u'ed', 12)]
 
+The :func:`.text` construct also supports the :meth:`.TextClause.columns`
+method, which can be used to associate ORM-mapped columns explicitly.
+This is useful to make an explicit mapping of columns in the string
+statement to those that are mapped::
+
+.. sourcecode:: python+sql
+
+    >>> stmt = text("SELECT name, id FROM users where name=:name")
+    >>> stmt = stmt.columns(User.name, User.id)
+    {sql}>>> session.query(User).from_statement(stmt).params(name='ed').all()
+    SELECT name, id FROM users where name=?
+    ('ed',)
+    {stop}[<User(name='ed', fullname='Ed Jones', password='f8s7ccs')>]
+
+
 .. versionchanged:: 1.0.0
    The :class:`.Query` construct emits warnings when string SQL
    fragments are coerced to :func:`.text`, and :func:`.text` should
    be used explicitly.  See :ref:`migration_2992` for background.
 
+
 .. seealso::
 
     :ref:`sqlexpression_text` - Core description of textual segments.  The