处理大型集合
relationship()的默认行为是根据配置的 加载策略 完全将集合内容加载到内存中，该加载策略控制何时以及如何从数据库加载这些内容。 相关集合可能不仅在访问时加载到内存中，或者急切地加载，而且在集合本身发生变化时以及在由工作单元系统删除所有者对象时也需要进行填充。
当相关集合可能非常大时，无论在任何情况下将这样的集合加载到内存中都可能不可行，因为这样的操作可能会过度消耗时间、网络和内存资源。
本节包括旨在允许relationship()与大型集合一起使用并保持足够性能的 API 特性。
仅写关系
仅写加载器策略是配置relationship()的主要方法，该方法将保持可写性，但不会加载其内容到内存中。 下面是使用现代类型注释的声明式形式的仅写 ORM 配置的示例：
>>> from decimal import Decimal >>> from datetime import datetime >>> from sqlalchemy import ForeignKey >>> from sqlalchemy import func >>> from sqlalchemy.orm import DeclarativeBase >>> from sqlalchemy.orm import Mapped >>> from sqlalchemy.orm import mapped_column >>> from sqlalchemy.orm import relationship >>> from sqlalchemy.orm import Session >>> from sqlalchemy.orm import WriteOnlyMapped >>> class Base(DeclarativeBase): ... pass >>> class Account(Base): ... __tablename__ = "account" ... id: Mapped[int] = mapped_column(primary_key=True) ... identifier: Mapped[str] ... ... account_transactions: WriteOnlyMapped["AccountTransaction"] = relationship( ... cascade="all, delete-orphan", ... passive_deletes=True, ... order_by="AccountTransaction.timestamp", ... ) ... ... def __repr__(self): ... return f"Account(identifier={self.identifier!r})" >>> class AccountTransaction(Base): ... __tablename__ = "account_transaction" ... id: Mapped[int] = mapped_column(primary_key=True) ... account_id: Mapped[int] = mapped_column( ... ForeignKey("account.id", ondelete="cascade") ... ) ... description: Mapped[str] ... amount: Mapped[Decimal] ... timestamp: Mapped[datetime] = mapped_column(default=func.now()) ... ... def __repr__(self): ... return ( ... f"AccountTransaction(amount={self.amount:.2f}, " ... f"timestamp={self.timestamp.isoformat()!r})" ... ) ... ... __mapper_args__ = {"eager_defaults": True}
上述示例中，account_transactions 关系不是使用普通的Mapped注释配置的，而是使用WriteOnlyMapped类型注释配置的，在运行时会将 lazy="write_only" 的 加载策略 分配给目标 relationship()。 WriteOnlyMapped 注释是 Mapped 注释的替代形式，指示对象实例上使用 WriteOnlyCollection 集合类型。
上述relationship()配置还包括几个元素，这些元素是特定于删除 Account 对象时要采取的操作以及从 account_transactions 集合中移除 AccountTransaction 对象时要采取的操作。 这些元素包括：
passive_deletes=True- 允许工作单元在删除Account时无需加载集合；参见使用 ORM 关系进行外键级联删除。- 在
ForeignKey约束上配置ondelete="cascade"。这也在使用 ORM 关系进行外键级联删除中详细说明。 cascade="all, delete-orphan"- 指示工作单元在从集合中删除时删除AccountTransaction对象。请参见 delete-orphan 中的 Cascades 文档。
2.0 版本新增：“仅写入”关系加载器。
创建和持久化新的仅写入集合
写入-仅集合仅允许对瞬态或挂起对象直接分配集合。根据我们上面的映射，这表示我们可以创建一个新的Account对象，其中包含一系列要添加到Session中的AccountTransaction对象。任何 Python 可迭代对象都可以用作要开始的对象的来源，下面我们使用 Python list：
>>> new_account = Account( ... identifier="account_01", ... account_transactions=[ ... AccountTransaction(description="initial deposit", amount=Decimal("500.00")), ... AccountTransaction(description="transfer", amount=Decimal("1000.00")), ... AccountTransaction(description="withdrawal", amount=Decimal("-29.50")), ... ], ... ) >>> with Session(engine) as session: ... session.add(new_account) ... session.commit() BEGIN (implicit) INSERT INTO account (identifier) VALUES (?) [...] ('account_01',) INSERT INTO account_transaction (account_id, description, amount, timestamp) VALUES (?, ?, ?, CURRENT_TIMESTAMP) RETURNING id, timestamp [... (insertmanyvalues) 1/3 (ordered; batch not supported)] (1, 'initial deposit', 500.0) INSERT INTO account_transaction (account_id, description, amount, timestamp) VALUES (?, ?, ?, CURRENT_TIMESTAMP) RETURNING id, timestamp [insertmanyvalues 2/3 (ordered; batch not supported)] (1, 'transfer', 1000.0) INSERT INTO account_transaction (account_id, description, amount, timestamp) VALUES (?, ?, ?, CURRENT_TIMESTAMP) RETURNING id, timestamp [insertmanyvalues 3/3 (ordered; batch not supported)] (1, 'withdrawal', -29.5) COMMIT
一旦对象被持久化到数据库（即处于持久化或分离状态），该集合就具有扩展新项目的能力，以及删除单个项目的能力。但是，该集合可能不再重新分配一个完整的替换集合，因为这样的操作需要将先前的集合完全加载到内存中，以便将旧条目与新条目进行协调：
>>> new_account.account_transactions = [ ... AccountTransaction(description="some transaction", amount=Decimal("10.00")) ... ] Traceback (most recent call last): ... sqlalchemy.exc.InvalidRequestError: Collection "Account.account_transactions" does not support implicit iteration; collection replacement operations can't be used
向现有集合添加新项目
对于持久对象的写入-仅集合，使用工作单元过程对集合进行修改只能通过使用WriteOnlyCollection.add()、WriteOnlyCollection.add_all()和WriteOnlyCollection.remove()方法进行：
>>> from sqlalchemy import select >>> session = Session(engine, expire_on_commit=False) >>> existing_account = session.scalar(select(Account).filter_by(identifier="account_01")) BEGIN (implicit) SELECT account.id, account.identifier FROM account WHERE account.identifier = ? [...] ('account_01',) >>> existing_account.account_transactions.add_all( ... [ ... AccountTransaction(description="paycheck", amount=Decimal("2000.00")), ... AccountTransaction(description="rent", amount=Decimal("-800.00")), ... ] ... ) >>> session.commit() INSERT INTO account_transaction (account_id, description, amount, timestamp) VALUES (?, ?, ?, CURRENT_TIMESTAMP) RETURNING id, timestamp [... (insertmanyvalues) 1/2 (ordered; batch not supported)] (1, 'paycheck', 2000.0) INSERT INTO account_transaction (account_id, description, amount, timestamp) VALUES (?, ?, ?, CURRENT_TIMESTAMP) RETURNING id, timestamp [insertmanyvalues 2/2 (ordered; batch not supported)] (1, 'rent', -800.0) COMMIT
上述添加的项目将在Session中的挂起队列中保留，直到下一次刷新，在此刻它们将被插入到数据库中，假设添加的对象之前是瞬态的。
查询项目
WriteOnlyCollection 在任何时候都不会存储对集合当前内容的引用，也不具有直接发出 SELECT 到数据库以加载它们的行为；其覆盖的假设是集合可能包含数千或数百万行，并且不应作为任何其他操作的副作用而完全加载到内存中。
相反，WriteOnlyCollection 包括诸如WriteOnlyCollection.select()之类的生成 SQL 的助手，该方法将生成一个预先配置了当前父行的正确 WHERE / FROM 条件的Select构造，然后可以进一步修改以选择所需的任何行范围，以及使用像服务器端游标之类的特性来调用以便以内存高效的方式迭代完整集合的进程。
下面是生成的语句的示例。请注意，它还包括在示例映射中由relationship.order_by参数指示的 ORDER BY 条件；如果未配置该参数，则将省略此条件：
>>> print(existing_account.account_transactions.select()) SELECT account_transaction.id, account_transaction.account_id, account_transaction.description, account_transaction.amount, account_transaction.timestamp FROM account_transaction WHERE :param_1 = account_transaction.account_id ORDER BY account_transaction.timestamp
我们可以使用这个Select构造与Session一起来查询AccountTransaction对象，最容易的是使用Session.scalars()方法，该方法将返回直接生成 ORM 对象的Result。通常，但不是必须的，Select可能会进一步修改以限制返回的记录；在下面的示例中，还添加了额外的 WHERE 条件，以仅加载“debit”账户交易，以及“LIMIT 10”以仅检索前十行：
>>> account_transactions = session.scalars( ... existing_account.account_transactions.select() ... .where(AccountTransaction.amount < 0) ... .limit(10) ... ).all() BEGIN (implicit) SELECT account_transaction.id, account_transaction.account_id, account_transaction.description, account_transaction.amount, account_transaction.timestamp FROM account_transaction WHERE ? = account_transaction.account_id AND account_transaction.amount < ? ORDER BY account_transaction.timestamp LIMIT ? OFFSET ? [...] (1, 0, 10, 0) >>> print(account_transactions) [AccountTransaction(amount=-29.50, timestamp='...'), AccountTransaction(amount=-800.00, timestamp='...')]
删除项目
在当前Session中加载的个体项可能会被标记为要从集合中删除，使用WriteOnlyCollection.remove()方法。当操作继续时，刷新过程将隐式地将对象视为已经是集合的一部分。下面的示例说明了如何删除单个AccountTransaction项，根据级联设置，将导致删除该行：
>>> existing_transaction = account_transactions[0] >>> existing_account.account_transactions.remove(existing_transaction) >>> session.commit() DELETE FROM account_transaction WHERE account_transaction.id = ? [...] (3,) COMMIT
与任何 ORM 映射的集合一样，对象的删除可以按照解除与集合的关联并将对象保留在数据库中的方式进行，也可以根据relationship()的 delete-orphan 配置发出其行的 DELETE。
在不删除的情况下删除集合涉及将外键列设置为 NULL 以进行一对多关系，或者删除相应的关联行以进行多对多关系。
新项目的批量插入
WriteOnlyCollection可以生成 DML 构造，例如Insert对象，可在 ORM 上下文中使用以产生批量插入行为。请参阅 ORM 批量 INSERT 语句部分，了解 ORM 批量插入的概述。
一对多集合
仅针对常规的一对多集合，WriteOnlyCollection.insert()方法将生成一个预先建立了与父对象相对应的 VALUES 条件的Insert构造。由于这个 VALUES 条件完全针对相关表，因此该语句可用于插入新的行，这些新行同时将成为相关集合中的新记录：
>>> session.execute( ... existing_account.account_transactions.insert(), ... [ ... {"description": "transaction 1", "amount": Decimal("47.50")}, ... {"description": "transaction 2", "amount": Decimal("-501.25")}, ... {"description": "transaction 3", "amount": Decimal("1800.00")}, ... {"description": "transaction 4", "amount": Decimal("-300.00")}, ... ], ... ) BEGIN (implicit) INSERT INTO account_transaction (account_id, description, amount, timestamp) VALUES (?, ?, ?, CURRENT_TIMESTAMP) [...] [(1, 'transaction 1', 47.5), (1, 'transaction 2', -501.25), (1, 'transaction 3', 1800.0), (1, 'transaction 4', -300.0)] <...> >>> session.commit() COMMIT
另请参阅
ORM 批量 INSERT 语句 - 在 ORM 查询指南中
一对多 - 在基本关系模式中
多对多集合
对于一个多对多集合，两个类之间的关系涉及一个使用relationship.secondary参数配置的第三个表的情况，通过WriteOnlyCollection.add_all()方法，可以先分别批量插入新记录，然后检索它们，并将这些记录传递给WriteOnlyCollection.add_all()方法，单位操作过程将继续将它们作为集合的一部分进行持久化。
假设一个类BankAudit使用一个多对多表引用了许多AccountTransaction记录：
>>> from sqlalchemy import Table, Column >>> audit_to_transaction = Table( ... "audit_transaction", ... Base.metadata, ... Column("audit_id", ForeignKey("audit.id", ondelete="CASCADE"), primary_key=True), ... Column( ... "transaction_id", ... ForeignKey("account_transaction.id", ondelete="CASCADE"), ... primary_key=True, ... ), ... ) >>> class BankAudit(Base): ... __tablename__ = "audit" ... id: Mapped[int] = mapped_column(primary_key=True) ... account_transactions: WriteOnlyMapped["AccountTransaction"] = relationship( ... secondary=audit_to_transaction, passive_deletes=True ... )
为了说明这两个操作，我们使用批量插入添加更多的AccountTransaction对象，通过在批量插入语句中添加returning(AccountTransaction)来使用 RETURNING 检索它们（请注意，我们也可以同样轻松地使用现有的AccountTransaction对象）：
>>> new_transactions = session.scalars( ... existing_account.account_transactions.insert().returning(AccountTransaction), ... [ ... {"description": "odd trans 1", "amount": Decimal("50000.00")}, ... {"description": "odd trans 2", "amount": Decimal("25000.00")}, ... {"description": "odd trans 3", "amount": Decimal("45.00")}, ... ], ... ).all() BEGIN (implicit) INSERT INTO account_transaction (account_id, description, amount, timestamp) VALUES (?, ?, ?, CURRENT_TIMESTAMP), (?, ?, ?, CURRENT_TIMESTAMP), (?, ?, ?, CURRENT_TIMESTAMP) RETURNING id, account_id, description, amount, timestamp [...] (1, 'odd trans 1', 50000.0, 1, 'odd trans 2', 25000.0, 1, 'odd trans 3', 45.0)
准备好一个AccountTransaction对象列表后，可以使用WriteOnlyCollection.add_all()方法一次性将许多行与一个新的BankAudit对象关联起来：
>>> bank_audit = BankAudit() >>> session.add(bank_audit) >>> bank_audit.account_transactions.add_all(new_transactions) >>> session.commit() INSERT INTO audit DEFAULT VALUES [...] () INSERT INTO audit_transaction (audit_id, transaction_id) VALUES (?, ?) [...] [(1, 10), (1, 11), (1, 12)] COMMIT
另请参见
ORM 批量插入语句 - 在 ORM 查询指南中
多对多 - 在基本关系模式中
项目的批量更新和删除
类似于WriteOnlyCollection可以预先建立 WHERE 条件生成Select构造的方式，它也可以生成具有相同 WHERE 条件的Update和Delete构造，以允许针对大集合中的元素进行基于条件的 UPDATE 和 DELETE 语句。
一对多集合
就像插入（INSERT）一样，这个特性在一对多集合中最直接。
在下面的示例中，使用WriteOnlyCollection.update()方法生成一个 UPDATE 语句，针对集合中的元素，定位“amount”等于-800的行，并将200的数量添加到它们中：
>>> session.execute( ... existing_account.account_transactions.update() ... .values(amount=AccountTransaction.amount + 200) ... .where(AccountTransaction.amount == -800), ... ) BEGIN (implicit) UPDATE account_transaction SET amount=(account_transaction.amount + ?) WHERE ? = account_transaction.account_id AND account_transaction.amount = ? [...] (200, 1, -800) <...>
类似地，WriteOnlyCollection.delete()将生成一个 DELETE 语句，以相同的方式调用：
>>> session.execute( ... existing_account.account_transactions.delete().where( ... AccountTransaction.amount.between(0, 30) ... ), ... ) DELETE FROM account_transaction WHERE ? = account_transaction.account_id AND account_transaction.amount BETWEEN ? AND ? RETURNING id [...] (1, 0, 30) <...>
多对多集合
提示
这里的技术涉及到稍微高级的多表更新表达式。
对于多对多集合的批量更新和删除，为了使 UPDATE 或 DELETE 语句与父对象的主键相关联，关联表必须明确地成为 UPDATE/DELETE 语句的一部分，这要求后端包括对非标准 SQL 语法的支持，或者在构造 UPDATE 或 DELETE 语句时需要额外的显式步骤。
对于支持多表版本的 UPDATE 的后端，WriteOnlyCollection.update()方法应该可以在多对多集合上工作，就像下面的示例中对AccountTransaction对象进行的 UPDATE 一样，涉及多对多的BankAudit.account_transactions集合：
>>> session.execute( ... bank_audit.account_transactions.update().values( ... description=AccountTransaction.description + " (audited)" ... ) ... ) UPDATE account_transaction SET description=(account_transaction.description || ?) FROM audit_transaction WHERE ? = audit_transaction.audit_id AND account_transaction.id = audit_transaction.transaction_id RETURNING id [...] (' (audited)', 1) <...>
上述语句自动使用“UPDATE…FROM”语法，由 SQLite 和其他后端支持，在 WHERE 子句中命名附加的audit_transaction表。
要更新或删除多对多集合，其中不支持多表语法的情况下，多对多条件可以移动到 SELECT 中，例如可以与 IN 组合以匹配行。WriteOnlyCollection在这里仍然对我们有所帮助，因为我们使用WriteOnlyCollection.select()方法为我们生成此 SELECT，利用Select.with_only_columns()方法生成标量子查询：
>>> from sqlalchemy import update >>> subq = bank_audit.account_transactions.select().with_only_columns(AccountTransaction.id) >>> session.execute( ... update(AccountTransaction) ... .values(description=AccountTransaction.description + " (audited)") ... .where(AccountTransaction.id.in_(subq)) ... ) UPDATE account_transaction SET description=(account_transaction.description || ?) WHERE account_transaction.id IN (SELECT account_transaction.id FROM audit_transaction WHERE ? = audit_transaction.audit_id AND account_transaction.id = audit_transaction.transaction_id) RETURNING id [...] (' (audited)', 1) <...>
SqlAlchemy 2.0 中文文档（十三）（2）https://developer.aliyun.com/article/1562960
