ORM quickstart

This is done in 1.4 style so it can be backported to 1.4.
Will put this up as is, we can work on it.   For 2.0, the
ORM mapping will be updated to mapped_column() style when
we do the full pass.

Change-Id: Icfdf81449973844dac244b3a107ce955a7d3b16c

2 files changed, 19 insertions, 0 deletions

diff --git a/doc/build/tutorial/data_select.rst b/doc/build/tutorial/data_select.rst
index 9f7aafc1b..c8fac288e 100644
--- a/doc/build/tutorial/data_select.rst
+++ b/doc/build/tutorial/data_select.rst
@@ -156,6 +156,20 @@ The above :class:`_engine.Row` has just one element, representing the ``User`` e
     >>> row[0]
     User(id=1, name='spongebob', fullname='Spongebob Squarepants')
 
+A highly recommended convenience method of achieving the same result as above
+is to use the :meth:`_orm.Session.scalars` method to execute the statement
+directly; this method will return a :class:`_result.ScalarResult` object
+that delivers the first "column" of each row at once, in this case,
+instances of the ``User`` class::
+
+    >>> user = session.scalars(select(User)).first()
+    {opensql}SELECT user_account.id, user_account.name, user_account.fullname
+    FROM user_account
+    [...] (){stop}
+    >>> user
+    User(id=1, name='spongebob', fullname='Spongebob Squarepants')
+
+
 Alternatively, we can select individual columns of an ORM entity as distinct
 elements within result rows, by using the class-bound attributes; when these
 are passed to a construct such as :func:`_sql.select`, they are resolved into
diff --git a/doc/build/tutorial/dbapi_transactions.rst b/doc/build/tutorial/dbapi_transactions.rst
index f4d2ad8e0..da07de87c 100644
--- a/doc/build/tutorial/dbapi_transactions.rst
+++ b/doc/build/tutorial/dbapi_transactions.rst
@@ -525,6 +525,11 @@ than that, however understanding that it has a :meth:`_orm.Session.execute`
 method that's used the same way as :meth:`_future.Connection.execute` will
 get us started with the examples that follow later.
 
+.. seealso::
+
+    :ref:`session_basics` - presents basic creational and usage patterns with
+    the :class:`_orm.Session` object.
+