Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Les relations entre entités (OneToMany, ManyToOne, ManyToMany)

Cette leçon modélise des données liées avec TypeORM : un groupe a plusieurs stagiaires (ManyToOne et OneToMany), un stagiaire a plusieurs notes enregistrées en cascade, et stagiaires et compétences so...

0 chapitres 0 QCM Accès gratuit
Les relations entre entités (OneToMany, ManyToOne, ManyToMany)

À propos de ce cours

Cette leçon modélise des données liées avec TypeORM : un groupe a plusieurs stagiaires (ManyToOne et OneToMany), un stagiaire a plusieurs notes enregistrées en cascade, et stagiaires et compétences sont liés par une table de jointure (ManyToMany et JoinTable). Les contraintes de clés étrangères réellement créées sont affichées, puis l'exécution montre l'enregistrement en cascade, la lecture avec ou sans relations et le SQL des jointures, le filtrage sur une relation, et le comportement des options onDelete SET NULL et CASCADE. La leçon aborde aussi eager, lazy et le problème N+1. Activités corrigées.

Objectifs de la leçon

  • Modéliser une relation un-à-plusieurs avec @ManyToOne et @OneToMany.
  • Modéliser une relation plusieurs-à-plusieurs avec @ManyToMany et @JoinTable.
  • Enregistrer des données liées et utiliser la cascade.
  • Charger les relations et filtrer sur une relation.
  • Choisir le comportement à la suppression (onDelete).

Modèle relationnel de l'exemple

Groupes, stagiaires, notes et compétences.

Les types de relations
RelationExempleEn baseDécorateurs
plusieurs-à-un / un-à-plusieursN stagiaires dans 1 groupecolonne groupe_id dans stagiaires@ManyToOne (+ @JoinColumn) côté stagiaire, @OneToMany côté groupe
plusieurs-à-plusieursstagiaires ↔ compétencestable de jointure stagiaires_competences@ManyToMany des deux côtés, @JoinTable d'un seul
un-à-unun stagiaire, un profilcolonne unique profil_id@OneToOne + @JoinColumn d'un côté
Les entités

📄 src/groupes/groupe.entity.ts

import { Column, Entity, OneToMany, PrimaryGeneratedColumn } from 'typeorm';
import { Stagiaire } from './stagiaire.entity';

@Entity('groupes')
export class Groupe {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ length: 10, unique: true })
  code: string;

  @Column({ length: 80 })
  intitule: string;

  @Column({ type: 'smallint', default: 20 })
  capacite: number;

  @OneToMany(() => Stagiaire, (stagiaire) => stagiaire.groupe)     // côté « un » : pas de colonne
  stagiaires: Stagiaire[];
}

📄 src/stagiaires/stagiaire.entity.ts

import {
  Column, Entity, JoinColumn, JoinTable, ManyToMany, ManyToOne, OneToMany, PrimaryGeneratedColumn,
} from 'typeorm';
import { Competence } from './competence.entity';
import { Groupe } from './groupe.entity';
import { Note } from './note.entity';

@Entity('stagiaires')
export class Stagiaire {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ length: 50 })
  nom: string;

  // ── N stagiaires → 1 groupe : la clé étrangère est ICI
  @ManyToOne(() => Groupe, (groupe) => groupe.stagiaires, { nullable: true, onDelete: 'SET NULL' })
  @JoinColumn({ name: 'groupe_id' })
  groupe: Groupe | null;

  @Column({ name: 'groupe_id', nullable: true })    // la clé étrangère aussi exposée comme simple nombre
  groupeId: number | null;

  // ── 1 stagiaire → N notes (cascade : les notes sont enregistrées avec le stagiaire)
  @OneToMany(() => Note, (note) => note.stagiaire, { cascade: ['insert'] })
  notes: Note[];

  // ── N stagiaires ↔ N compétences : table de jointure
  @ManyToMany(() => Competence, (competence) => competence.stagiaires)
  @JoinTable({
    name: 'stagiaires_competences',
    joinColumn: { name: 'stagiaire_id' },
    inverseJoinColumn: { name: 'competence_id' },
  })
  competences: Competence[];
}

📄 src/notes/note.entity.ts

import { Column, Entity, JoinColumn, ManyToOne, PrimaryGeneratedColumn } from 'typeorm';
import { Stagiaire } from './stagiaire.entity';

