From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 5 Jul 2019 19:55:20 +0000 (-0400)
Subject: Rename tutorial section to "Using Aliases and Subqueries"
X-Git-Tag: rel_1_3_6~19
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0b7a99c4bd821f860a1c1cfeecd19ae2f20ad343;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Rename tutorial section to "Using Aliases and Subqueries"

add some verbiage to start differentiating a subquery from
an alias.

Also, get rid of a very strange note to use ``.correlate(None)``
on a non-scalar subquery; this is unnecessary and confusing.

Change-Id: I83b2fd1275c719a32bb74060756d61bc51b52892
(cherry picked from commit f4f9ec1c2f6fad29729ee379adb537f8648d1737)
---

diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst
index d2ab167e09..69499d7ed1 100644
--- a/doc/build/core/tutorial.rst
+++ b/doc/build/core/tutorial.rst
@@ -1085,8 +1085,8 @@ by a column name that appears more than once:
 
 .. _core_tutorial_aliases:
 
-Using Aliases
-=============
+Using Aliases and Subqueries
+============================
 
 The alias in SQL corresponds to a "renamed" version of a table or SELECT
 statement, which occurs anytime you say "SELECT .. FROM sometable AS
@@ -1097,10 +1097,11 @@ FROM clause multiple times. In the case of a SELECT statement, it provides a
 parent name for the columns represented by the statement, allowing them to be
 referenced relative to this name.
 
-In SQLAlchemy, any :class:`.Table`, :func:`.select` construct, or
-other selectable can be turned into an alias using the :meth:`.FromClause.alias`
-method, which produces a :class:`.Alias` construct.  As an example, suppose we know that our user ``jack`` has two
-particular email addresses. How can we locate jack based on the combination of those two
+In SQLAlchemy, any :class:`.Table`, :func:`.select` construct, or other
+selectable can be turned into an alias or named subquery using the
+:meth:`.FromClause.alias` method, which produces a :class:`.Alias` construct.
+As an example, suppose we know that our user ``jack`` has two particular email
+addresses. How can we locate jack based on the combination of those two
 addresses?   To accomplish this, we'd use a join to the ``addresses`` table,
 once for each address.   We create two :class:`.Alias` constructs against
 ``addresses``, and then use them both within a :func:`.select` construct:
@@ -1142,15 +1143,16 @@ to the :meth:`.FromClause.alias` method::
     >>> a1 = addresses.alias('a1')
 
 Aliases can of course be used for anything which you can SELECT from,
-including SELECT statements themselves. We can self-join the ``users`` table
+including SELECT statements themselves, by converting the SELECT statement
+into a named subquery.  The :meth:`.SelectBase.alias` method performs this
+role.   We can self-join the ``users`` table
 back to the :func:`.select` we've created by making an alias of the entire
-statement. The ``correlate(None)`` directive is to avoid SQLAlchemy's attempt
-to "correlate" the inner ``users`` table with the outer one:
+statement:
 
 .. sourcecode:: pycon+sql
 
-    >>> a1 = s.correlate(None).alias()
-    >>> s = select([users.c.name]).where(users.c.id == a1.c.id)
+    >>> addresses_subq = s.alias()
+    >>> s = select([users.c.name]).where(users.c.id == addresses_subq.c.id)
     {sql}>>> conn.execute(s).fetchall()
     SELECT users.name
     FROM users,