JPA offers two ways to map a composite primary key: @EmbeddedId and @IdClass. How do they differ in mapping, in query syntax, and in when you would choose one over the other?

## Two spellings of the same schema A composite primary key means the table's PK spans two or more columns. JPA gives two mappings. ### @EmbeddedId ```java @Embeddable public class OrderLineId implements Serializable { private Long orderId; private Long productId; protected OrderLineId() {} public OrderLineId(Long orderId, Long productId) { ... } @Override public boolean equals(Object o) { ... } @Override public int hashCode() { ... } } @Entity public class OrderLine { @EmbeddedId private OrderLineId id; private int quantity; } ``` The key is a first-class type. `em.find(OrderLine.class, new OrderLineId(1L, 2L))` reads naturally, the key can be passed through service signatures, and column names are tuned with `@AttributeOverride` on the `@EmbeddedId` field. The cost is a level of indirection everywhere — including in queries: `select l from OrderLine l where l.id.orderId = :o`. ### @IdClass ```java public class OrderLineId implements Serializable { private Long orderId; // names and types must match the entity private Long productId; public OrderLineId() {} @Override public boolean equals(Object o) { ... } @Override public int hashCode() { ... } } @Entity @IdClass(OrderLineId.class) public class OrderLine { @Id private Long orderId; @Id private Long productId; private int quantity; } ``` The attributes live on the entity, so JPQL is flat (`where l.orderId = :o`) and getters read directly. The id class is only a *lookup token*: it is what you pass to `find()` and what `getReference()` needs, but it is never populated as an entity field. The obvious downside is duplication — change a key attribute and you must change it in two files, with no compiler check that they still match. A mismatch in name or type surfaces as a bootstrap error or, worse, as odd behaviour. ## Rules that apply to both - The key class must be **public**, implement **`Serializable`**, have a **no-arg constructor**, and implement **`equals`/`hashCode`** over all key attributes. Hibernate uses identifier equality to key the first-level cache (the persistence context map), the second-level cache, and to resolve `merge`/`find`. - Key attributes must be basic types, other embeddables, or (with derived identity) associations. Composite keys **cannot** use `@GeneratedValue`; you assign the values yourself or derive them from associations via `@MapsId`. - Key attributes should be treated as immutable. Changing a key value after persist means Hibernate's identity map and the database row disagree; the safe operation is delete-and-insert. - `@AttributeOverride` works on `@EmbeddedId` to rename key columns per entity; with `@IdClass` you simply annotate the entity fields with `@Column`. ## Derived identity When the composite key is made of foreign keys — the common case for link tables — both forms support `@MapsId`. With `@EmbeddedId` you write `@MapsId("orderId") @ManyToOne Order order`, and Hibernate keeps the key field and the association's FK column in sync from a single mapping. With `@IdClass`, you can instead annotate the association itself `@Id @ManyToOne Order order`, and the id class declares the *type of the FK* (or of the parent's id) for that name. ## Choosing Prefer `@EmbeddedId` for new code: one source of truth for the key, a reusable value type, natural `find()` calls, and first-class support for `@MapsId`. Reach for `@IdClass` when you are mapping a legacy schema where flat entity attributes and flat JPQL matter, when a framework or query layer you use dislikes nested id paths, or when you want the key attributes to be plain fields on the entity for readability. Functionally the two produce the same SQL; the choice is ergonomic, and consistency across a codebase matters more than which one you pick.