..
.. META INFORMATION OF TRANSLATION
..
..   $TranslationStatus: Done, waiting for revision. $
..   $OriginalRevision: 11348 $
..   $TranslationAuthors: Robson Mendonça $
..
.. INFO OF THIS FILE (DO NOT EDIT! UPDATED BY SUBVERSION)
..
..   $HeadURL$
..   $LastChangedRevision$
..   $LastChangedBy$
..   $LastChangedDate$
..

.. _ref-models-relations:

==================================
Referência de objetos relacionados
==================================

.. currentmodule:: django.db.models

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``.

.. method:: 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.

.. method:: 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``.

.. method:: 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.

.. method:: 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
    ``ForeignKey``\s onde ``null=True``.