SQL 表达式作为映射属性¶

映射类上的属性可以链接到 SQL 表达式，这些表达式可以在查询中使用。

使用 Hybrid¶

将相对简单的 SQL 表达式链接到类的最简单、最灵活的方法是使用所谓的“混合属性”，如混合属性一节中所述。混合提供了一个在 Python 级别和 SQL 表达式级别都有效的表达式。例如，下面我们映射一个类 User，其中包含属性 firstname 和 lastname，并包含一个混合类，它将为我们提供 fullname，这是两者的字符串连接：

from sqlalchemy.ext.hybrid import hybrid_property


class User(Base):
    __tablename__ = "user"
    id = mapped_column(Integer, primary_key=True)
    firstname = mapped_column(String(50))
    lastname = mapped_column(String(50))

    @hybrid_property
    def fullname(self):
        return self.firstname + " " + self.lastname

在上面，fullname 属性在实例和类级别都进行了解释，以便它可以从实例中使用：

some_user = session.scalars(select(User).limit(1)).first()
print(some_user.fullname)

以及 useable within queries：

some_user = session.scalars(
    select(User).where(User.fullname == "John Smith").limit(1)
).first()

字符串连接示例很简单，其中 Python 表达式可以在实例和类级别实现双重用途。通常，SQL 表达式必须与 Python 表达式区分开来，这可以使用 hybrid_property.expression（） 中。下面我们使用 Python 中的 if 语句和 case（） 结构：

from sqlalchemy.ext.hybrid import hybrid_property
from sqlalchemy.sql import case


class User(Base):
    __tablename__ = "user"
    id = mapped_column(Integer, primary_key=True)
    firstname = mapped_column(String(50))
    lastname = mapped_column(String(50))

    @hybrid_property
    def fullname(self):
        if self.firstname is not None:
            return self.firstname + " " + self.lastname
        else:
            return self.lastname

    @fullname.expression
    def fullname(cls):
        return case(
            (cls.firstname != None, cls.firstname + " " + cls.lastname),
            else_=cls.lastname,
        )

使用 column_property¶

column_property（） 函数可用于以类似于常规映射 Column 的方式映射 SQL 表达式。使用此技术，该属性将在加载时与所有其他列映射属性一起加载。在某些情况下，这比使用 hybrids 更具优势，因为该值可以与对象的父行同时预先加载，特别是如果表达式是链接到其他表（通常作为相关子查询）以访问通常在已加载的对象上不可用的数据。

对 SQL 表达式使用 column_property（） 的缺点包括表达式必须与为整个类发出的 SELECT 语句兼容，并且在从声明性混合中使用 column_property（） 时也可能会出现一些配置怪癖。

我们的 “fullname” 示例可以用 column_property（） 表示，如下所示：

from sqlalchemy.orm import column_property


class User(Base):
    __tablename__ = "user"
    id = mapped_column(Integer, primary_key=True)
    firstname = mapped_column(String(50))
    lastname = mapped_column(String(50))
    fullname = column_property(firstname + " " + lastname)

也可以使用相关子查询。下面我们使用 select（） 结构创建一个 ScalarSelect，表示面向列的 SELECT 语句，该语句将特定 User 可用的 Address 对象计数链接在一起：

from sqlalchemy.orm import column_property
from sqlalchemy import select, func
from sqlalchemy import Column, Integer, String, ForeignKey

from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    pass


class Address(Base):
    __tablename__ = "address"
    id = mapped_column(Integer, primary_key=True)
    user_id = mapped_column(Integer, ForeignKey("user.id"))


class User(Base):
    __tablename__ = "user"
    id = mapped_column(Integer, primary_key=True)
    address_count = column_property(
        select(func.count(Address.id))
        .where(Address.user_id == id)
        .correlate_except(Address)
        .scalar_subquery()
    )

在上面的示例中，我们定义了一个 ScalarSelect（） 结构，如下所示：

stmt = (
    select(func.count(Address.id))
    .where(Address.user_id == id)
    .correlate_except(Address)
    .scalar_subquery()
)

上面，我们首先使用 select（） 创建一个 Select 构造，然后使用 Select.scalar_subquery（） 方法，表明我们打算使用 this select 列表达式上下文中的语句。

在 Select 本身中，我们选择 Address.id 行的计数，其中 Address.user_id 列等于 id，在 User 类的上下文中是名为 id 的列（请注意，id 也是 Python 内置函数的名称，这不是我们在这里想要使用的 - 如果我们在 User 之外 class 定义，我们会使用 User.id）。

Select.correlate_except（） 方法指示此 select（） 的 FROM 子句中的每个元素都可以从 FROM 列表中省略（即，与针对 User 的封闭 SELECT 语句相关），但与 Address 对应的元素除外。这并非绝对必要，但可以防止在 User 和 Address 表之间存在一长串联接的情况下，在 SELECT 语句对 Address 嵌套。

对于引用从多对多关系链接的列的 column_property（），请使用 and_（） 将关联表的字段联接到关系中的两个表：

from sqlalchemy import and_


class Author(Base):
    # ...

    book_count = column_property(
        select(func.count(books.c.id))
        .where(
            and_(
                book_authors.c.author_id == authors.c.id,
                book_authors.c.book_id == books.c.id,
            )
        )
        .scalar_subquery()
    )

将 column_property（）添加到现有的 Declarative 映射类中¶