@Entity('notes')
export class Note {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ length: 30 })
  matiere: string;

  @Column({ type: 'decimal', precision: 4, scale: 2, transformer: { to: (v: number) => v, from: (v: string) => Number(v) } })
  valeur: number;

  @ManyToOne(() => Stagiaire, (stagiaire) => stagiaire.notes, { onDelete: 'CASCADE' })   // note supprimée avec le stagiaire
  @JoinColumn({ name: 'stagiaire_id' })
  stagiaire: Stagiaire;
}

📄 src/competences/competence.entity.ts

import { Column, Entity, ManyToMany, PrimaryGeneratedColumn } from 'typeorm';
import { Stagiaire } from './stagiaire.entity';

@Entity('competences')
export class Competence {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ length: 40, unique: true })
  libelle: string;

  @ManyToMany(() => Stagiaire, (stagiaire) => stagiaire.competences)
  stagiaires: Stagiaire[];
}
  • () => Groupe: une fonction plutôt que la classe directement, car les deux fichiers s'importent mutuellement (même raison que forwardRef, leçon 7.6).
  • Le second argument ((groupe) => groupe.stagiaires) désigne la propriété inverse: les deux côtés décrivent la même relation.
  • @JoinColumn se place du côté @ManyToOne, celui qui possède la clé étrangère ; il permet de choisir son nom.
  • Déclarer aussi groupeId comme simple colonne est pratique : on peut lire ou affecter l'identifiant sans charger le groupe.
L'exécution

📄 src/main.ts (extrait)


  const source = app.get(DataSource);
  const groupes = source.getRepository(Groupe);
  const stagiaires = source.getRepository(Stagiaire);
  const competences = source.getRepository(Competence);
  const afficher = (titre: string, v: unknown) => console.log(`\n▶ ${titre}\n` + JSON.stringify(v, null, 1).replace(/\n\s*/g, ' '));

  for (const t of ['stagiaires', 'notes', 'stagiaires_competences']) {
    const [r] = await source.query(`SHOW CREATE TABLE ${t}`);
    console.log(r['Create Table'].split('\n').filter((l: string) => /CONSTRAINT|CREATE TABLE/.test(l)).join('\n'));
  }

  // 1. Créer des données liées
  const [dev101, dev102] = await groupes.save([
    { code: 'DEV101', intitule: 'Développement web 1', capacite: 20 },
    { code: 'DEV102', intitule: 'Développement web 2', capacite: 18 },
  ]);
  const [html, css, js] = await competences.save([{ libelle: 'HTML' }, { libelle: 'CSS' }, { libelle: 'JavaScript' }]);

  console.log('\n▶ Enregistrement d\'un stagiaire avec son groupe, ses compétences et ses notes (cascade)');
  await stagiaires.save({
    nom: 'Ben Ali', groupe: dev101, competences: [html, css],
    notes: [{ matiere: 'SQL', valeur: 15 }, { matiere: 'JS', valeur: 12.5 }],
  });
  await stagiaires.save({ nom: 'Trabelsi', groupeId: dev101.id, competences: [js], notes: [{ matiere: 'SQL', valeur: 9 }] });
  await stagiaires.save({ nom: 'Gharbi', groupe: dev102, competences: [html, css, js] });

  // 2. Lire sans / avec relations
  afficher('find() sans relations', await stagiaires.find({ where: { nom: 'Ben Ali' } }));
  afficher('find() avec relations', await stagiaires.find({
    where: { nom: 'Ben Ali' },
    relations: { groupe: true, competences: true, notes: true },
  }));
  afficher('Un groupe et ses stagiaires (OneToMany)', await groupes.findOne({
    where: { code: 'DEV101' }, relations: { stagiaires: true }, order: { stagiaires: { nom: 'ASC' } },
  }));
  afficher('Filtrer sur une relation : stagiaires qui ont la compétence CSS', await stagiaires.find({
    where: { competences: { libelle: 'CSS' } }, select: { id: true, nom: true },
  }));

  // 3. Suppressions et contraintes
  await groupes.delete({ code: 'DEV102' });
  afficher('Après suppression du groupe DEV102 (ON DELETE SET NULL)', await stagiaires.findOne({ where: { nom: 'Gharbi' }, relations: { groupe: true } }));
  await stagiaires.delete({ nom: 'Ben Ali' });
  afficher('Notes restantes après suppression de Ben Ali (ON DELETE CASCADE)', await source.getRepository(Note).find({ relations: { stagiaire: true } }));

