Un «administrador relacionado» es un administrador utilizado en un contexto relacionado uno-a-muchos o muchos-a-muchos. Esto ocurre en dos casos:
El «lado contrario» de una relación ForeignKey. Es decir:
from django.db import models
class Blog(models.Model):
# ...
pass
class Entry(models.Model):
blog = models.ForeignKey(Blog, on_delete=models.CASCADE, null=True)
En el ejemplo anterior, los métodos a continuación estarán disponibles en el administrador blog.entry_set.
Ambos lados de una relación ManyToManyField
class Topping(models.Model):
# ...
pass
class Pizza(models.Model):
toppings = models.ManyToManyField(Topping)
En este ejemplo, los métodos a continuación estarán disponibles tanto en topping.pizza_set como en pizza.toppings.
Versión asíncrona: aadd
Agrega los objetos de modelo especificados al conjunto relacionado.
Ejemplo:
>>> b = Blog.objects.get(id=1)
>>> e = Entry.objects.get(id=234)
>>> b.entry_set.add(e) # Associates Entry e with Blog b.
En el ejemplo anterior, en el caso de una relación ForeignKey, se utiliza la función QuerySet.update() para realizar la actualización. Esto requiere que los objetos ya estén guardados.
Puedes utilizar el argumento bulk=False en su lugar, para que el administrador relacionado realice la actualización llamando a e.save().
Al usar add() con una relación muchos-a-muchos, sin embargo, no se llamarán métodos save(), sino que se crearán las relaciones utilizando QuerySet.bulk_create(). Si necesitas ejecutar lógica personalizada cuando se crea una relación, escucha el señal m2m_changed, que disparará acciones pre_add y post_add.
Usar add() en una relación que ya existe no duplicará la relación, pero aún así disparará señales.
Para relaciones muchos-a-muchos, add() acepta tanto instancias de modelo como valores del campo, normalmente claves primarias, como el argumento *objs.
Utiliza el argumento through_defaults para especificar valores para la nueva instancia(s) modelo intermedio , si es necesario. Puedes utilizar llamables como valores en el diccionario through_defaults y se evaluarán una vez antes de crear cualquier instancia(s) intermedia(s).
Versión asíncrona: acreate
Crea un nuevo objeto, lo guarda y lo coloca en el conjunto de objetos relacionados. Devuelve el objeto creado recientemente:
>>> 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.
Esto es equivalente a (pero más simple que):
>>> 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)
Ten en cuenta que no hay necesidad de especificar el argumento clave del modelo que define la relación. En el ejemplo anterior, no pasamos el parámetro blog a create(). Django determina que el campo blog del nuevo objeto Entry debe estar configurado para b.
Utiliza el argumento through_defaults para especificar valores para la instancia de modelo intermedio nueva, si es necesario. Puedes utilizar llamables como valores en el diccionario through_defaults.
Versión asíncrona: aremove
Elimina los objetos del modelo especificados del conjunto de objetos relacionados:
>>> b = Blog.objects.get(id=1)
>>> e = Entry.objects.get(id=234)
>>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.
Similar a add(), e.save() se llama en el ejemplo anterior para realizar la actualización. Utilizar remove() con una relación muchos-a-muchos, sin embargo, eliminará las relaciones utilizando QuerySet.delete() lo que significa que no se llamarán los métodos de modelo save(), escucha el m2m_changed si deseas ejecutar código personalizado cuando una relación es eliminada.
Para las relaciones muchos-a-muchos, remove() acepta tanto instancias del modelo como valores del campo, normalmente claves primarias, como el argumento *objs.
Para objetos ForeignKey, este método solo existe si null=True. Si el campo relacionado no puede estar configurado para None (NULL), entonces un objeto no se puede eliminar de una relación sin ser agregado a otra. En el ejemplo anterior, eliminar e del conjunto de objetos relacionados b.entry_set() es equivalente a hacer e.blog = None, y porque el campo blog ForeignKey no tiene null=True, esto es inválido.
Los textos traducidos son:
Para las relaciones muchos-a-muchos, el argumento bulk no existe.
Versión asíncrona: aclear
Elimina todos los objetos del conjunto relacionado:
>>> b = Blog.objects.get(id=1)
>>> b.entry_set.clear()
Ten en cuenta que esto no elimina los objetos relacionados – solo los desasocia.
Al igual que remove(), clear() está disponible sólo para ForeignKeys donde null=True y también acepta el argumento bulk.
Para las relaciones muchos-a-muchos, el argumento bulk no existe.
Versión asíncrona: aset
Reemplaza el conjunto de objetos relacionados:
>>> new_list = [obj1, obj2, obj3]
>>> e.related_set.set(new_list)
Este método acepta un argumento clear para controlar cómo realizar la operación. Si False (el valor por defecto), se eliminan los elementos faltantes del nuevo conjunto utilizando remove() y solo se agregan los nuevos. Si clear=True, se llama en lugar de eso el método clear() y se agrega todo el conjunto a la vez.
Para los objetos ForeignKey, el argumento bulk se pasa a add() y remove().
Para las relaciones muchos-a-muchos, el argumento bulk no existe.
Ten en cuenta que ya que set() es una operación compuesta, está sujeta a condiciones de carrera. Por ejemplo, nuevos objetos pueden ser agregados a la base de datos entre la llamada a clear() y la llamada a add().
Para las relaciones muchos-a-muchos, set() acepta una lista de instancias del modelo o valores de campo, normalmente claves primarias, como el argumento objs.
Utiliza el argumento through_defaults para especificar valores para la nueva instancia(s) modelo intermedio , si es necesario. Puedes utilizar llamables como valores en el diccionario through_defaults y se evaluarán una vez antes de crear cualquier instancia(s) intermedia(s).
Nota
Nota que add(), aadd(), create(), acreate(), remove(), aremove(), clear(), aclear(), set(), y aset() aplican cambios en la base de datos inmediatamente para todos los tipos de campos relacionados. En otras palabras, no es necesario llamar a save()/asave() en ninguno de los extremos de la relación.
Si utilizas prefetch_related(), los métodos add(), aadd(), remove(), aremove(), clear(), aclear(), set(), y aset() vacían el caché prefetcheado.
may 31, 2026