Please take a few minutes to complete the
2024 Django Developers Survey.
Your feedback will help guide future efforts.
RelatedManager
¶“关系管理器”是一个用于处理一对多和多对多关系的管理器。在以下两种情况用到:
ForeignKey
关系的“另一边”。即:
from django.db import models
class Blog(models.Model):
# ...
pass
class Entry(models.Model):
blog = models.ForeignKey(Blog, on_delete=models.CASCADE, null=True)
In the above example, the methods below will be available on
the manager blog.entry_set
.
ManyToManyField
关系的两边:
class Topping(models.Model):
# ...
pass
class Pizza(models.Model):
toppings = models.ManyToManyField(Topping)
在这个例子中,下文列出的方法在 topping.pizza_set
和 pizza.toppings
中均可用。
add
(*objs, bulk=True, through_defaults=None)¶将指定的模型对象加入关联对象集。
举例:
>>> b = Blog.objects.get(id=1)
>>> e = Entry.objects.get(id=234)
>>> b.entry_set.add(e) # Associates Entry e with Blog b.
上述例子中,由于有 ForeignKey
关系,才可以使用 QuerySet.update()
更新数据。这要求对象事先已经被保存在数据库内了。
你可以使用 bulk=False
参数让关系管理器通过调用 e.save()
来执行更新操作。
但是,在多对多关系中使用 add()
,不会调用任何 save()
方法(bulk
参数不存在),而是使用 QuerySet.bulk_create()
创建关系。如果需要在创建关系时执行一些自定义逻辑,可以监听 m2m_changed
信号,它将触发 pre_add
和 post_add
动作。
在已经存在的关系上使用 add()
不会重复关系,但仍然会触发信号。
对于多对多关系,add()
接受模型实例或字段值,通常是主键,作为 *objs
参数。
如果需要的话,使用 through_defaults
参数为新的 中间模型 实例指定值。你可以使用可调用对象作为 through_defaults
字典中的值,它们将在创建任何中间实例之前被执行一次。
create
(through_defaults=None, **kwargs)¶创建一个新的对象,将其保存并放入关联对象集。返回新创建的对象:
>>> b = Blog.objects.get(id=1)
>>> e = b.entry_set.create(
... headline='Hello',
... body_text='Hi',
... pub_date=datetime.date(2005, 1, 1)
... )
# No need to call e.save() at this point -- it's already been saved.
这相当于(但更简单):
>>> b = Blog.objects.get(id=1)
>>> e = Entry(
... blog=b,
... headline='Hello',
... body_text='Hi',
... pub_date=datetime.date(2005, 1, 1)
... )
>>> e.save(force_insert=True)
无需指定定义了模型间关系的关键字参数。在上述例子中,我们并未向 create()
传递参数 blog
。Django 知道要将新 Entry
对象的 blog
字段设置为 b
。
如果需要的话,使用 through_defaults
参数为新的 中间模型 实例指定值。你可以使用可调用对象作为 through_defaults
字典中的值。
remove
(*objs, bulk=True)¶从关联对象集中删除指定的模型对象:
>>> b = Blog.objects.get(id=1)
>>> e = Entry.objects.get(id=234)
>>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.
与 add()
类似,在上面的例子中调用 e.save()
来执行更新。但是,对多对多关系使用 remove()
,将使用 QuerySet.delete()
删除关系,这意味着没有调用模型 save()
方法;如果想在删除关系时执行自定义代码,请监听 m2m_changed
信号。
对于多对多关系,remove()
接受模型实例或字段值,通常是主键,作为 *objs
参数。
对于 ForeignKey
对象,只有当 null=True
时,这个方法才存在。如果相关字段不能设置为 None
(NULL
),那么一个对象就不能从一个关系中删除而不被添加到另一个关系中。在上面的例子中,从 b.entry_set()
中删除 e
相当于做了 e.blog = None
,由于 blog
ForeignKey`
没有 null=True
,所以这是无效的。
对于 ForeignKey
对象,这个方法接受一个 bulk
参数来控制如何执行操作。如果 True
(默认),则使用 QuerySet.update()
。如果 bulk=False
,则调用每个单独模型实例的 save()
方法。这将触发 pre_save
和 post_save
信号,并以牺牲性能为代价。
对于多对多关系,bulk
关键字参数不存在。
clear
(bulk=True)¶从关联对象集中删除所有对象:
>>> b = Blog.objects.get(id=1)
>>> b.entry_set.clear()
请注意,这并不会删除相关的对象——只是将它们脱离关联。
和 remove()
一样,clear()
只在 ForeignKey
上可用,其中 null=True
,而且它还接受 bulk
关键字参数。
对于多对多关系,bulk
关键字参数不存在。
set
(objs, bulk=True, clear=False, through_defaults=None)¶替换一组关联对象:
>>> new_list = [obj1, obj2, obj3]
>>> e.related_set.set(new_list)
本方法接受一个 clear
参数来控制如何执行操作。如果 False
(默认),则使用 remove()
删除新集合中缺少的元素,只添加新元素。如果 clear=True
,则调用 clear()
方法,一次性添加整个集合。
对于 ForeignKey
对象,bulk
参数被传递给 add()
和 remove()
。
对于多对多关系,bulk
关键字参数不存在。
请注意,由于 set()
是一个复合操作,它受到竞争条件的影响。例如,在调用 clear()
和调用 add()
之间可能会向数据库中添加新的对象。
对于多对多关系,set()
接受一个模型实例或字段值的列表,通常是主键,作为 objs
参数。
如果需要的话,使用 through_defaults
参数为新的 中间模型 实例指定值。你可以使用可调用对象作为 through_defaults
字典中的值,它们将在创建任何中间实例之前被执行一次。
备注
请注意,add()
、create()
、remove()
、clear()
和 set()
都会对所有类型的相关字段立即应用数据库变化。换句话说,没有必要在关系的任何一端调用 save()
。
如果使用 prefetch_related()
,add()
、remove()
、clear()
和 set()
方法会清除预取缓存。
_meta
API
离线 (Django 4.0):
HTML |
PDF |
ePub
由 Read the Docs 提供。
© 2005-2024 Django Software Foundation and individual contributors. Django is a registered trademark of the Django Software Foundation.