Résultat réellement obtenu :

CREATE TABLE `stagiaires` (
  CONSTRAINT `FK_ba2a66ec7f5e8b4b0cb0feefa98` FOREIGN KEY (`groupe_id`) REFERENCES `groupes` (`id`) ON DELETE SET NULL ON UPDATE NO ACTION
CREATE TABLE `notes` (
  CONSTRAINT `FK_a4cd75e56913d5d899ae5be3576` FOREIGN KEY (`stagiaire_id`) REFERENCES `stagiaires` (`id`) ON DELETE CASCADE ON UPDATE NO ACTION
CREATE TABLE `stagiaires_competences` (
  CONSTRAINT `FK_7f59949121c50f7024e0a298fd3` FOREIGN KEY (`stagiaire_id`) REFERENCES `stagiaires` (`id`) ON DELETE CASCADE ON UPDATE CASCADE,
  CONSTRAINT `FK_b261087b07c4d7e262132f68d6e` FOREIGN KEY (`competence_id`) REFERENCES `competences` (`id`) ON DELETE CASCADE ON UPDATE CASCADE

▶ Enregistrement d'un stagiaire avec son groupe, ses compétences et ses notes (cascade)
  SQL> START TRANSACTION
  SQL> INSERT INTO `stagiaires`(`id`, `nom`, `groupe_id`) VALUES (DEFAULT, ?, ?) -- ["Ben Ali",1]
  SQL> INSERT INTO `notes`(`id`, `matiere`, `valeur`, `stagiaire_id`) VALUES (DEFAULT, ?, ?, ?) -- ["SQL",15,1]
  SQL> INSERT INTO `notes`(`id`, `matiere`, `valeur`, `stagiaire_id`) VALUES (DEFAULT, ?, ?, ?) -- ["JS",12.5,1]
  SQL> INSERT INTO `stagiaires_competences`(`stagiaire_id`, `competence_id`) VALUES (?, ?), (?, ?) -- [1,1,1,2]
  SQL> COMMIT

▶ find() sans relations
[ { "id": 1, "nom": "Ben Ali", "groupeId": 1 } ]
  SQL> SELECT `Stagiaire`.`id` AS `Stagiaire_id`, `Stagiaire`.`nom` AS `Stagiaire_nom`, `Stagiaire`.`groupe_id` AS `Stagiaire_groupe_id`, `Stagiaire__Stagiaire_groupe`.`id` AS `Stagiaire__Stagiaire_groupe_id`, `Stagiaire__Stagiaire_groupe`.`code` AS `Stagiaire__Stagiaire_groupe_code`, `Stagiaire__Stagiaire_groupe`.`intitule` AS `Stagiaire__Stagiaire_groupe_intitule`, `Stagiaire__Stagiaire_groupe`.`capacite` AS `Stagiaire__Stagiaire_groupe_capacite`, `Stagiaire__Stagiaire_competences`.`id` AS `Stagiaire__Stagiaire_competences_id`, `Stagiaire__Stagiaire_competences`.`libelle` AS `Stagiaire__Stagiaire_competences_libelle`, `Stagiaire__Stagiaire_notes`.`id` AS `Stagiaire__Stagiaire_notes_id`, `Stagiaire__Stagiaire_notes`.`matiere` AS `Stagiaire__Stagiaire_notes_matiere`, `Stagiaire__Stagiaire_notes`.`valeur` AS `Stagiaire__Stagiaire_notes_valeur`, `Stagiaire__Stagiaire_notes`.`stagiaire_id` AS `Stagiaire__Stagiaire_notes_stagiaire_id` FROM `stagiaires` `Stagiaire` LEFT JOIN `groupes` `Stagiaire__Stagiaire_groupe` ON `Stagiaire__Stagiaire_groupe`.`id`=`Stagiaire`.`groupe_id`  LEFT JOIN `stagiaires_competences` `Stagiaire_Stagiaire__Stagiaire_competences` ON `Stagiaire_Stagiaire__Stagiaire_competences`.`stagiaire_id`=`Stagiaire`.`id` LEFT JOIN `competences` `Stagiaire__Stagiaire_competences` ON `Stagiaire__Stagiaire_competences`.`id`=`Stagiaire_Stagiaire__Stagiaire_competences`.`competence_id`  LEFT JOIN `notes` `Stagiaire__Stagiaire_notes` ON `Stagiaire__Stagiaire_notes`.`stagiaire_id`=`Stagiaire`.`id` WHERE ((`Stagiaire`.`nom` = ?)) -- ["Ben Ali"]

▶ find() avec relations
[ { "id": 1, "nom": "Ben Ali", "groupe": { "id": 1, "code": "DEV101", "intitule": "Développement web 1", "capacite": 20 }, "groupeId": 1, "notes": [ { "id": 1, "matiere": "SQL", "valeur": 15 }, { "id": 2, "matiere": "JS", "valeur": 12.5 } ], "competences": [ { "id": 1, "libelle": "HTML" }, { "id": 2, "libelle": "CSS" } ] } ]

▶ Un groupe et ses stagiaires (OneToMany)
{ "id": 1, "code": "DEV101", "intitule": "Développement web 1", "capacite": 20, "stagiaires": [ { "id": 1, "nom": "Ben Ali", "groupeId": 1 }, { "id": 2, "nom": "Trabelsi", "groupeId": 1 } ] }

▶ Filtrer sur une relation : stagiaires qui ont la compétence CSS
[ { "id": 1, "nom": "Ben Ali" }, { "id": 3, "nom": "Gharbi" } ]

▶ Après suppression du groupe DEV102 (ON DELETE SET NULL)
{ "id": 3, "nom": "Gharbi", "groupe": null, "groupeId": null }

▶ Notes restantes après suppression de Ben Ali (ON DELETE CASCADE)
[ { "id": 3, "matiere": "SQL", "valeur": 9, "stagiaire": { "id": 2, "nom": "Trabelsi", "groupeId": 1 } } ]

Les lignes SQL> sont les requêtes réellement envoyées par TypeORM (option logging). Pour la lisibilité, elles ne sont affichées que pour certaines opérations.

Ce qu'il faut observer
  1. Les contraintes créées: FOREIGN KEY (groupe_id) … ON DELETE SET NULL, … ON DELETE CASCADE pour les notes, et deux clés étrangères dans la table de jointure.
  2. Un seul save() a produit quatre requêtes dans une transaction : le stagiaire, ses deux notes (grâce à cascade: ['insert']) et les liens vers ses compétences. On peut fournir l'objet groupe ou simplement groupeId (deuxième stagiaire).
  3. Sans relations, find() ne charge que la table stagiaires: pas de propriété groupe ni notes dans le résultat. Avec relations, TypeORM écrit les LEFT JOIN et reconstruit les objets imbriqués.
  4. On peut charger le côté inverse (un groupe et ses stagiaires), trier les éléments liés, et filtrer sur une relation (where: { competences: { libelle: 'CSS' } }).
  5. Supprimer le groupe DEV102 a mis groupe_id à NULL chez Gharbi ; supprimer Ben Ali a supprimé ses notes. Ces actions sont faites par MySQL lui-même, grâce aux contraintes.
onDeleteQuand la ligne parente est supprimée…Exemple
'RESTRICT' / 'NO ACTION' (défaut)la suppression est refusée s'il existe des lignes liéesun auteur qui a des livres (TP 7)
'CASCADE'les lignes liées sont supprimées aussiles notes d'un stagiaire supprimé
'SET NULL'la clé étrangère est mise à NULL (colonne nullable)un stagiaire dont le groupe est dissous

Ne pas confondre cascade (option TypeORM : save() enregistre aussi les objets liés) et onDelete: 'CASCADE' (contrainte SQL : MySQL supprime les lignes liées). Les deux sont indépendants.

Chargement automatique et problème N+1
  • eager: true sur une relation la charge à chaque find(), sans relations. Pratique, mais on charge souvent des données inutiles : à éviter, sauf pour une petite relation toujours utile.
  • lazy (propriété de type Promise<Groupe>) charge la relation au premier accès : une requête par accès.
  • Le problème N+1: charger 50 stagiaires (1 requête), puis leurs notes dans une boucle (50 requêtes). Avec relations: { notes: true } ou une jointure du QueryBuilder (leçon 11.6), tout est chargé en une ou deux requêtes. Activez logging pour repérer les boucles de requêtes.

Sérialisation: renvoyer une entité avec ses relations dans les deux sens (un groupe → ses stagiaires → leur groupe…) ne pose pas de problème tant que vous ne chargez que ce qui est demandé. Pour les réponses publiques, préférez des DTO de sortie (leçon 8.1).

Activités

Activité 1 Formations et groupes

Une formation (DEV, RES…) a plusieurs groupes ; un groupe appartient à une seule formation, obligatoire. Supprimer une formation qui a des groupes doit être refusé. Écrivez les décorateurs des deux côtés.

Voir le corrigé
// formation.entity.ts
@OneToMany(() => Groupe, (groupe) => groupe.formation)
groupes: Groupe[];

// groupe.entity.ts
@ManyToOne(() => Formation, (formation) => formation.groupes, { nullable: false, onDelete: 'RESTRICT' })
@JoinColumn({ name: 'formation_id' })
formation: Formation;

La tentative de suppression produit une QueryFailedError de code ER_ROW_IS_REFERENCED_2, à traduire en 409 (TP 7).

Activité 2 Formateurs et groupes

Un formateur encadre plusieurs groupes, et un groupe peut avoir plusieurs formateurs. Modélisez la relation (table groupes_formateurs). Écrivez ensuite affecter(groupeId, formateurId) qui ajoute un formateur à un groupe.

Voir le corrigé
// groupe.entity.ts
@ManyToMany(() => Formateur, (f) => f.groupes)
@JoinTable({ name: 'groupes_formateurs', joinColumn: { name: 'groupe_id' }, inverseJoinColumn: { name: 'formateur_id' } })
formateurs: Formateur[];

// service
async affecter(groupeId: number, formateurId: number) {
  const groupe = await this.groupes.findOne({ where: { id: groupeId }, relations: { formateurs: true } });
  const formateur = await this.formateurs.findOneBy({ id: formateurId });
  if (!groupe || !formateur) throw new NotFoundException();
  if (!groupe.formateurs.some((f) => f.id === formateurId)) {
    groupe.formateurs.push(formateur);
    await this.groupes.save(groupe);           // INSERT dans groupes_formateurs
  }
  return groupe;
}

Alternative sans charger toute la liste : this.groupes.createQueryBuilder().relation(Groupe, 'formateurs').of(groupeId).add(formateurId).

Activité 3 Repérer le N+1

Ce code affiche la moyenne de chaque stagiaire d'un groupe de 25. Combien de requêtes exécute-t-il ? Réécrivez-le.

const stagiaires = await this.stagiaires.findBy({ groupeId });
for (const s of stagiaires) {
  const notes = await this.notes.findBy({ stagiaire: { id: s.id } });
  s.moyenne = notes.reduce((a, n) => a + n.valeur, 0) / (notes.length || 1);
}
Voir le corrigé

26 requêtes : 1 pour les stagiaires, puis 1 par stagiaire. Version en une requête : this.stagiaires.find({ where: { groupeId }, relations: { notes: true } }) puis le calcul en mémoire. Encore mieux : laisser MySQL calculer la moyenne avec le QueryBuilder (AVG et GROUP BY, leçon 11.6).

Activité 4 Un-à-un

Chaque stagiaire peut avoir un profil (photo, biographie). Écrivez l'entité Profil et la relation @OneToOne, avec la clé étrangère dans stagiaires et une cascade pour enregistrer le profil avec le stagiaire.

Voir le corrigé
@Entity('profils')
export class Profil {
  @PrimaryGeneratedColumn() id: number;
  @Column({ type: 'varchar', length: 255, nullable: true }) photo: string | null;
  @Column({ type: 'text', nullable: true }) biographie: string | null;
}

// stagiaire.entity.ts
@OneToOne(() => Profil, { cascade: true, nullable: true, onDelete: 'SET NULL' })
@JoinColumn({ name: 'profil_id' })              // crée profil_id UNIQUE dans stagiaires
profil: Profil | null;

À retenir

  • @ManyToOne (+ @JoinColumn) côté clé étrangère ; @OneToMany côté inverse, sans colonne.
  • @ManyToMany des deux côtés, @JoinTable d'un seul : table de jointure.
  • find({ relations: { … } }) charge les relations (LEFT JOIN) ; sans cela, elles sont absentes.
  • cascade : save() enregistre les objets liés ; onDelete (RESTRICT, CASCADE, SET NULL) : contrainte SQL.
  • Éviter eager par défaut et les requêtes en boucle (problème N+1).

Cet article vous a-t-il aidé ?