A “related manager” is a manager used in a one-to-many or many-to-many\nrelated context. This happens in two cases:
\nThe “other side” of a ForeignKey relation.\nThat is:
from django.db import models\n\n\nclass Blog(models.Model):\n # ...\n pass\n\n\nclass Entry(models.Model):\n blog = models.ForeignKey(Blog, on_delete=models.CASCADE, null=True)\nIn the above example, the methods below will be available on\nthe manager blog.entry_set.
Both sides of a ManyToManyField relation
class Topping(models.Model):\n # ...\n pass\n\n\nclass Pizza(models.Model):\n toppings = models.ManyToManyField(Topping)\nIn this example, the methods below will be available both on\ntopping.pizza_set and on pizza.toppings.
Asynchronous version: aadd
Adds the specified model objects to the related object set.
\nExample:
\n>>> b = Blog.objects.get(id=1)\n>>> e = Entry.objects.get(id=234)\n>>> b.entry_set.add(e) # Associates Entry e with Blog b.\nIn the example above, in the case of a\nForeignKey relationship,\nQuerySet.update()\nis used to perform the update. This requires the objects to already be\nsaved.
You can use the bulk=False argument to instead have the related\nmanager perform the update by calling e.save().
Using add() with a many-to-many relationship, however, will not\ncall any save() methods (the bulk argument doesn’t exist), but\nrather create the relationships using QuerySet.bulk_create(). If you need to execute\nsome custom logic when a relationship is created, listen to the\nm2m_changed signal, which will\ntrigger pre_add and post_add actions.
Using add() on a relation that already exists won’t duplicate the\nrelation, but it will still trigger signals.
For many-to-many relationships add() accepts either model instances\nor field values, normally primary keys, as the *objs argument.
Use the through_defaults argument to specify values for the new\nintermediate model instance(s), if\nneeded. You can use callables as values in the through_defaults\ndictionary and they will be evaluated once before creating any\nintermediate instance(s).
Asynchronous version: acreate
Creates a new object, saves it and puts it in the related object set.\nReturns the newly created object:
\n>>> b = Blog.objects.get(id=1)\n>>> e = b.entry_set.create(\n... headline="Hello", body_text="Hi", pub_date=datetime.date(2005, 1, 1)\n... )\n\n# No need to call e.save() at this point -- it's already been saved.\nThis is equivalent to (but simpler than):
\n>>> b = Blog.objects.get(id=1)\n>>> e = Entry(blog=b, headline="Hello", body_text="Hi", pub_date=datetime.date(2005, 1, 1))\n>>> e.save(force_insert=True)\nNote that there’s no need to specify the keyword argument of the model\nthat defines the relationship. In the above example, we don’t pass the\nparameter blog to create(). Django figures out that the new\nEntry object’s blog field should be set to b.
Use the through_defaults argument to specify values for the new\nintermediate model instance, if\nneeded. You can use callables as values in the through_defaults\ndictionary.
Asynchronous version: aremove
Removes the specified model objects from the related object set:
\n>>> b = Blog.objects.get(id=1)\n>>> e = Entry.objects.get(id=234)\n>>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.\nSimilar to add(), e.save() is called in the example above\nto perform the update. Using remove() with a many-to-many\nrelationship, however, will delete the relationships using\nQuerySet.delete() which\nmeans no model save() methods are called; listen to the\nm2m_changed signal if you wish to\nexecute custom code when a relationship is deleted.
For many-to-many relationships remove() accepts either model\ninstances or field values, normally primary keys, as the *objs\nargument.
For ForeignKey objects, this method only\nexists if null=True. If the related field can’t be set to None\n(NULL), then an object can’t be removed from a relation without\nbeing added to another. In the above example, removing e from\nb.entry_set() is equivalent to doing e.blog = None, and because\nthe blog ForeignKey doesn’t have\nnull=True, this is invalid.
For ForeignKey objects, this method accepts\na bulk argument to control how to perform the operation.\nIf True (the default), QuerySet.update() is used.\nIf bulk=False, the save() method of each individual model\ninstance is called instead. This triggers the\npre_save and\npost_save signals and comes at the\nexpense of performance.
For many-to-many relationships, the bulk keyword argument doesn’t\nexist.
Asynchronous version: aclear
Removes all objects from the related object set:
\n>>> b = Blog.objects.get(id=1)\n>>> b.entry_set.clear()\nNote this doesn’t delete the related objects – it just disassociates\nthem.
\nJust like remove(), clear() is only available on\nForeignKeys where null=True and it also\naccepts the bulk keyword argument.
For many-to-many relationships, the bulk keyword argument doesn’t\nexist.
Asynchronous version: aset
Replace the set of related objects:
\n>>> new_list = [obj1, obj2, obj3]\n>>> e.related_set.set(new_list)\nThis method accepts a clear argument to control how to perform the\noperation. If False (the default), the elements missing from the\nnew set are removed using remove() and only the new ones are added.\nIf clear=True, the clear() method is called instead and the\nwhole set is added at once.
For ForeignKey objects, the bulk\nargument is passed on to add() and remove().
For many-to-many relationships, the bulk keyword argument doesn’t\nexist.
Note that since set() is a compound operation, it is subject to\nrace conditions. For instance, new objects may be added to the database\nin between the call to clear() and the call to add().
For many-to-many relationships set() accepts a list of either model\ninstances or field values, normally primary keys, as the objs\nargument.
Use the through_defaults argument to specify values for the new\nintermediate model instance(s), if\nneeded. You can use callables as values in the through_defaults\ndictionary and they will be evaluated once before creating any\nintermediate instance(s).