From 1fe60f678870237dc2cea9b5ce3fe650ccbde2e6 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Wed, 8 Mar 2023 17:23:31 -0500 Subject: [PATCH] clarify "selecting individual columns" doc Just went to refer to this and it was full of difficult terminology for no good reason. What's troubling is that this doc is like the tenth time I've rewritten this and it still was loaded with too much jargon and not clear about the behavior. Change-Id: I22745962568277eead6081a82003ac90665048e0 --- doc/build/orm/queryguide/select.rst | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/doc/build/orm/queryguide/select.rst b/doc/build/orm/queryguide/select.rst index 7a2eb3a862..c14eb134e4 100644 --- a/doc/build/orm/queryguide/select.rst +++ b/doc/build/orm/queryguide/select.rst @@ -175,11 +175,12 @@ above using this form as well:: Selecting Individual Attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The attributes on a mapped class, such as ``User.name`` and ``Address.email_address``, -have a similar behavior as that of the entity class itself such as ``User`` -in that they are automatically converted into ORM-annotated Core objects -when passed to :func:`_sql.select`. They may be used in the same way -as table columns are used:: +The attributes on a mapped class, such as ``User.name`` and +``Address.email_address``, can be used just like :class:`_schema.Column` or +other SQL expression objects when passed to :func:`_sql.select`. Creating a +:func:`_sql.select` that is against specific columns will return :class:`.Row` +objects, and **not** entities like ``User`` or ``Address`` objects. +Each :class:`.Row` will have each column represented individually:: >>> result = session.execute( ... select(User.name, Address.email_address) @@ -191,11 +192,8 @@ as table columns are used:: ORDER BY user_account.id, address.id [...] (){stop} -ORM attributes, themselves known as -:class:`_orm.InstrumentedAttribute` -objects, can be used in the same way as any :class:`_sql.ColumnElement`, -and are delivered in result rows just the same way, such as below -where we refer to their values by column name within each row:: +The above statement returns :class:`.Row` objects with ``name`` and +``email_address`` columns, as illustrated in the runtime demonstration below:: >>> for row in result: ... print(f"{row.name} {row.email_address}") -- 2.47.2