この記事の要点
@Modifying は Spring Data JPA で更新系クエリ (UPDATE / DELETE / INSERT) を実行するためのアノテーション @Query と組み合わせて使う（@Query("UPDATE ...") @Modifying） @Transactional 必須: メソッド or 呼び出し元に付与 1次キャッシュと同期しないため、clearAutomatically=true でキャッシュクリア推奨 戻り値は影響行数 (int / void) のみ

 

@Modifying の基本

Spring Data JPA の @Query は通常 SELECT 用ですが、UPDATE / DELETE / INSERT の DML を実行したい場合は @Modifying を併用します。

@Repository
public interface UserRepository extends JpaRepository {

    // UPDATE
    @Modifying
    @Query("UPDATE User u SET u.status = :status WHERE u.id = :id")
    int updateStatus(@Param("id") Long id, @Param("status") String status);

    // DELETE
    @Modifying
    @Query("DELETE FROM User u WHERE u.lastLoginAt < :date")
    int deleteInactiveUsers(@Param("date") LocalDateTime date);

    // INSERT (Native Query が必要)
    @Modifying
    @Query(value = "INSERT INTO user_logs (user_id, action) VALUES (:userId, :action)",
           nativeQuery = true)
    int insertLog(@Param("userId") Long userId, @Param("action") String action);
}

@Transactional の必須性

更新系クエリには必ずトランザクションが必要です:

@Service
public class UserService {
    @Autowired
    private UserRepository userRepository;

    @Transactional  // ← 必須
    public void deactivate(Long id) {
        userRepository.updateStatus(id, "INACTIVE");
    }
}

// または Repository メソッドに直接
@Modifying
@Transactional  // ← Repository メソッドに付ける場合
@Query("UPDATE User u SET u.status = :status WHERE u.id = :id")
int updateStatus(@Param("id") Long id, @Param("status") String status);

付け忘れると以下のエラー:

javax.persistence.TransactionRequiredException:
Executing an update/delete query

1次キャッシュとの同期問題

JPA の EntityManager は 1次キャッシュ（Persistence Context）を持ち、ロード済みエンティティを保持します。@Modifying クエリはこのキャッシュを更新しません。

@Transactional
public void problematicMethod(Long userId) {
    User user = userRepository.findById(userId).orElseThrow();
    // user.status = "ACTIVE" (キャッシュにロード済み)

    userRepository.updateStatus(userId, "INACTIVE");
    // DB は INACTIVE になる
    // しかし user オブジェクトのキャッシュは ACTIVE のまま！

    System.out.println(user.getStatus());  // → "ACTIVE" (誤った値)
}

解決策 1: clearAutomatically

@Modifying(clearAutomatically = true)  // 実行後にキャッシュを clear
@Query("UPDATE User u SET u.status = :status WHERE u.id = :id")
int updateStatus(@Param("id") Long id, @Param("status") String status);

解決策 2: flushAutomatically

@Modifying(flushAutomatically = true)  // クエリ前にキャッシュを DB に flush
@Query("UPDATE User u SET u.status = :status WHERE u.id = :id")
int updateStatus(@Param("id") Long id, @Param("status") String status);

// flush + clear 両方
@Modifying(flushAutomatically = true, clearAutomatically = true)

解決策 3: 手動で entityManager.refresh()

@Autowired
private EntityManager entityManager;

@Transactional
public void method(Long userId) {
    User user = userRepository.findById(userId).orElseThrow();
    userRepository.updateStatus(userId, "INACTIVE");

    entityManager.refresh(user);  // DB から再ロード
    System.out.println(user.getStatus());  // → "INACTIVE" (正)
}

戻り値の選択

戻り値型	意味
int	影響行数（更新された件数）
void	結果不要
Integer	影響行数（null 可）
その他	不可（DataIntegrityViolationException）

JPQL vs Native Query

JPQL（標準）

@Modifying
@Query("UPDATE User u SET u.status = :status WHERE u.id IN :ids")
int updateBulk(@Param("ids") List ids, @Param("status") String status);

Native Query（DB ベンダ固有機能）

@Modifying
@Query(value = """
    INSERT INTO user_logs (user_id, action, created_at)
    SELECT id, 'EXPORTED', NOW() FROM users WHERE status = 'ACTIVE'
    """, nativeQuery = true)
int logActiveExport();

// MySQL の ON DUPLICATE KEY UPDATE
@Modifying
@Query(value = """
    INSERT INTO user_settings (user_id, key, value)
    VALUES (:userId, :key, :value)
    ON DUPLICATE KEY UPDATE value = :value
    """, nativeQuery = true)
int upsertSetting(@Param("userId") Long userId,
                  @Param("key") String key,
                  @Param("value") String value);

サービス層からの呼び出しパターン

@Service
public class UserService {

    private final UserRepository userRepository;

    @Transactional
    public int bulkDeactivate(List userIds) {
        // バルク更新（高速）
        int affected = userRepository.updateBulk(userIds, "INACTIVE");
        log.info("Deactivated {} users", affected);
        return affected;
    }

    @Transactional
    public int cleanupInactiveUsers(int days) {
        LocalDateTime threshold = LocalDateTime.now().minusDays(days);
        return userRepository.deleteInactiveUsers(threshold);
    }
}

@Modifying の代替: 通常 save()

少量のエンティティ更新なら通常の save() でも OK:

@Transactional
public void deactivate(Long id) {
    User user = userRepository.findById(id).orElseThrow();
    user.setStatus("INACTIVE");
    userRepository.save(user);  // または明示的 save 不要 (Dirty Checking)
}

// vs @Modifying (バルク向き)
// - @Modifying は SELECT なし、1 つの UPDATE 文だけ発行 (高速)
// - 通常 save は SELECT + UPDATE (キャッシュ更新あり)

注意点

• @Version の楽観ロックは効かない: バルク UPDATE では Version 自動チェックなし
• キャッシュ非同期: 1次キャッシュ + 2次キャッシュとの整合性に注意
• cascade は効かない: 関連エンティティへの自動カスケードなし
• 監査リスナーは呼ばれない: @PrePersist / @PreUpdate もスキップ
• JPA SELECT 結果との不整合: 同トランザクション内で更新 → SELECT すると古い結果が返るリスク

関連記事

• @Repository
• アノテーション一覧
• DB接続設定や値の取得(JdbcTemplate編)