---
title: "Référence des objets liés"
version: 1.9
locale: fr
source: https://docs.djangoproject.com/fr/1.9/ref/models/relations/
canonical: https://djangodocs.dev/fr/1.9/ref/models/relations/
---
# Référence des objets liés

#### `class RelatedManager`

Un gestionnaire de liaison (« related manager ») est un gestionnaire utilisé dans un contexte de champ lié un-à-plusieurs ou plusieurs-à-plusieurs. Cela se produit dans deux cas :

- Le « côté opposé » d’une relation [`ForeignKey`](/fr/1.9/ref/models/fields/#django.db.models.ForeignKey). C’est-à-dire :

  ```
  from django.db import models

  class Reporter(models.Model):
      # ...
      pass

  class Article(models.Model):
      reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)
  ```

  Dans l’exemple ci-dessus, les méthodes ci-dessous seront disponibles pour le gestionnaire `reporter.article_set`.
- Les deux côtés d’une relation [`ManyToManyField`](/fr/1.9/ref/models/fields/#django.db.models.ManyToManyField):

  ```
  class Topping(models.Model):
      # ...
      pass

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

  Dans cet exemple, les méthodes ci-dessous seront disponibles à la fois pour `topping.pizza_set` et pour `pizza.toppings`.

#### `add(*objs, bulk=True)`

Ajoute les objets modèles indiqués à l’ensemble des objets liés.

Exemple :

```
>>> b = Blog.objects.get(id=1)
>>> e = Entry.objects.get(id=234)
>>> b.entry_set.add(e) # Associates Entry e with Blog b.
```

Dans l’exemple ci-dessus, dans le cas d’une relation [`ForeignKey`](/fr/1.9/ref/models/fields/#django.db.models.ForeignKey), [`QuerySet.update()`](/fr/1.9/ref/models/querysets/#django.db.models.query.QuerySet.update) est utilisée pour effectuer la mise à jour. Ceci nécessite que les objets soient déjà enregistrés.

Vous pouvez utiliser le paramètre `bulk=False` pour que la mise à jour soit effectuée plutôt par le gestionnaire de la relation en appelant `e.save()`.

Cependant, l’emploi de `add()` avec une relation plusieurs-à-plusieurs n’appelle aucune méthode `save()` mais crée plutôt les relations en utilisant [`QuerySet.bulk_create()`](/fr/1.9/ref/models/querysets/#django.db.models.query.QuerySet.bulk_create). Si vous avez besoin de faire exécuter une certaine logique personnalisée lors de la création d’une relation, faites-le dans une fonction à l’écoute du signal [`m2m_changed`](/fr/1.9/ref/signals/#django.db.models.signals.m2m_changed).

> **Changed in Django 1.9**
>
> Le paramètre `bulk` a été ajouté. Dans les anciennes versions, les mises à jour de clé étrangère se faisaient toujours avec `save()`. Indiquez `bulk=False` si vous avez besoin de l’ancien comportement.

#### `create(**kwargs)`

Crée un nouvel objet, l’enregistre et le place dans l’ensemble des objets liés. Renvoie l’objet nouvellement créé :

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

C’est équivalent à (mais beaucoup plus simple) :

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

Notez qu’il n’y a pas besoin de fournir le paramètre nommé du modèle qui définit la relation. Dans l’exemple ci-dessus, nous ne transmettons pas le paramètre `blog` à `create()`. Django réalise lui-même que le champ `blog` du nouvel objet `Entry` doit recevoir la valeur `b`.

#### `remove(*objs)`

Enlève les objets modèles indiqués de l’ensemble des objets liés :

```
>>> b = Blog.objects.get(id=1)
>>> e = Entry.objects.get(id=234)
>>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.
```

Comme avec [`add()`](#django.db.models.fields.related.RelatedManager.add), on appelle `e.save()` dans l’exemple ci-dessus pour effectuer la mise à jour. Cependant, l’emploi de `remove()` avec une relation plusieurs-à-plusieurs supprime les relations avec [`QuerySet.delete()`](/fr/1.9/ref/models/querysets/#django.db.models.query.QuerySet.delete), ce qui signifie qu’aucune méthode `save()` n’est appelée. Si vous avez besoin de faire exécuter du code personnalisé lors de la suppression d’une relation, faites-le dans une fonction à l’écoute du signal [`m2m_changed`](/fr/1.9/ref/signals/#django.db.models.signals.m2m_changed).

Pour les objets [`ForeignKey`](/fr/1.9/ref/models/fields/#django.db.models.ForeignKey), cette méthode existe seulement quand `null=True`. Si le champ lié ne peut pas recevoir la valeur `None` (`NULL`), alors un objet ne peut pas être enlevé d’une relation sans être ajouté à une autre. Dans l’exemple ci-dessus, enlever `e` de `b.entry_set()` est l’équivalent de la définition `e.blog = None`, et comme la clé [`ForeignKey`](/fr/1.9/ref/models/fields/#django.db.models.ForeignKey) `blog` n’a pas l’option `null=True`, ce n’est pas valide.

Pour les objets [`ForeignKey`](/fr/1.9/ref/models/fields/#django.db.models.ForeignKey), cette méthode accepte un paramètre `bulk` pour contrôler comment effectuer l’opération. Avec `True` (valeur par défaut), c’est `QuerySet.update()` qui est utilisé. Avec `bulk=False`, c’est plutôt la méthode `save()` de chaque instance de modèle individuelle qui est appelée. Cela déclenche les signaux [`pre_save`](/fr/1.9/ref/signals/#django.db.models.signals.pre_save) et [`post_save`](/fr/1.9/ref/signals/#django.db.models.signals.post_save) au détriment d’une perte de performance.

#### `clear()`

Enlève tous les objets de l’ensemble des objets liés :

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

Notez que cela ne supprime pas les objets liés, il ne fait que les dissocier.

Tout comme `remove()`, `clear()` n’est disponible pour un champ [`ForeignKey`](/fr/1.9/ref/models/fields/#django.db.models.ForeignKey) que lorsque `null=True` et il accepte également le paramètre nommé `bulk`.

#### `set(objs, bulk=True, clear=False)`

> **New in Django 1.9**

Remplace l’ensemble des objets liés :

```
>>> new_list = [obj1, obj2, obj3]
>>> e.related_set.set(new_list)
```

Cette méthode accepte un paramètre `clear` pour contrôler le fonctionnement de l’opération. Si `False` (par défaut), les éléments manquants dans le nouvel ensemble sont supprimés avec `remove()` et seuls les nouveaux sont ajoutés. Si `clear=True`, la méthode `clear()` est appelée à la place et l’ensemble est ajouté en une seule fois.

Le paramètre `bulk` est transmis à [`add()`](#django.db.models.fields.related.RelatedManager.add).

Notez que dans la mesure où `set()` est une opération composée, elle est sujette aux situations de concurrence. Par exemple, de nouveaux objets pourraient être ajoutés à la base de données entre l’appel `clear()` et l’appel `add()`.

> **Note**
>
> Notez que `add()`, `create()`, `remove()`, `clear()` et `set()` appliquent tous immédiatement les modifications de base de données pour tous les types de champs de relation. En d’autres termes, il n’est pas nécessaire d’appeler `save()` ni d’un côté de la relation, ni de l’autre.
>
> Also, if you are using [an intermediate model](/fr/1.9/topics/db/models/#intermediary-manytomany) for a many-to-many relationship, then the
> `add()`, `create()`, `remove()`, and `set()` methods are
> disabled.

## Attribution directe

Un ensemble d’objets liés peut être remplacé en vrac en une seule opération en attribuant un nouvel ensemble d’objets itérable :

```
>>> new_list = [obj1, obj2, obj3]
>>> e.related_set = new_list
```

Si la relation de clé étrangère possède `null=True`, le gestionnaire de la relation efface premièrement toute liaison avec des objets existants avant d’ajouter le contenu de `new_list`. Sinon, les objets de `new_list` seraient ajoutés à l’ensemble existant d’objets liés.

> **Changed in Django 1.9**
>
> Dans les versions antérieures, l’affectation directe procédait à une opération d’effacement `clear()` suivie d’une opération `add()`. Dorénavant, elle appelle `set()` avec le paramètre nommé `clear=False`.