- ⚠️ Hibernate JSON functions are turned off by default. This is because of stability concerns and issues across different databases.
- 💡 The "incubating" tag means JSON functions might change or break in future Hibernate versions.
- 🔑 To turn on JSON functions in Spring Boot 4 with Hibernate 7, use
hibernate.query.json_functionality.enabled=true. - 🧪 Testing in staging areas is key before using JSON queries in a live system.
- 🔄 Even without Hibernate JSON functions, other options like JDBC and SQL views give you ways to work around it.
Spring Boot JSON Functions: Why Are They Turned Off?
The Spring Boot 4 update brings Hibernate 7. This gives you new ORM features, like native JSON function support for databases such as PostgreSQL and MySQL. And while this helps your app handle modern, semi-structured data in regular databases, these JSON functions are turned off by default. This raises questions about how stable, compatible, and safe they are to use. In this article, we'll look at why this choice was made, how to turn on the feature, how people use it, the risks involved, and other good options.
What Are Hibernate JSON Functions?
Hibernate 7 is a newer version of the Java Persistence API (JPA) framework. It adds strong support for native JSON operations. For developers building new applications with Spring Boot and Hibernate, this means a better fit with the document-like features now available in relational databases such as PostgreSQL, MySQL 8+, and Oracle.
Supported Features
Hibernate’s JSON function support lets you do strong SQL-like operations over JSON columns:
- 🔍 Get values straight from JSON using specific JSON path rules for each database.
- 🎯 Filter or pick parts from JSON structures that are inside other JSON structures.
- 🧾 Build changing queries that use detailed JSON info.
- 🛠️ Set conditions right on JSON fields with standard JPQL or HQL code.
For PostgreSQL, this means using functions like jsonb_extract_path_text, jsonb_exists, or jsonb_array_elements_text. In MySQL, similar functions include JSON_EXTRACT and JSON_CONTAINS.
Before, these operations meant writing native SQL by hand or processing raw text in Java. Now, with Hibernate 7 and Spring Boot 4, you can build these JSON operations in your repositories and query definitions. The ORM layer gives you type-safe access.
How People Use Them
Here are some modern software ways where Hibernate’s JSON support can greatly improve your system:
- Analytics Logs: Keep user actions or system events as JSON. Search them by related fields, like location or event type.
- Flexible User Metadata: Don't change table designs for small user preference updates. Instead, save them in a JSON blob.
- Third-Party Integrations: Outside systems often send back JSON data with parts inside other parts. Save and query them directly in the database.
For these ways, Hibernate JSON functions make things fit better, run faster, and code simpler.
New Features in Hibernate Explained
Hibernate uses the term “incubating” to show that a feature is experimental. This means it's not part of the promised long-term API. This label is key for developers deciding whether to use a new feature.
“An incubating feature is experimental. It might change or be replaced in ways that are not backward-compatible.” — Red Hat, 2023
Why “Incubating” Matters
A new feature:
- Its API might change in future versions.
- It could be removed or marked as old without warning.
- It might not have the same tests or promise of backward compatibility as stable APIs.
- And it might work differently on different databases.
For Hibernate JSON support, this means developers need to be extra careful when updating or switching databases. It's not just about bugs. It's about how the design and use might change.
Why Are Hibernate JSON Functions Disabled by Default?
Even with its promise, Hibernate turns off JSON querying by default. This may surprise developers who updated and thought JSON support would work right away.
Main Reasons for Default Disablement
-
Stability Protection
- Because this feature is new, there's a higher chance of bugs or API changes.
- Turning it off by default makes sure only developers who clearly need it take on the risks.
-
Database Differences
- How well JSON is supported changes a lot across different databases.
- PostgreSQL has many features for
jsonb. But MySQL follows different code (JSON_EXTRACT). - It's hard to support all databases in the same way. Turning it on by default could break how well it works across different databases.
-
Business Caution
- Hibernate runs many business applications. Many are older, critical systems.
- Even small changes in ORM logic could cause unexpected problems.
-
Avoiding Hidden Issues
- Updating from older Hibernate versions (like 5 or 6.2) to Hibernate 7 might add JSON function behaviors you didn't expect.
- By making you turn it on, Hibernate makes sure you know what that means.
The feature is there, but with a clear "use at your own risk" warning.
Spring Boot 4 and Hibernate 7: What's New?
Spring Boot 4 makes big changes internally. It now works better with Hibernate 7 (Hibernate ORM 6.4+). This updates your Java setup and fits with new JDK features.
Key Improvements
- ✅ Hibernate 7 support with better JSON integration.
- ✅ The base Java version is now Java 17+ (LTS).
- 🧹 Less wordy thanks to better annotation design.
- 🧬 Works better with native SQL functions and type guessing.
- 📦 Improved ways to map JSON and custom columns.
Even with newer versions, Spring Boot 4 doesn't automatically turn on Hibernate's new features. JSON functions still need to be activated explicitly.
Do You Actually Need JSON Functions?
Before you reach for this feature, ask a key question: Do your data needs make JSON support worth it?
When JSON Functions Shine
- Your data changes over time, like user preferences.
- You work with outside systems and save JSON data to search or look at.
- Logs or audit trails work better as semi-structured data.
- Your business needs you to get or look at JSON parts in queries.
When to Avoid
- Your data structure is set and probably won't change.
- ORM consistency and lifecycle support matters (like how entities relate).
- You use many databases (like PostgreSQL + Oracle) with different JSON support.
- Your developers are new to native JSON SQL queries and fixing how they work.
Don't use JSON too much just because you can. Indexing, querying, and changing the structure are harder with JSON blobs than with regular database columns.
Turning On Hibernate JSON Functions in Spring Boot 4
To use JSON functions, you need to turn them on in your app's settings. Here’s how.
Method 1: YAML Configuration
spring:
jpa:
properties:
hibernate:
query:
json_functionality:
enabled: true
Method 2: Properties File
spring.jpa.properties.hibernate.query.json_functionality.enabled=true
This one setting lets Hibernate build JSON expressions in HQL, JPQL, or CriteriaBuilder.
Using JSON Functions in JPQL with PostgreSQL
After you turn it on, Hibernate sends JSON expressions into the SQL it makes. Here's an example to show how to use it.
Entity Definition
@Entity
public class User {
@Id
private Long id;
@Type(JsonBinaryType.class)
@Column(columnDefinition = "jsonb")
private String metadata;
}
Here, we use @Type(JsonBinaryType.class) from the hibernate-types library to let you map JSONB in PostgreSQL.
JPQL Query Example
@Query("SELECT u FROM User u WHERE jsonb_extract_path_text(u.metadata, 'preferences', 'theme') = 'dark'")
List<User> findUsersWithDarkTheme();
This query will return all users whose metadata JSONB includes the field:
{
"preferences": {
"theme": "dark"
}
}
Native Query Option
If JPQL doesn't work because of syntax rules, think about writing the raw SQL query:
@Query(value = "SELECT * FROM user WHERE metadata->'preferences'->>'theme' = 'dark'", nativeQuery = true)
List<User> findDarkThemeUsers();
Rules for Safe Usage
Using new features like these safely in a live system needs good engineering practices.
Good Ways to Work
- 🔍 Turn on SQL query logs (
spring.jpa.show-sql=true) to check the SQL that's made. - 📜 Use native queries if JPQL doesn't handle hard JSON paths.
- 🧪 Put JSON queries in integration tests with enough coverage.
- 🪝 Make feature switches to turn off JSON logic fast, if you need to.
Keep things separate. Give all JSON queries to repository methods so you can easily change them later.
Testing JSON Functions in Staging Areas
Before going live, test in a staging area that acts like your real system.
Checklist:
- ✅ Make sure your database works with the JSON operators you're using.
- ✅ Write scripts to fill JSON structures with test data.
- ✅ Run performance tests with EXPLAIN ANALYZE to see if queries on JSON fields run well.
- ✅ Turn on logging to catch SQL that you didn't expect.
- ✅ Add monitoring for slow queries after you go live.
When NOT to Use Hibernate JSON Functions
Some tech setups don't work well with Hibernate JSON features:
- Cross-Database Projects: If your app needs to run on MySQL, PostgreSQL, and Oracle, JSON functions won't act the same on all of them.
- Older Hibernate Versions: Developers updating from Hibernate 5 need to be careful. New APIs don't promise easy changes.
- Hard Joins & Indexing Needs: JSON fields are tough to index. This makes it harder to speed things up when used with regular tables.
In these cases, save JSON data. Then, process it in your app later with a Java JSON parser.
Looking Ahead: JSON in Spring Boot and Hibernate
Future plans for Hibernate and Spring show more JSON integration.
🔮 Expected changes:
- ✅ Better Criteria support for JSON path objects.
- ✅ Safer ways to use JSON across different database types.
- ✅ Spring Data methods to rely less on raw query strings.
- ✅ Strong reactive data access with JSON fields.
JSON is more and more seen as key, not just an option, when mixing relational and document data methods.
Other Options to Hibernate's JSON Functions
If you don't want to use new features yet, think about these other options:
1. Raw JDBC
Use Spring’s JdbcTemplate or EntityManager.createNativeQuery() to fully control SQL.
2. JSON Processing in Java
Get the data as a string. Then, use Jackson, GSON, or JSON-P to change it with code.
3. Ready-Made SQL Views
Make views in the database that are ready to go. They make JSON flat for simpler queries.
4. Database-Specific Functions
Put complicated JSON processing into database functions to keep logic in one place.
Final Thoughts
Hibernate’s JSON functions give great flexibility for handling semi-structured data in a relational world, but they also have risks. With Spring Boot 4 and Hibernate 7, you now have these tools. But you must use them with purpose.
Before you start:
- Know how your database acts.
- Keep your queries separate.
- Test well.
If JSON is a main part of your data plan, think about turning on these functions. If not, regular ORM models or other parsing ways might still work best for you.
Resources and Further Reading
- Red Hat. (2023). Hibernate ORM 6.2 Final Release Notes. Retrieved from https://hibernate.org/orm/releases/6.2
- Oracle. (2022). SQL/JSON Function Reference for PostgreSQL and Oracle. Documentation retrieved from https://docs.oracle.com
- Spring. (2024). Spring Boot 4.0 Migration Guide. Retrieved from https://docs.spring.io
