Referência de objetos relacionados

This document describes extra methods available on managers when used in a one-to-many or many-to-many related context. This happens in two cases:

• The “other side” of a ForeignKey relation. That is:

  class Reporter(models.Model):
      ...
  
  class Article(models.Model):
      reporter = models.ForeignKey(Reporter)
  

  In the above example, the methods below will be available on the manager reporter.article_set.

• Both sides of a ManyToManyField relation:

  class Topping(models.Model):
      ...
  
  class Pizza(models.Model):
      toppings = models.ManyToManyField(Topping)
  

  In this example, the methods below will be available both on topping.pizza_set and on pizza.toppings.

QuerySet.add(obj1[, obj2, ...])

Adiciona objeto model especificado para o conjunto de objetos relacionados.

Exemplo:

>>> b = Blog.objects.get(id=1)
>>> e = Entry.objects.get(id=234)
>>> b.entry_set.add(e) # Associa Entry e com Blog b.

QuerySet.create(**kwargs)

Cria um novo objeto, o salva e o coloca no conjunto de objetos relacionados. Retorna o novo objeto criado:

>>> b = Blog.objects.get(id=1)
>>> e = b.entry_set.create(
...     headline='Hello',
...     body_text='Hi',
...     pub_date=datetime.date(2005, 1, 1)
... )

# Não necessita chamar e.save() neste ponto -- ele já está salvo.

Isto é equivalente (mas muito mais simples):

>>> 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)

Note que não há necessidade de especificar argumentos nomeados para o model que define a realação. No exemplo acima, nós não passamos o parâmetro blog para create(). O Django descobre que o novo campo blog do objeto Entry deve ser definido como b.

QuerySet.remove(obj1[, obj2, ...])

Remove o model especificado do conjunto de objetos relacionados:

>>> b = Blog.objects.get(id=1)
>>> e = Entry.objects.get(id=234)
>>> b.entry_set.remove(e) # Disassocia Entry e de Blog b.

A fim de previnir inconsistências no banco de dados, este método somente existe em objetos ForeignKey onde null=True. Se o campo relacionado não puder ser None (NULL), então o objeto não pode ser removido de uma relação sem ser adicionado em outra. No exemplo acima, removendo e de b.entry_set() é equivalente a fazer e.blog = None, e por isso o ForeignKey blog não tem null=True, isto é inválido.

QuerySet.clear()

Revove todos os objetos de um conjunto de objetos relacionados:

>>> b = Blog.objects.get(id=1)
>>> b.entry_set.clear()

Note que isto não deleta os objetos relacionados – somente os desassocia.

Assim como remove(), clear() é somente disponível em ForeignKeys onde null=True.