Spring Data save() INSERT vs UPDATE Decision

Direct Answer

Spring Data JPA calls EntityManager.persist for an entity it considers new and EntityManager.merge otherwise. By default it first checks a non-primitive @Version property, then a nullable identifier: null means new. It does not generally define primitive id value 0 as the rule. Entities with assigned IDs often implement Persistable to supply reliable isNew behavior.

Code Example

@Service
public class ProductService {
    private final ProductRepository repository;
    ProductService(ProductRepository r) { this.repository = r; }

    public Product create(String name, BigDecimal price) {
        var p = new Product();
        p.setName(name);
        p.setPrice(price);
        return repository.save(p); // id null -> persist() -> INSERT (id filled)
    }

    @Transactional
    public Product updatePrice(Long id, BigDecimal price) {
        var p = repository.findById(id).orElseThrow();
        p.setPrice(price);
        return p; // managed -> dirty checking -> UPDATE at commit (no save needed)
    }
}

Common Mistakes & Pitfalls

• Assuming save() only inserts — a non-null id makes it an UPDATE; reusing a detached entity with an id won't INSERT.
• Calling save() when nothing changed — managed entities update via dirty checking at commit; an extra save() is redundant.
• Manually assigned IDs — a non-null id forces merge()'s SELECT-before-INSERT; implement Persistable to skip it.
• Cross-transaction edits — modifying detached entities means merge() does a SELECT; prefer fetching fresh in the same transaction.