如果导入问题阻止 column_property（） 与类内联定义，则可以在配置两者后将其分配给类。当使用使用 DeclarativeBase 基类（即由 DeclarativeBase 超类或遗留函数（如 declarative_base（） ））生成的）的映射时，此属性分配具有调用 Mapper.add_property（） 的效果要在事后添加其他属性，请执行以下作：

# only works if a declarative base class is in use
User.address_count = column_property(
    select(func.count(Address.id)).where(Address.user_id == User.id).scalar_subquery()
)

当使用不使用声明式基类（例如 registry.mapped（） 装饰器）的映射样式时，Mapper.add_property（） method 可以在底层 Mapper 对象上显式调用，这可以通过 inspect（） 获得：

from sqlalchemy.orm import registry

reg = registry()


@reg.mapped
class User:
    __tablename__ = "user"

    # ... additional mapping directives


# later ...

# works for any kind of mapping
from sqlalchemy import inspect

inspect(User).add_property(
    column_property(
        select(func.count(Address.id))
        .where(Address.user_id == User.id)
        .scalar_subquery()
    )
)

另请参阅

将其他列追加到现有的 Declarative 映射类

在 Map 时从 Column Properties 进行组合¶

可以创建组合多个 ColumnProperty 对象。在 Core 表达式上下文中使用 ColumnProperty 时，如果它以现有表达式对象为目标，则它将被解释为 SQL 表达式;这是通过 Core 检测对象具有返回 SQL 表达式的 __clause_element__（） 方法来实现的。但是，如果 ColumnProperty 用作表达式中的前导对象，而没有其他 Core SQL 表达式对象作为目标，则 ColumnProperty.expression 属性将返回基础 SQL 表达式，以便可以一致地使用它来构建 SQL 表达式。下面，File 类包含一个属性 File.path，它将字符串标记连接到 File.filename attribute，它本身就是一个 ColumnProperty：

class File(Base):
    __tablename__ = "file"

    id = mapped_column(Integer, primary_key=True)
    name = mapped_column(String(64))
    extension = mapped_column(String(8))
    filename = column_property(name + "." + extension)
    path = column_property("C:/" + filename.expression)

当 File 类在表达式中正常使用时，分配给 filename 和 path 的属性可以直接使用。使用仅当直接在映射定义中使用 ColumnProperty 时，才需要 ColumnProperty.expression 属性：

stmt = select(File.path).where(File.filename == "foo.txt")

在 `column_property（）` 中使用列延迟¶

ORM Querying Guide 中引入的列延迟功能在限制在映射时可以使用 column_property（）映射的 SQL 表达式中，使用 deferred（） 函数代替 column_property（） 来代替（）来代替（）的函数：

from sqlalchemy.orm import deferred


class User(Base):
    __tablename__ = "user"

    id: Mapped[int] = mapped_column(primary_key=True)
    firstname: Mapped[str] = mapped_column()
    lastname: Mapped[str] = mapped_column()
    fullname: Mapped[str] = deferred(firstname + " " + lastname)

另请参阅

将 deferred（）用于命令式映射器，映射的 SQL 表达式

使用普通描述符¶

如果 SQL 查询比 column_property（） 更详细或者hybrid_property can provide 的表达式，则可以使用作为属性访问的常规 Python 函数，前提是表达式只需要在已加载的实例上可用。该函数使用 Python 自己的 @property 装饰器进行装饰，以将其标记为只读属性。在函数中，object_session（） 用于定位当前对象对应的 Session，然后用于发出查询：

from sqlalchemy.orm import object_session
from sqlalchemy import select, func


class User(Base):
    __tablename__ = "user"
    id = mapped_column(Integer, primary_key=True)
    firstname = mapped_column(String(50))
    lastname = mapped_column(String(50))

    @property
    def address_count(self):
        return object_session(self).scalar(
            select(func.count(Address.id)).where(Address.user_id == self.id)
        )

普通描述符方法作为最后的手段很有用，但在通常情况下，性能不如 hybrid 和 column 属性方法，因为它需要在每次访问时发出 SQL 查询。

查询时 SQL 表达式作为映射属性¶

除了能够在映射类上配置固定的 SQL 表达式之外，SQLAlchemy ORM 还包括一个功能，其中对象可以加载任意 SQL 表达式的结果，这些表达式在查询时作为其状态的一部分进行设置。通过使用 query_expression（） 配置 ORM 映射属性，然后使用 with_expression（） 加载器选项。请参阅该部分将任意 SQL 表达式加载到对象上，有关示例映射和用法。

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy ORM

SQL 表达式作为映射属性¶

使用 Hybrid¶

使用 column_property¶

将 column_property（）添加到现有的 Declarative 映射类中¶

在 Map 时从 Column Properties 进行组合¶

在 `column_property（）` 中使用列延迟¶

使用普通描述符¶

查询时 SQL 表达式作为映射属性¶

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy ORM

SQL 表达式作为映射属性¶

使用 Hybrid¶

使用 column_property¶

将 column_property（） 添加到现有的 Declarative 映射类中¶

在 Map 时从 Column Properties 进行组合¶

在 column_property（） 中使用列延迟¶

使用普通描述符¶

查询时 SQL 表达式作为映射属性¶

将 column_property（）添加到现有的 Declarative 映射类中¶

在 `column_property（）` 中使用列延迟¶