- New Query methods: query.label(name), query.as_scalar(),

return the query's statement as a scalar subquery
with /without label [ticket:1920];
query.with_entities(*ent), replaces the SELECT list of
the query with new entities.
Roughly equivalent to a generative form of query.values()
which accepts mapped entities as well as column
expressions.

1 files changed, 57 insertions, 2 deletions

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 17603e04a..a1ed19243 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -425,8 +425,8 @@ class Query(object):
         return stmt._annotate({'_halt_adapt': True})
 
     def subquery(self):
-        """return the full SELECT statement represented by this Query, 
-        embedded within an Alias.
+        """return the full SELECT statement represented by this :class:`.Query`, 
+        embedded within an :class:`.Alias`.
 
         Eager JOIN generation within the query is disabled.
 
@@ -436,7 +436,33 @@ class Query(object):
 
         """
         return self.enable_eagerloads(False).statement.alias()
+    
+    def label(self, name):
+        """Return the full SELECT statement represented by this :class:`.Query`, converted 
+        to a scalar subquery with a label of the given name.
+        
+        Analagous to :meth:`sqlalchemy.sql._SelectBaseMixin.label`.
+        
+        New in 0.6.5.
+
+        """
+        
+        return self.enable_eagerloads(False).statement.label(name)
+
 
+    def as_scalar(self):
+        """Return the full SELECT statement represented by this :class:`.Query`, converted 
+        to a scalar subquery.
+        
+        Analagous to :meth:`sqlalchemy.sql._SelectBaseMixin.as_scalar`.
+
+        New in 0.6.5.
+        
+        """
+        
+        return self.enable_eagerloads(False).statement.as_scalar()
+        
+        
     def __clause_element__(self):
         return self.enable_eagerloads(False).with_labels().statement
 
@@ -758,7 +784,36 @@ class Query(object):
             # end Py2K
         except StopIteration:
             return None
+    
+    @_generative()
+    def with_entities(self, *entities):
+        """Return a new :class:`.Query` replacing the SELECT list with the given
+        entities.
+        
+        e.g.::
+
+            # Users, filtered on some arbitrary criterion
+            # and then ordered by related email address
+            q = session.query(User).\\
+                        join(User.address).\\
+                        filter(User.name.like.('%ed%')).\\
+                        order_by(Address.email)
 
+            # given *only* User.id==5, Address.email, and 'q', what 
+            # would the *next* User in the result be ?
+            subq = q.with_entities(Address.email).\\
+                        order_by(None).\\
+                        filter(User.id==5).\\
+                        subquery()
+            q = q.join((subq, subq.c.email < Address.email)).\\
+                        limit(1)
+
+        New in 0.6.5.
+        
+        """
+        self._set_entities(entities)
+        
+        
     @_generative()
     def add_columns(self, *column):
         """Add one or more column expressions to the list