Add where criteria example to selected_columns attribute

Change-Id: Ic9050dd846d5a3103aabe6c4d90e5bf2d7b8372d

diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index 060b03b503b7f21d43bac68425566936b7589eb2..b13c53249e75f87587cdbeb52eceeff1ffbe8fbc 100644 (file)
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -6200,6 +6200,18 @@ class Select(
         :class:`_expression.ColumnElement` objects that are in the
         :attr:`_expression.FromClause.c` collection of the from element.
 
+        A use case for the :attr:`_sql.Select.selected_columns` collection is
+        to allow the existing columns to be referenced when adding additional
+        criteria, e.g.::
+
+            def filter_on_id(my_select, id):
+                return my_select.where(my_select.selected_columns['id'] == id)
+
+            stmt = select(MyModel)
+
+            # adds "WHERE id=:param" to the statement
+            stmt = filter_on_id(stmt, 42)
+
         .. note::
 
             The :attr:`_sql.Select.selected_columns` collection does not