From: Mike Bayer Date: Tue, 23 Feb 2021 03:14:41 +0000 (-0500) Subject: refer to row elements as "elements", not columns X-Git-Tag: rel_1_4_0~39 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=930e1a89373ff3ee8c35b6696ed6d70502f03566;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git refer to row elements as "elements", not columns disambiguate between the "elements of a row" and a "column" which is taken to mean a database column, and remove confusing terms like "single-column ORM entity". Change-Id: I7304bdb6dd0f60ab0c36ef3ae40b1f36b29ea291 --- diff --git a/doc/build/orm/queryguide.rst b/doc/build/orm/queryguide.rst index 7d23821383..d15b69be2c 100644 --- a/doc/build/orm/queryguide.rst +++ b/doc/build/orm/queryguide.rst @@ -158,17 +158,18 @@ that selects from the mapped :class:`_schema.Table` to which ``User`` is mapped: [...] (){stop} When selecting from ORM entities, the entity itself is returned in the result -as a single column value; for example above, the :class:`_engine.Result` -returns :class:`_engine.Row` objects that have just a single column, that column -holding onto a ``User`` object:: +as a row with a single element, as opposed to a series of individual columns; +for example above, the :class:`_engine.Result` returns :class:`_engine.Row` +objects that have just a single element per row, that element holding onto a +``User`` object:: >>> result.fetchone() (User(id=1, name='spongebob', fullname='Spongebob Squarepants'),) -When selecting a list of single-column ORM entities, it is typical to skip -the generation of :class:`_engine.Row` objects and instead receive -ORM entities directly, which is achieved using the :meth:`_engine.Result.scalars` -method:: +When selecting a list of single-element rows containing ORM entities, it is +typical to skip the generation of :class:`_engine.Row` objects and instead +receive ORM entities directly, which is achieved using the +:meth:`_engine.Result.scalars` method:: >>> result.scalars().all() [User(id=2, name='sandy', fullname='Sandy Cheeks'), diff --git a/doc/build/tutorial/data.rst b/doc/build/tutorial/data.rst index ab180c3c2b..a658a7db79 100644 --- a/doc/build/tutorial/data.rst +++ b/doc/build/tutorial/data.rst @@ -357,7 +357,8 @@ composed against ORM entities, we will want to execute it using the :meth:`_orm.Session.execute` method on the :class:`_orm.Session`; using this approach, we continue to get :class:`_engine.Row` objects from the result, however these rows are now capable of including -complete entities, such as instances of the ``User`` class, as column values: +complete entities, such as instances of the ``User`` class, as individual +elements within each row: .. sourcecode:: pycon+sql @@ -428,9 +429,9 @@ in the same way as if we had used ``user_table`` directly:: When executing a statement like the above using the ORM :meth:`_orm.Session.execute` method, there is an important difference when we select from a full entity such as ``User``, as opposed to ``user_table``, which is that the **entity -itself is returned as a single column within each row**. That is, when we fetch rows from +itself is returned as a single element within each row**. That is, when we fetch rows from the above statement, as there is only the ``User`` entity in the list of -things to fetch, we get back :class:`_engine.Row` objects that have only one column, which contain +things to fetch, we get back :class:`_engine.Row` objects that have only one element, which contain instances of the ``User`` class:: >>> row = session.execute(select(User)).first() @@ -441,23 +442,24 @@ instances of the ``User`` class:: >>> row (User(id=1, name='spongebob', fullname='Spongebob Squarepants'),) -The above :class:`_engine.Row` has just one column, representing the ``User`` entity:: +The above :class:`_engine.Row` has just one element, representing the ``User`` entity:: >>> row[0] User(id=1, name='spongebob', fullname='Spongebob Squarepants') -Alternatively, we can select individual columns from an ORM entity, by -using the class-bound -attributes; when these are passed to a construct such as :func:`_sql.select`, -they are resolved into the -:class:`_schema.Column` or other SQL expression represented by each attribute:: +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 +the :class:`_schema.Column` or other SQL expression represented by each +attribute:: >>> print(select(User.name, User.fullname)) {opensql}SELECT user_account.name, user_account.fullname FROM user_account When we invoke *this* statement using :meth:`_orm.Session.execute`, we now -receive rows that have individual columns per value:: +receive rows that have individual elements per value, each corresponding +to a separate column or other SQL expression:: >>> row = session.execute(select(User.name, User.fullname)).first() {opensql}SELECT user_account.name, user_account.fullname @@ -467,8 +469,8 @@ receive rows that have individual columns per value:: ('spongebob', 'Spongebob Squarepants') The approaches can also be mixed, as below where we SELECT the ``name`` -attribute of the ``User`` entity as the first column, and combine it with full -``Address`` entities in the second column:: +attribute of the ``User`` entity as the first element of the row, and combine +it with full ``Address`` entities in the second element:: >>> session.execute( ... select(User.name, Address).