13 октября 2026 года MongoDB объявила об общей доступности (GA) официального расширения для Hibernate ORM. Java-приложения теперь могут работать с документной базой через привычные JPA-сущности, запросы HQL и интеграцию со Spring Boot. Разбираемся, какие операции расширение переводит в команды MongoDB и какие ограничения сохраняются при переносе существующих проектов.
Hibernate ORM получил официальный способ работать с коллекциями MongoDB
У Java-разработчика, привыкшего к Hibernate, данные обычно представлены классами: например, Movie описывает фильм, а Comment — комментарий к нему. Hibernate связывает такие объекты с хранилищем и позволяет читать или сохранять их через методы Java. Традиционно эта схема ориентирована на реляционные базы данных, где информация размещается в таблицах и строках.
MongoDB хранит записи в документах, которые могут содержать вложенные объекты и массивы. Для работы с ними Java-приложения используют собственные инструменты MongoDB, в частности официальный драйвер. Теперь компания предлагает ещё один путь: MongoDB Extension for Hibernate ORM связывает классы, помеченные @Entity, с коллекциями MongoDB и обрабатывает операции через знакомые Hibernate API.
В опубликованном 13 октября сообщении MongoDB подтвердила статус General Availability для расширения с открытым исходным кодом. В нём доступны Hibernate Query Language (HQL), Jakarta Persistence Query Language (JPQL), Criteria Queries и API Session. Практический сценарий — Java-сервис, в котором бизнес-логика уже построена вокруг JPA-сущностей, а часть данных предполагается хранить как документы с изменяемой структурой.
JOIN-запросы Hibernate переводятся в операции MongoDB
Одно из главных изменений стабильной интеграции — поддержка соединений INNER JOIN и LEFT OUTER JOIN. Они позволяют получать связанные данные из разных коллекций, используя привычный для Hibernate синтаксис HQL или JPQL.
Представим каталог фильмов с комментариями. Приложение хранит фильмы в коллекции movies, а отзывы — в comments. Запрос с INNER JOIN возвращает фильмы, для которых есть подходящие комментарии. Вариант с LEFT JOIN сохраняет в результате и фильмы без отзывов.
Внутри расширение преобразует такое соединение в этапы конвейера агрегации MongoDB: $lookup находит документы во второй коллекции, а $unwind обрабатывает полученный массив результатов. Для LEFT JOIN используется параметр preserveNullAndEmptyArrays, который сохраняет записи без связанных документов.
Раньше аналогичный сценарий при работе напрямую через API MongoDB требовал описывать соответствующую агрегацию средствами базы. С расширением эту часть выполняет интеграционный слой. При этом фактическое выполнение запроса по-прежнему зависит от устройства коллекций, связей между документами и условий фильтрации.
Аннотация @Version помогает обнаружить конфликт обновлений
При одновременном редактировании записи возникает распространённая проблема: два процесса считывают одинаковые данные, затем каждый пытается сохранить собственные изменения. В результате более поздняя запись может перезаписать предыдущую.
Расширение поддерживает оптимистическую блокировку через аннотацию @Version. При изменении или удалении документа Hibernate формирует запрос, в котором проверяется идентификатор записи и номер версии, прочитанный ранее. Если другой процесс уже обновил документ, прежняя версия больше не совпадает: Hibernate выдаёт OptimisticLockException.
Этот механизм полезен, например, для параллельного изменения карточки товара или параметров учётной записи. Разработчик получает привычную для Hibernate модель обнаружения конфликтов при работе с документами MongoDB. Пессимистическая блокировка, при которой запись удерживается заблокированной на время операции, в расширении не поддерживается.
Spring Boot получил стартер для MongoDB через JPA
Для приложений на Spring Boot MongoDB подготовила отдельный стартер mongodb-hibernate-spring-boot-starter версии 1.0.0. Он настраивает EntityManagerFactory, менеджер транзакций JPA и поддержку репозиториев Spring Data JPA поверх MongoDB. При этом используется тот же объект MongoClient, который создаёт Spring Boot, без дополнительного пула подключений для расширения.
Это позволяет сохранить привычный подход к репозиториям: например, методы поиска в интерфейсе JpaRepository могут получать документы MongoDB. Такая интеграция отличается от обычного Spring Data MongoDB и имеет собственные границы совместимости.
Есть существенное условие запуска: требуется Hibernate ORM 7.4 или новее. Некоторые выпуски Spring Boot 4.x управляют более ранней версией Hibernate; в этом случае документация предупреждает о возможной ошибке NoSuchMethodError при запуске. Для обработки сравнений с null расширение также требует настройку com.mongodb.hibernate.semantics.nulls=MQL, поскольку использует семантику языка запросов MongoDB.
Какие ограничения сохраняются в версии GA
Статус общей доступности подтверждает готовность поддерживаемых сценариев к промышленному применению. Он не означает полной совместимости со всеми возможностями Hibernate и SQL. В официальной таблице MongoDB перечислены следующие различия:
| Возможность | Поддержка в расширении |
INNER JOIN, LEFT OUTER JOIN, JOIN FETCH | Поддерживаются |
RIGHT JOIN, FULL OUTER JOIN, CROSS JOIN | Не поддерживаются |
Оптимистическая блокировка через @Version | Поддерживается |
| Пессимистическая блокировка | Не поддерживается |
| MongoDB в режиме replica set | Поддерживается |
Отдельный сервер mongod без replica set | Не поддерживается |
| Spring Boot и Spring Data JPA | Частичная совместимость |
Для некоторых специфических операций MongoDB, включая геопространственный поиск и векторный поиск, можно использовать нативные запросы через createNativeQuery() вместо стандартных конструкций HQL. Поддержка функций Queryable Encryption, Change Streams и GridFS непосредственно через расширение отсутствует; соответствующие возможности доступны через Java Driver при соблюдении требований самих механизмов.
Из этих ограничений следует практическая граница миграции: существующий код на Hibernate может сохранить значительную часть модели сущностей и запросов, но запросы с неподдерживаемыми соединениями или SQL-специфичной семантикой потребуют изменений. Перенос самих данных между разными базами тоже остаётся отдельной задачей.
MongoDB расширяет выбор архитектуры для Java-приложений
В анонсе от 13 октября MongoDB закрепила поддержку распространённых приёмов Hibernate — работы с сущностями, связывания коллекций и контроля конкурентных обновлений. По сравнению с прямым использованием MongoDB Java Driver разработчик получает дополнительный интерфейс доступа к документам через JPA и HQL.
Возможности интеграции по-прежнему определяются документной моделью и опубликованной матрицей совместимости. Полный набор HQL-конструкций компания не заявляет, а дальнейшее расширение функций зависит от развития проекта. Для существующих Java-приложений объём изменений при переходе зависит от набора используемых JPA-конструкций, версии Hibernate и конфигурации MongoDB. В официальной документации эти границы уже перечислены для расширения версии 1.0.0.
