SQL Expressions as Mapped Attributes

    The easiest and most flexible way to link relatively simple SQL expressions to a class is to use a so-called “hybrid attribute”, described in the section Hybrid Attributes. The hybrid provides for an expression that works at both the Python level as well as at the SQL expression level. For example, below we map a class , containing attributes firstname and lastname, and include a hybrid that will provide for us the fullname, which is the string concatenation of the two:

    Above, the fullname attribute is interpreted at both the instance and class level, so that it is available from an instance:

    1. some_user = session.query(User).first()
    2. print(some_user.fullname)

    as well as usable within queries:

    1. some_user = session.query(User).filter(User.fullname == "John Smith").first()

    The string concatenation example is a simple one, where the Python expression can be dual purposed at the instance and class level. Often, the SQL expression must be distinguished from the Python expression, which can be achieved using . Below we illustrate the case where a conditional needs to be present inside the hybrid, using the if statement in Python and the case() construct for SQL expressions:

    1. from sqlalchemy.ext.hybrid import hybrid_property
    2. from sqlalchemy.sql import case
    4. class User(Base):
    5.     __tablename__ = 'user'
    6.     id = Column(Integer, primary_key=True)
    7.     firstname = Column(String(50))
    8.     lastname = Column(String(50))
    10.     @hybrid_property
    11.     def fullname(self):
    12.         if self.firstname is not None:
    13.             return self.firstname + " " + self.lastname
    14.         else:
    15.             return self.lastname
    17.     @fullname.expression
    18.     def fullname(cls):
    19.         return case([
    20.             (cls.firstname != None, cls.firstname + " " + cls.lastname),
    21.         ], else_ = cls.lastname)

    The function can be used to map a SQL expression in a manner similar to a regularly mapped Column. With this technique, the attribute is loaded along with all other column-mapped attributes at load time. This is in some cases an advantage over the usage of hybrids, as the value can be loaded up front at the same time as the parent row of the object, particularly if the expression is one which links to other tables (typically as a correlated subquery) to access data that wouldn’t normally be available on an already loaded object.

    Disadvantages to using for SQL expressions include that the expression must be compatible with the SELECT statement emitted for the class as a whole, and there are also some configurational quirks which can occur when using column_property() from declarative mixins.

    Our “fullname” example can be expressed using as follows:

    1. from sqlalchemy.orm import column_property
    3. class User(Base):
    4.     __tablename__ = 'user'
    5.     id = Column(Integer, primary_key=True)
    6.     firstname = Column(String(50))
    7.     lastname = Column(String(50))
    8.     fullname = column_property(firstname + " " + lastname)

    Correlated subqueries may be used as well. Below we use the select() construct to create a SELECT that links together the count of Address objects available for a particular User:

    1. from sqlalchemy.orm import column_property
    2. from sqlalchemy import select, func
    3. from sqlalchemy import Column, Integer, String, ForeignKey
    6. Base = declarative_base()
    8. class Address(Base):
    9.     __tablename__ = 'address'
    10.     id = Column(Integer, primary_key=True)
    11.     user_id = Column(Integer, ForeignKey('user.id'))
    13. class User(Base):
    14.     __tablename__ = 'user'
    15.     id = Column(Integer, primary_key=True)
    16.     address_count = column_property(
    17.         select(func.count(Address.id)).\
    19.             correlate_except(Address)
    20.     )

    In the above example, we define a construct like the following:

    The select.correlate_except() directive indicates that each element in the FROM clause of this select() may be omitted from the FROM list (that is, correlated to the enclosing SELECT statement against User) except for the one corresponding to Address. This isn’t strictly necessary, but prevents Address from being inadvertently omitted from the FROM list in the case of a long string of joins between User and Address tables where SELECT statements against Address are nested.

    If import issues prevent the from being defined inline with the class, it can be assigned to the class after both are configured. In Declarative this has the effect of calling Mapper.add_property() to add an additional property after the fact:

    1. User.address_count = column_property(
    2.         select(func.count(Address.id)).\
    3.             where(Address.user_id==User.id)
    4.     )

    For a that refers to columns linked from a many-to-many relationship, use and_() to join the fields of the association table to both tables in a relationship:

    1. from sqlalchemy import and_
    3. class Author(Base):
    4.     # ...
    6.     book_count = column_property(
    7.         select(func.count(books.c.id)
    8.         ).where(
    9.             and_(
    10.                 book_authors.c.author_id==authors.c.id,
    11.                 book_authors.c.book_id==books.c.id
    12.             )
    13.         )
    14.     )

    It is possible to create mappings that combine multiple objects together. The ColumnProperty will be interpreted as a SQL expression when used in a Core expression context, provided that it is targeted by an existing expression object; this works by the Core detecting that the object has a __clause_element__() method which returns a SQL expression. However, if the is used as a lead object in an expression where there is no other Core SQL expression object to target it, the ColumnProperty.expression attribute will return the underlying SQL expression so that it can be used to build SQL expressions consistently. Below, the File class contains an attribute File.path that concatenates a string token to the File.filename attribute, which is itself a :

    1. class File(Base):
    2.     __tablename__ = 'file'
    4.     id = Column(Integer, primary_key=True)
    5.     name = Column(String(64))
    6.     extension = Column(String(8))
    7.     filename = column_property(name + '.' + extension)

    When the File class is used in expressions normally, the attributes assigned to filename and path are usable directly. The use of the ColumnProperty.expression attribute is only necessary when using the directly within the mapping definition:

    1. q = session.query(File.path).filter(File.filename == 'foo.txt')

    In cases where a SQL query more elaborate than what or can provide must be emitted, a regular Python function accessed as an attribute can be used, assuming the expression only needs to be available on an already-loaded instance. The function is decorated with Python’s own @property decorator to mark it as a read-only attribute. Within the function, object_session() is used to locate the corresponding to the current object, which is then used to emit a query:

    1. from sqlalchemy.orm import object_session
    2. from sqlalchemy import select, func
    4. class User(Base):
    5.     __tablename__ = 'user'
    6.     id = Column(Integer, primary_key=True)
    7.     firstname = Column(String(50))
    8.     lastname = Column(String(50))
    10.     @property
    11.     def address_count(self):
    12.         return object_session(self).\
    13.             scalar(
    14.                 select(func.count(Address.id)).\
    15.                     where(Address.user_id==self.id)
    16.             )

    The plain descriptor approach is useful as a last resort, but is less performant in the usual case than both the hybrid and column property approaches, in that it needs to emit a SQL query upon each access.

    When using Session.query(), we have the option to specify not just mapped entities but ad-hoc SQL expressions as well. Suppose if a class A had integer attributes .x and .y, we could query for A objects, and additionally the sum of .x and .y, as follows:

    The above query returns tuples of the form (A object, integer).

    1. from sqlalchemy.orm import query_expression
    3. class A(Base):
    4.     __tablename__ = 'a'
    5.     id = Column(Integer, primary_key=True)
    6.     x = Column(Integer)
    7.     y = Column(Integer)
    9.     expr = query_expression()

    We can then query for objects of type A, applying an arbitrary SQL expression to be populated into A.expr:

    1. from sqlalchemy.orm import with_expression
    2. q = session.query(A).options(
    3.     with_expression(A.expr, A.x + A.y))

    The mapping has these caveats:

    • On an object where query_expression() were not used to populate the attribute, the attribute on an object instance will have the value None, unless the parameter is set to an alternate SQL expression.

    • The query_expression value does not populate on an object that is already loaded. That is, this will not work:

      1. obj = session.query(A).first()
      3. obj = session.query(A).options(with_expression(A.expr, some_expr)).first()

      To ensure the attribute is re-loaded, use Query.populate_existing():

      1. obj = session.query(A).populate_existing().options(
      2.     with_expression(A.expr, some_expr)).first()

    • The query_expression value does not refresh when the object is expired. Once the object is expired, either via or via the expire_on_commit behavior of Session.commit(), the value is removed from the attribute and will return None on subsequent access. Only by running a new that touches the object which includes a new with_expression() directive will the attribute be set to a non-None value.

    • The mapped attribute currently cannot be applied to other parts of the query, such as the WHERE clause, the ORDER BY clause, and make use of the ad-hoc expression; that is, this won’t work:

      1. # wont work
      2. q = session.query(A).options(
      3.     with_expression(A.expr, A.x + A.y)

      The expression will resolve to NULL in the above WHERE clause and ORDER BY clause. To use the expression throughout the query, assign to a variable and use that:

    New in version 1.2.