- Implement many-to-many relationships using JPA annotations and join tables
- Understand the difference between simple and complex many-to-many mappings
- Configure bidirectional many-to-many relationships with proper collection management
- Use join entities to add attributes to many-to-many relationships
Many-to-many relationships show up everywhere in real applications. Users can belong to multiple groups, and groups have multiple users. Students enroll in multiple courses, and courses have multiple students. Products appear in multiple categories, and categories contain multiple products. The pattern is ubiquitous.
JPA handles many-to-many relationships through join tables. Unlike one-to-many where the foreign key lives on one table, many-to-many requires a separate table to hold the associations. This join table contains two foreign keys—one pointing to each side of the relationship. It's the standard relational database approach, and JPA maps it cleanly to your Java objects.
We'll add tags to our blog system. Users can create tags, posts can have multiple tags, and tags can be applied to multiple posts. That's a many-to-many between Post and Tag. We'll start with a simple mapping, then show you how to handle the more complex case where you need to store additional data on the relationship itself.
The database structure for many-to-many involves three tables. You've got your two entity tables (posts and tags in our case), plus a join table that connects them. The join table typically has just two columns: foreign keys to both entity tables. Sometimes it has a composite primary key on those two columns, sometimes an auto-generated ID. Either approach works.
In Java, both sides of the relationship have collections. Post has a collection of Tags, Tag has a collection of Posts. You can navigate in both directions, which is usually what you want. Unlike one-to-many, there's no clear "owning" side in the business logic sense, but JPA still requires you to designate one side as the owner for mapping purposes.
The owning side determines which entity's table the join table is "closer to" in a sense, though really the join table is equally related to both. More practically, the owning side's annotations control the join table name and column names. The inverse side uses mappedBy to reference the owning side's field.
Here's our Tag entity, which will be one side of the many-to-many relationship:
package javapro.academy.entity;
import jakarta.persistence.*;
import java.time.LocalDateTime;
import java.util.HashSet;
import java.util.Set;
@Entity
@Table(name = "tags")
public class Tag {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(unique = true, nullable = false)
private String name;
private String description;
private LocalDateTime createdAt;
@ManyToMany(mappedBy = "tags")
private Set<Post> posts = new HashSet<>();
public Tag() {
this.createdAt = LocalDateTime.now();
}
public Tag(String name, String description) {
this();
this.name = name;
this.description = description;
}
// Getters and setters
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getDescription() {
return description;
}
public void setDescription(String description) {
this.description = description;
}
public LocalDateTime getCreatedAt() {
return createdAt;
}
public void setCreatedAt(LocalDateTime createdAt) {
this.createdAt = createdAt;
}
public Set<Post> getPosts() {
return posts;
}
public void setPosts(Set<Post> posts) {
this.posts = posts;
}
}Notice we're using Set<Post> instead of List<Post>. This is intentional and important for many-to-many relationships. Sets prevent duplicates automatically—you can't add the same post to a tag twice. They also perform better for contains checks and equality operations. Hibernate handles Set-based collections more efficiently in many-to-many scenarios because it doesn't care about ordering.
The @ManyToMany(mappedBy = "tags") annotation makes Tag the inverse side of the relationship. Post will be the owner and will define the join table configuration. The mappedBy value must exactly match the field name in the Post entity.
Making the name column unique makes sense for tags. You don't want "java" and "Java" as separate tags. In a production system, you'd probably want case-insensitive uniqueness and more sophisticated tag management, but this works for demonstration purposes.
Now we add the many-to-many relationship to Post:
package javapro.academy.entity;
import jakarta.persistence.*;
import java.time.LocalDateTime;
import java.util.HashSet;
import java.util.Set;
@Entity
@Table(name = "posts")
public class Post {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
private String title;
@Column(columnDefinition = "TEXT")
private String content;
private LocalDateTime createdAt;
private LocalDateTime updatedAt;
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "user_id", nullable = false)
private User user;
@ManyToMany(cascade = {CascadeType.PERSIST, CascadeType.MERGE})
@JoinTable(
name = "post_tags",
joinColumns = @JoinColumn(name = "post_id"),
inverseJoinColumns = @JoinColumn(name = "tag_id")
)
private Set<Tag> tags = new HashSet<>();
public Post() {
this.createdAt = LocalDateTime.now();
this.updatedAt = LocalDateTime.now();
}
public Post(String title, String content) {
this();
this.title = title;
this.content = content;
}
// Convenience methods for managing tags
public void addTag(Tag tag) {
tags.add(tag);
tag.getPosts().add(this);
}
public void removeTag(Tag tag) {
tags.remove(tag);
tag.getPosts().remove(this);
}
@PreUpdate
public void preUpdate() {
this.updatedAt = LocalDateTime.now();
}
// Getters and setters
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getTitle() {
return title;
}
public void setTitle(String title) {
this.title = title;
}
public String getContent() {
return content;
}
public void setContent(String content) {
this.content = content;
}
public LocalDateTime getCreatedAt() {
return createdAt;
}
public void setCreatedAt(LocalDateTime createdAt) {
this.createdAt = createdAt;
}
public LocalDateTime getUpdatedAt() {
return updatedAt;
}
public void setUpdatedAt(LocalDateTime updatedAt) {
this.updatedAt = updatedAt;
}
public User getUser() {
return user;
}
public void setUser(User user) {
this.user = user;
}
public Set<Tag> getTags() {
return tags;
}
public void setTags(Set<Tag> tags) {
this.tags = tags;
}
}The @JoinTable annotation defines the join table structure. The name attribute sets the table name. joinColumns specifies the foreign key column that points back to this entity (Post), and inverseJoinColumns specifies the column that points to the other entity (Tag).
Hibernate will create a post_tags table with two columns: post_id and tag_id. Both are foreign keys with constraints to their respective tables. Typically, you'd have a composite primary key on both columns, or a unique constraint if you add a separate ID column.
Notice the cascade settings: CascadeType.PERSIST and CascadeType.MERGE but not CascadeType.REMOVE. This is deliberate. When you save a post with new tags, the tags get persisted. When you update a post, changes to tags propagate. But when you delete a post, the tags should survive—they might be used by other posts. If you used CascadeType.ALL, deleting a post would delete all its tags, which would break other posts using those same tags.
The addTag() and removeTag() methods maintain bidirectional consistency. When you add a tag to a post, it also adds that post to the tag's collection. When you remove a tag from a post, it removes the post from the tag's collection. This keeps your in-memory object graph consistent with what will be in the database.
The repository for tags follows the familiar pattern:
package javapro.academy.repository;
import javapro.academy.entity.Tag;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.stereotype.Repository;
import java.util.List;
import java.util.Optional;
@Repository
public interface TagRepository extends JpaRepository<Tag, Long> {
Optional<Tag> findByName(String name);
@Query("SELECT t FROM Tag t LEFT JOIN FETCH t.posts WHERE t.id = :id")
Optional<Tag> findByIdWithPosts(Long id);
@Query("SELECT DISTINCT t FROM Tag t LEFT JOIN FETCH t.posts")
List<Tag> findAllWithPosts();
@Query("SELECT t FROM Tag t WHERE SIZE(t.posts) > :minPosts")
List<Tag> findPopularTags(int minPosts);
}The findByName() method is useful for checking if a tag already exists before creating a new one. You typically want tags to be reused across posts, not created fresh each time.
The JOIN FETCH queries prevent N+1 problems when you need to access the posts associated with tags. The findPopularTags() method demonstrates using the SIZE() function in JPQL to filter based on collection size. This finds tags that are used in more than a certain number of posts.
Let's add tags to our seed data:
package javapro.academy.config;
import javapro.academy.entity.Post;
import javapro.academy.entity.Profile;
import javapro.academy.entity.Tag;
import javapro.academy.entity.User;
import javapro.academy.repository.TagRepository;
import javapro.academy.repository.UserRepository;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class DataSeeder {
@Bean
CommandLineRunner initDatabase(UserRepository userRepository, TagRepository tagRepository) {
return args -> {
// Create tags first
Tag javaTag = new Tag("Java", "Java programming language and ecosystem");
Tag springTag = new Tag("Spring Boot", "Spring Boot framework and best practices");
Tag microservicesTag = new Tag("Microservices", "Microservices architecture patterns");
Tag dockerTag = new Tag("Docker", "Containerization and Docker");
Tag kubernetesTag = new Tag("Kubernetes", "Container orchestration with Kubernetes");
Tag apiTag = new Tag("API Design", "RESTful API design principles");
Tag jpaTag = new Tag("JPA", "Java Persistence API and Hibernate");
tagRepository.save(javaTag);
tagRepository.save(springTag);
tagRepository.save(microservicesTag);
tagRepository.save(dockerTag);
tagRepository.save(kubernetesTag);
tagRepository.save(apiTag);
tagRepository.save(jpaTag);
User user1 = new User("john_doe", "john@example.com");
Profile profile1 = new Profile(
"Software developer with a passion for Java and Spring Boot",
"https://example.com/avatars/john.jpg",
"San Francisco, CA"
);
user1.setProfile(profile1);
Post post1 = new Post(
"Getting Started with Spring Boot",
"Spring Boot has revolutionized Java application development by providing sensible defaults and auto-configuration..."
);
post1.addTag(springTag);
post1.addTag(javaTag);
Post post2 = new Post(
"Understanding JPA Relationships",
"JPA relationships can be tricky, especially when you're dealing with bidirectional mappings and cascade operations..."
);
post2.addTag(jpaTag);
post2.addTag(javaTag);
post2.addTag(springTag);
user1.addPost(post1);
user1.addPost(post2);
User user2 = new User("jane_smith", "jane@example.com");
Profile profile2 = new Profile(
"Full-stack engineer specializing in microservices architecture",
"https://example.com/avatars/jane.jpg",
"Austin, TX"
);
user2.setProfile(profile2);
Post post3 = new Post(
"Microservices Best Practices",
"Building microservices requires careful consideration of service boundaries, communication patterns, and data consistency..."
);
post3.addTag(microservicesTag);
post3.addTag(springTag);
post3.addTag(javaTag);
Post post4 = new Post(
"Docker for Java Developers",
"Containerizing Java applications with Docker simplifies deployment and ensures consistency across environments..."
);
post4.addTag(dockerTag);
post4.addTag(javaTag);
Post post5 = new Post(
"API Design Principles",
"Designing clean, intuitive APIs is crucial for building maintainable systems. REST principles provide a solid foundation..."
);
post5.addTag(apiTag);
post5.addTag(springTag);
user2.addPost(post3);
user2.addPost(post4);
user2.addPost(post5);
User user3 = new User("bob_wilson", "bob@example.com");
Profile profile3 = new Profile(
"DevOps enthusiast and cloud infrastructure expert",
"https://example.com/avatars/bob.jpg",
"Seattle, WA"
);
user3.setProfile(profile3);
Post post6 = new Post(
"Kubernetes Essentials",
"Kubernetes orchestrates containerized applications at scale. Understanding pods, services, and deployments is fundamental..."
);
post6.addTag(kubernetesTag);
post6.addTag(dockerTag);
user3.addPost(post6);
userRepository.save(user1);
userRepository.save(user2);
userRepository.save(user3);
System.out.println("Database seeded with " + userRepository.count() + " users and " + tagRepository.count() + " tags");
};
}
}We save the tags first, then associate them with posts. Because we set CascadeType.PERSIST on the Post-Tag relationship, you could technically skip saving the tags explicitly and let cascade handle it. But saving tags first is clearer and avoids potential issues with tag uniqueness—if multiple posts try to create the same tag, you'd get constraint violations.
The addTag() convenience method handles the bidirectional association. When the posts get saved through the user cascade, Hibernate inserts rows into the post_tags join table automatically.
A controller to manage tags and see which posts use them:
package javapro.academy.controller;
import javapro.academy.entity.Post;
import javapro.academy.entity.Tag;
import javapro.academy.repository.PostRepository;
import javapro.academy.repository.TagRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.List;
import java.util.Set;
@RestController
@RequestMapping("/api/tags")
public class TagController {
@Autowired
private TagRepository tagRepository;
@Autowired
private PostRepository postRepository;
@GetMapping
public List<Tag> getAllTags() {
return tagRepository.findAll();
}
@GetMapping("/{id}")
public ResponseEntity<Tag> getTagById(@PathVariable Long id) {
return tagRepository.findById(id)
.map(ResponseEntity::ok)
.orElse(ResponseEntity.notFound().build());
}
@GetMapping("/{id}/posts")
public ResponseEntity<Set<Post>> getPostsByTag(@PathVariable Long id) {
return tagRepository.findById(id)
.map(tag -> ResponseEntity.ok(tag.getPosts()))
.orElse(ResponseEntity.notFound().build());
}
@GetMapping("/popular")
public List<Tag> getPopularTags(@RequestParam(defaultValue = "2") int minPosts) {
return tagRepository.findPopularTags(minPosts);
}
@PostMapping
public ResponseEntity<Tag> createTag(@RequestBody Tag tag) {
if (tagRepository.findByName(tag.getName()).isPresent()) {
return ResponseEntity.badRequest().build();
}
Tag savedTag = tagRepository.save(tag);
return ResponseEntity.ok(savedTag);
}
@PostMapping("/{tagId}/posts/{postId}")
public ResponseEntity<Void> addTagToPost(@PathVariable Long tagId, @PathVariable Long postId) {
return tagRepository.findById(tagId).flatMap(tag ->
postRepository.findById(postId).map(post -> {
post.addTag(tag);
postRepository.save(post);
return ResponseEntity.ok().<Void>build();
})
).orElse(ResponseEntity.notFound().build());
}
@DeleteMapping("/{tagId}/posts/{postId}")
public ResponseEntity<Void> removeTagFromPost(@PathVariable Long tagId, @PathVariable Long postId) {
return tagRepository.findById(tagId).flatMap(tag ->
postRepository.findById(postId).map(post -> {
post.removeTag(tag);
postRepository.save(post);
return ResponseEntity.ok().<Void>build();
})
).orElse(ResponseEntity.notFound().build());
}
}The /api/tags/{id}/posts endpoint shows all posts that have a particular tag. Because we're using Set<Post>, the response will be a set of post objects, which Jackson serializes to JSON.
Adding and removing tags from posts requires loading both entities, calling the convenience method, and saving. The addTag() method updates both sides of the relationship in memory, then saving the post persists that change to the join table.
Be careful with JSON serialization again. The bidirectional relationship between Post and Tag can cause infinite recursion during serialization. You'll need @JsonManagedReference and @JsonBackReference annotations, or better yet, use DTOs that don't include the back-references.
Let's add endpoints to the PostController to handle tags on posts:
package javapro.academy.controller;
import javapro.academy.entity.Post;
import javapro.academy.entity.Tag;
import javapro.academy.entity.User;
import javapro.academy.repository.PostRepository;
import javapro.academy.repository.TagRepository;
import javapro.academy.repository.UserRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.List;
import java.util.Set;
@RestController
@RequestMapping("/api/posts")
public class PostController {
@Autowired
private PostRepository postRepository;
@Autowired
private UserRepository userRepository;
@Autowired
private TagRepository tagRepository;
@GetMapping
public List<Post> getAllPosts() {
return postRepository.findAll();
}
@GetMapping("/{id}")
public ResponseEntity<Post> getPostById(@PathVariable Long id) {
return postRepository.findById(id)
.map(ResponseEntity::ok)
.orElse(ResponseEntity.notFound().build());
}
@GetMapping("/{id}/tags")
public ResponseEntity<Set<Tag>> getPostTags(@PathVariable Long id) {
return postRepository.findById(id)
.map(post -> ResponseEntity.ok(post.getTags()))
.orElse(ResponseEntity.notFound().build());
}
@GetMapping("/user/{userId}")
public ResponseEntity<List<Post>> getPostsByUser(@PathVariable Long userId) {
return userRepository.findById(userId)
.map(user -> ResponseEntity.ok(postRepository.findByUserId(userId)))
.orElse(ResponseEntity.notFound().build());
}
@GetMapping("/search")
public List<Post> searchPosts(@RequestParam String keyword) {
return postRepository.searchPosts(keyword);
}
@PostMapping("/user/{userId}")
public ResponseEntity<Post> createPost(@PathVariable Long userId, @RequestBody Post post) {
return userRepository.findById(userId)
.map(user -> {
user.addPost(post);
userRepository.save(user);
return ResponseEntity.ok(post);
})
.orElse(ResponseEntity.notFound().build());
}
@DeleteMapping("/{id}")
public ResponseEntity<Void> deletePost(@PathVariable Long id) {
return postRepository.findById(id)
.map(post -> {
postRepository.delete(post);
return ResponseEntity.ok().<Void>build();
})
.orElse(ResponseEntity.notFound().build());
}
}The /api/posts/{id}/tags endpoint returns all tags for a specific post. Combined with the tag controller's endpoint to get posts by tag, you have full bidirectional navigation through the REST API.
Sometimes you need to store additional data on the relationship itself. Suppose you want to track when a tag was added to a post, or who added it, or a priority/relevance score. The simple many-to-many mapping won't work because the join table only has the two foreign keys.
The solution is a join entity—a full entity class that represents the join table. Instead of a direct many-to-many, you have two one-to-many relationships. Post has many PostTag entities, Tag has many PostTag entities, and PostTag has references to both Post and Tag plus whatever additional fields you need.
Here's what that looks like:
package javapro.academy.entity;
import jakarta.persistence.*;
import java.time.LocalDateTime;
@Entity
@Table(name = "post_tags")
public class PostTag {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "post_id")
private Post post;
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "tag_id")
private Tag tag;
private LocalDateTime taggedAt;
private Integer relevanceScore;
public PostTag() {
this.taggedAt = LocalDateTime.now();
}
public PostTag(Post post, Tag tag, Integer relevanceScore) {
this();
this.post = post;
this.tag = tag;
this.relevanceScore = relevanceScore;
}
// Getters and setters
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public Post getPost() {
return post;
}
public void setPost(Post post) {
this.post = post;
}
public Tag getTag() {
return tag;
}
public void setTag(Tag tag) {
this.tag = tag;
}
public LocalDateTime getTaggedAt() {
return taggedAt;
}
public void setTaggedAt(LocalDateTime taggedAt) {
this.taggedAt = taggedAt;
}
public Integer getRelevanceScore() {
return relevanceScore;
}
public void setRelevanceScore(Integer relevanceScore) {
this.relevanceScore = relevanceScore;
}
}Then you'd modify Post and Tag to have @OneToMany relationships to PostTag instead of @ManyToMany to each other. This gives you complete control over the join table at the cost of more complexity in your code. You have to manage PostTag entities explicitly instead of just adding tags to a set.
For most use cases, the simple many-to-many is sufficient. Only introduce join entities when you genuinely need to store attributes on the relationship. The added complexity isn't worth it otherwise.
Finding posts by tag is straightforward—just navigate the relationship. But what if you want posts that have all tags in a specific set? Or posts that have at least one of several tags? These queries require more sophisticated JPQL.
Here are some useful query methods you might add to PostRepository:
@Query("SELECT DISTINCT p FROM Post p JOIN p.tags t WHERE t.name IN :tagNames")
List<Post> findByTagNames(@Param("tagNames") List<String> tagNames);
@Query("SELECT p FROM Post p WHERE SIZE(p.tags) >= :minTags")
List<Post> findPostsWithMinTags(@Param("minTags") int minTags);
@Query("SELECT p FROM Post p JOIN p.tags t WHERE t.id = :tagId")
List<Post> findByTagId(@Param("tagId") Long tagId);The first query finds posts that have at least one of the specified tags. The JOIN creates a row for each post-tag combination, then IN filters to matching tags. DISTINCT prevents duplicate posts if they have multiple matching tags.
The second query uses SIZE() to find posts with a minimum number of tags. This is useful for finding well-categorized content.
The third query is simpler than navigating through the Tag entity when you already have the tag ID. These kinds of targeted queries perform better than loading entities and filtering in Java code.
Many-to-many relationships can have significant performance implications. Loading a collection of posts and accessing their tags causes N+1 queries unless you use JOIN FETCH. Loading tags and accessing their posts has the same problem.
The join table adds overhead. Every tag you add to a post requires an INSERT into the join table. Removing a tag requires a DELETE. These operations are fast individually but add up when you're managing tags on many posts.
Consider caching tag data if it doesn't change frequently. Tags are often relatively static—you create a core set and reuse them. Spring's cache abstraction can store tag lookups and reduce database hits.
For high-traffic applications, denormalization might make sense. You could store tag names as a comma-separated string or JSON array in the posts table for display purposes, while maintaining the normalized many-to-many relationship for filtering and management. This trades storage and update complexity for read performance.
Many-to-many relationships require join tables in the database and collection fields in your entities. JPA's @ManyToMany annotation handles the mapping, and @JoinTable configures the join table structure. One side owns the relationship and defines the join table, the other uses mappedBy to reference it.
Cascade operations in many-to-many contexts require careful thought. You typically want PERSIST and MERGE to cascade so new associations get saved, but not REMOVE since deleting one entity shouldn't delete the related entities that might be associated with other entities too. Orphan removal doesn't apply to many-to-many—there are no orphans when entities exist independently.
Bidirectional consistency matters just as much as in one-to-many relationships. Convenience methods that update both sides of the association prevent bugs where your object graph doesn't match the database state. Using Set instead of List prevents duplicates and improves performance.
Join entities transform many-to-many into two one-to-many relationships when you need attributes on the association itself. This adds complexity but gives you complete control over the join table. Reserve it for cases where you genuinely need that extra data—timestamps, relevance scores, user attribution, or other metadata about the relationship.
The key to many-to-many success is understanding the SQL being generated and optimizing accordingly. Use JOIN FETCH to avoid N+1 queries, write targeted JPQL for complex filtering, and consider your cascade and fetch strategies carefully. Many-to-many relationships are powerful but demand attention to performance and data integrity.
Did you find this helpful? You'll love our Building Production-Ready REST APIs with Spring Boot course. We take these JPA fundamentals and show you how to build complete, scalable systems—with validation, error handling, business logic, and everything else tutorials skip but employers demand. Learn to create APIs that work in the real world: https://www.javapro.academy/bootcamp/building-production-ready-rest-apis-with-spring-boot/