DEV Community: Silver_dev

Hibernate Under the Hood. Part 7: Performance and Common Pitfalls

Silver_dev — Wed, 21 Oct 2026 20:06:49 +0000

Performance issues are rarely the fault of Hibernate itself; more often, they are caused by its misuse. The key to success is identifying these issues before they manifest in production.

How to Find Problems Before Production

Performance issues are barely visible on a small test database with a single user, but they manifest catastrophically on real data under load. Therefore, you must start by configuring diagnostics.

1. SQL and Hibernate Statistics Logging

Enable SQL query and statistics logging to see exactly what Hibernate is sending to the database.

# Show SQL in logs (in dev environment)
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

# Collect detailed statistics (number of queries, execution time)
hibernate.generate_statistics=true
logging.level.org.hibernate.stat=DEBUG

Statistics will show the total number of queries, their execution time, and the most crucial metric — the number of JDBC calls per session.

2. Slow Query Logging

Starting from Hibernate 5.4.5, you can specify a threshold, and Hibernate will log only those queries that take longer than that.

# Log queries that take longer than 100 ms
hibernate.session.events.log.LOG_QUERIES_SLOWER_THAN_MS=100

This helps quickly identify "heavy" (bottleneck) areas.

Problem #1: N+1 (and How to Fix It)

This is the most common cause of performance issues in Java applications using ORM. We have already discussed its mechanism: instead of a single query, Hibernate executes 1 + N queries.

Here are the primary treatment strategies, from most preferred to auxiliary.

Strategy 1: `JOIN FETCH` (or `@EntityGraph`)

This is the most direct and effective approach when you know in advance that the data will be needed. You explicitly instruct Hibernate to load the association in the same SQL query via a JOIN.

// In a JPQL query
@Query("SELECT o FROM Order o JOIN FETCH o.customer WHERE o.status = :status")
List<Order> findWithCustomerByStatus(@Param("status") Status status);

@EntityGraph does the same thing, but declaratively at the Spring Data repository level:

@EntityGraph(attributePaths = {"customer", "items"})
List<Order> findByStatus(Status status);

Pros: A single database query, maximum performance for known scenarios.
Cons: Works cleanly only for a single collection association per query. Attempting a JOIN FETCH on two List collections simultaneously will result in a MultipleBagFetchException or a Cartesian product.

Strategy 2: Batch Fetching (`@BatchSize` / `default_batch_fetch_size`)

This is a "safety net" and an excellent option when you cannot (or do not want to) change all queries. Hibernate continues to use lazy loading, but when you access the first entity in a "batch", it collects the IDs of the rest and loads them in a single query with an IN (...) clause.

# Global setting: Hibernate will group lazy loads into batches of 50
spring.jpa.properties.hibernate.default_batch_fetch_size=50

Or targeted on a specific collection: @BatchSize(size = 25).

Pros: Does not require query modifications, easy to enable globally, works excellently as a "safety net" against accidental N+1.
Cons: Does not eliminate N+1 completely, but reduces the number of queries from N to N / batchSize. Several database round-trips remain.

Strategy 3: DTO Projections

If you only need a few fields of the entity for reading, do not load the entire entity. Write a query that returns a DTO directly (e.g., a Java record).

@Query("SELECT new com.example.dto.OrderSummary(o.id, o.status, c.name) " +
       "FROM Order o JOIN o.customer c WHERE o.status = :status")
List<OrderSummary> findSummariesByStatus(@Param("status") Status status);

Pros: The fastest and safest approach for read-only endpoints. You load exactly the data you need, avoid creating managed entities, and completely eliminate N+1 and dirty checking.
Cons: Suitable only for reading; update operations require managed entities.
Selection hierarchy: Ideally, choose the strategy consciously for each access scenario. In practice, a combination is often used: JOIN FETCH for known "hot" paths and default_batch_fetch_size as a global safety net.

Problem #2: The `Open Session in View` (OSIV) Anti-Pattern

Spring Boot enables spring.jpa.open-in-view=true by default. This means the Hibernate session remains open for the entire HTTP request, including response rendering or JSON serialization.

Why this is dangerous:

Hides N+1: When Jackson serializes an object and triggers a lazy collection, Hibernate silently executes a query. You might not even suspect this until you check the logs.
Unpredictable queries: Database queries can be executed during the serialization phase, already after the transaction has been closed.
Long-held connections: Although OSIV does not hold the physical connection open the entire time, it allows queries to be executed at any point in the request lifecycle, which can lead to unpredictable connection pool usage.

Solution: Always disable OSIV in production.

spring.jpa.open-in-view=false

After disabling it, any lazy loading issues will become explicit (LazyInitializationException), forcing you to solve them correctly — via JOIN FETCH, @EntityGraph, or DTOs — rather than sweeping them under the rug.

Problem #3: Slow Batching (Bulk Inserts/Updates)

If you save 1,000 entities via saveAll(), Hibernate will execute 1,000 separate INSERT statements by default, which can take minutes. Batching allows you to group them into a few packets.

Configuration to enable batching:

spring.jpa.properties.hibernate.jdbc.batch_size=50
spring.jpa.properties.hibernate.order_inserts=true
spring.jpa.properties.hibernate.order_updates=true
spring.jpa.properties.hibernate.jdbc.batch_versioned_data=true

batch_size: the number of statements in a single batch (optimal is 20–50).
order_inserts / order_updates: group similar operations together, which is necessary for effective batching.

Critical Pitfall: GenerationType.IDENTITY

If your entity uses @GeneratedValue(strategy = GenerationType.IDENTITY), batching will not work. Hibernate is forced to execute each INSERT individually to immediately obtain the database-generated ID. Use GenerationType.SEQUENCE instead. Hibernate can pre-allocate a block of IDs from the sequence and then execute all inserts in a single batch.

Summary

Hibernate performance issues are almost always a consequence of its misuse, not its internal flaws.
Diagnostics come first. Enable show-sql and generate_statistics in the dev environment to see the actual number and execution time of queries.
N+1 is enemy #1. Treat it with JOIN FETCH (for known scenarios) or @BatchSize (as a global safety net). For read-only endpoints, DTO projections are the cleanest and fastest solution.
open-in-view is an anti-pattern for REST APIs. Disable it (spring.jpa.open-in-view=false). This will make lazy loading issues explicit and force you to solve them correctly.
Batching does not work with IDENTITY. Use GenerationType.SEQUENCE for efficient bulk inserts.
Consciously choose the fetching strategy for each scenario. LAZY is the correct default, but it requires explicit management via JOIN FETCH, @EntityGraph, or DTOs, especially when OSIV is disabled.

Hibernate Under the Hood. Part 6: Transaction Management and Locking

Silver_dev — Wed, 21 Oct 2026 19:46:56 +0000

Hibernate and Spring ensure data integrity during concurrent operations. It is crucial to understand two key mechanisms here: transactions, which define the boundaries of a unit of work, and locks, which resolve conflicts during concurrent access.

Transaction Management in Spring and Hibernate

At the core is the @Transactional annotation, which wraps a method in a transaction via Spring AOP (proxies) and decides when to commit or roll it back.

Key point — Rollback Rules:
By default, Spring rolls back a transaction only for unchecked exceptions (RuntimeException and Error). For checked exceptions (subclasses of Exception, but not RuntimeException), the transaction commits by default. This is a frequent source of errors: a developer throws an IOException and expects a rollback, but the data is partially saved.

// Explicit rollback management
@Transactional(
    // rollback for checked exceptions
    rollbackFor = { IOException.class, PaymentGatewayException.class },
    // commit for RuntimeException (e.g., to retry later) 
    noRollbackFor = { OptimisticLockException.class } 
)
public void processOrder(Order order) throws IOException {
    // ...
}

Important: A rollback will only trigger if the exception "escapes" the @Transactional method. If you catch it inside the method, Spring will not know about it, and the transaction will commit.

Isolation Levels:
Spring allows you to explicitly specify the isolation level (Isolation.READ_COMMITTED, REPEATABLE_READ, etc.). By default, it uses Isolation.DEFAULT, which relies on the underlying database's default settings. This can be dangerous if different environments (e.g., staging and production) use different databases with different default levels — the code's behavior will become unpredictable.

Propagation:
Defines how a method's transaction relates to an existing one. For example, Propagation.REQUIRES_NEW always creates a new transaction, suspending the outer one. This is useful for operations that must be committed independently (e.g., audit logging).

Locking: Conflict Resolution Strategies

Hibernate, like JPA, offers two fundamentally different approaches to locking: optimistic and pessimistic.

Optimistic Locking

Based on the assumption that conflicts are rare. Transactions do not lock data during reads, but before committing, they check if anyone else has modified the data since it was read.

It is implemented via a field annotated with @Version (a number or Timestamp). On every update, Hibernate executes SQL like UPDATE ... SET version = version + 1 WHERE id = ? AND version = ?. If no rows satisfy the WHERE condition (because the version changed), an OptimisticLockException is thrown.

When to use: For most web applications and scenarios with rare conflicts. It is a scalable and performant approach.
LockModeType modes: OPTIMISTIC (version check on commit) and OPTIMISTIC_FORCE_INCREMENT (forced version increment even without actual changes).

Pessimistic Locking

Based on the assumption that conflicts are likely. Data is locked at the database level for the duration of the transaction, preventing other transactions from modifying or reading it.

It is implemented via LockModeType (e.g., PESSIMISTIC_WRITE), which translates to SQL SELECT ... FOR UPDATE.

When to use: For critical operations with high contention (e.g., deducting money from an account), where rollbacks and retries are undesirable or too costly.
Risks: Locks are held until the end of the transaction, which can lead to deadlocks and reduced throughput.

Typical Mistakes and Pitfalls

Misunderstanding rollback rules: Expecting a rollback for a checked exception, or conversely, committing after a RuntimeException that was caught and swallowed inside the method.
"Poisoned" session: After an exception (e.g., DataIntegrityViolationException), the Hibernate session may be marked as rollback-only. Subsequent operations in this transaction will fail. The solution is to use Propagation.REQUIRES_NEW to isolate the failing operation.
Spurious OptimisticLockException: Can occur when using orphanRemoval and complex object graphs, where Hibernate attempts to update an already deleted entity. Sometimes em.flush() followed by em.clear() helps to synchronize the state.
Mixing strategies: The presence of @Version (optimistic locking) does not bypass the version check even when using SELECT ... FOR UPDATE (pessimistic locking). If another transaction modified the data, an OptimisticLockException will still be thrown upon update.
Long transactions: Holding a pessimistic lock or an open session during user interaction (e.g., via OpenSessionInView) is a direct path to connection pool exhaustion and deadlocks.

What to Use and When

Feature	Optimistic Locking	Pessimistic Locking
Principle	Conflicts are rare. Check before commit.	Conflicts are likely. Lock in the DB.
Implementation	`@Version`	`LockModeType.PESSIMISTIC_WRITE` (`SELECT ... FOR UPDATE`)
When to use	Most web apps, CRUD, rare updates.	Critical operations with high contention (finance, reservations).
Risks	`OptimisticLockException` on conflict (requires handling/retry).	Deadlocks, reduced throughput, long-held locks.

Summary

Spring rolls back only RuntimeException and Error by default. For checked exceptions, rollback must be explicitly specified via rollbackFor.
The exception must "escape" the @Transactional method for Spring to perform a rollback. Do not swallow exceptions inside the method.
Optimistic locking (@Version) is a version check upon update. It does not lock data, but merely reports a conflict (OptimisticLockException). This is the default choice for most systems.
Pessimistic locking (SELECT ... FOR UPDATE) is an actual lock at the database level. Use it sparingly, only where its absence would cause a critical data integrity error.
Isolation.DEFAULT can lead to different behavior across environments. For critical operations, specify the isolation level explicitly.
Propagation.REQUIRES_NEW is your tool for isolating failing operations (e.g., logging) that should not affect the main transaction's rollback.

Hibernate Under the Hood. Part 5: Caching

Silver_dev — Wed, 21 Oct 2026 18:21:51 +0000

Caching in Hibernate is a multi-level system, and understanding its architecture is critical for application performance. The golden rule: caching is disabled by default (except for the first-level cache), and it must be enabled consciously for specific data. The system consists of three independent layers, each with its own area of responsibility.

First-Level Cache

This is the foundation that cannot be disabled. It is always active and bound to a specific session (Session/EntityManager).

What it is: Essentially, this is the Persistence Context. All entities loaded within a single session are placed into this cache.
Scope: Only within a single session (usually a single transaction). Once the session is closed, the cache is destroyed.
Guarantees: It ensures the identity map (a repeated get for the same ID returns the exact same Java object instance) and dirty checking (Hibernate compares the current state with the snapshot upon flush).
Management: You cannot disable it, but you can manage its contents: session.evict(entity) removes a specific object, and session.clear() completely empties the cache. This is highly useful during batch processing of large data volumes to prevent Out-Of-Memory (OOM) errors.

Second-Level Cache

This is a shared cache that lives at the SessionFactory level and is shared across all sessions. It is designed for data that is rarely updated and frequently read.

Scope: Process level (or cluster level, if a distributed provider is used). Data survives session closure.
What is cached: Entity state (by their ID). It does not cache query results.
Disabled by default. To enable it, three conditions must be met:
- Activate the cache in the settings (hibernate.cache.use_second_level_cache=true).
- Provide a cache provider (Ehcache, Caffeine, Infinispan, Redis, etc.).
- Explicitly mark each entity with the @Cache annotation. Global activation does not cache everything indiscriminately — entities must "opt-in" to caching.

Concurrency Strategies (CacheConcurrencyStrategy):
When configuring @Cache, you must specify a strategy that defines how the cache behaves during concurrent updates.

Strategy	When to use	Characteristics
`READ_ONLY`	Immutable reference data	Fastest and safest. Throws an exception on update attempts.
`NONSTRICT_READ_WRITE`	Updates are rare and unlikely	No locks. Slight risk of reading stale data during an update.
`READ_WRITE`	Updates are possible	Uses "soft" locks to prevent reading stale data during a transaction.
`TRANSACTIONAL`	Strict consistency required	Full transactional locks. Requires explicit support from the cache provider.

Management: sessionFactory.evict(Entity.class, id) allows targeted removal of an entity from the second-level cache.

Query Cache

This is a specialized cache for query results. It works as an extension to the second-level cache and does not replace it. What is cached: The result of a query (JPQL/Criteria) with a specific set of parameters. Only the identifiers of the found entities and scalar values are cached, not the state of the entities themselves.
Dependency: Since the query cache stores only IDs, Hibernate will reach out to the second-level cache to fetch the actual entity data. If the entity is not there, a database query will be executed. Therefore, the query cache is always used in tandem with the second-level cache.
How to enable:
- Activate globally: hibernate.cache.use_query_cache=true.
- For each specific query, call .setCacheable(true).
Invalidation: The query cache is highly sensitive to changes. Any update to a table involved in the query invalidates the corresponding cached results. Hibernate tracks this via the UpdateTimestampsCache region.

Pitfalls and Common Mistakes

Expecting the second-level cache to work "out of the box". This is the most common mistake. Enabling the global setting is completely useless if the entities lack the @Cache annotation.
Caching "volatile" data. If an entity is frequently updated, the cache will constantly invalidate, creating overhead without providing any performance benefit. Cache only "reference" or rarely changing data.
Cluster consistency issues. When using multiple application instances, a standard second-level cache (e.g., based on local memory) does not synchronize between them. One instance might update data, while another continues to serve stale data from its local cache. The solution is a distributed cache (Redis, Infinispan, Hazelcast) that synchronizes invalidation across nodes.
Using READ_WRITE without lock support. The READ_WRITE strategy requires the cache provider to support locking. Not all providers can do this, and the provider's documentation usually contains explicit warnings about it.
Query cache overhead. The query cache only makes sense for frequently repeated queries with the exact same parameters. For ad-hoc or unique queries, it creates unnecessary invalidation overhead.

Summary

First-level cache is always on, lives within a session, and ensures identity and dirty checking. Manage it via evict/clear during batch processing.
Second-level cache is shared across sessions but off by default. It requires a provider and an explicit @Cache annotation on each entity. Choose the strategy (READ_ONLY, READ_WRITE, etc.) based on the data's update frequency.
Query cache caches only the IDs of results for repetitive queries. It always works in tandem with the second-level cache; otherwise, it is pointless.
Caching is a trade-off between read speed and the risk of serving stale data. Do not cache everything indiscriminately; start with READ_ONLY for reference tables.
In a cluster, always use a distributed cache (Redis/Infinispan), otherwise data consistency will be compromised.

Hibernate Under the Hood. Part 4: Querying

Silver_dev — Wed, 21 Oct 2026 16:48:02 +0000

The chapter on querying languages is where Hibernate stops being just "magic" and becomes a manageable tool. Here, it is crucial to understand three approaches and their boundaries: HQL/JPQL (declarative, object-oriented), Criteria API (programmatic, type-safe), and Native SQL (direct database access). In Spring projects, there is an additional layer on top of this: Spring Data JPA, which changes how you write 90% of your queries.

HQL and JPQL: Object-Oriented SQL

HQL is Hibernate's proprietary language, while JPQL is the JPA standard inspired by early HQL. It is important to know the relationship: HQL is a superset of JPQL. Any valid JPQL query is a valid HQL query, but not vice versa: HQL supports more features (e.g., insert ... select, which is absent in JPQL).

The main difference from SQL is that you operate on entities and their fields, not tables and columns. In HQL, Book is a Java class, and book.title is its field. Direct referencing of database table and column names is prohibited. Because of this, HQL is more compact than SQL and portable across different databases.

Mapping Example:

-- SQL
SELECT book.title, pub.name
FROM Book AS book
JOIN Publisher AS pub ON book.publisherId = pub.id
WHERE book.title LIKE 'Hibernate%'
ORDER BY book.title

// HQL / JPQL
SELECT book.title, pub.name
FROM Book AS book
JOIN book.publisher AS pub
WHERE book.title LIKE 'Hibernate%'
ORDER BY book.title

Note: the join is performed on the association (book.publisher), not on the foreign key column. Hibernate knows how to resolve it automatically.

Key HQL features you need to know:

Parameters: Named (:name) and positional (?1). Named parameters are preferred for readability, while positional ones are often used in native queries.
JOIN FETCH: The primary tool for combating the N+1 query problem. It loads the association immediately in a single query.
DTO projections: You can return a DTO directly instead of an entity, e.g., new com.example.dto.BookDto(book.title, pub.name). This saves memory and avoids creating managed objects.
update / delete: Bulk operations executed as a single SQL statement that bypass the Persistence Context (in-memory entities will not be updated — this is a pitfall).

HQL Pitfalls:

Bulk update/delete does not synchronize with the first-level cache. If you loaded a Book into the session and then executed update Book set title = ..., the in-memory object will retain the old title. You need session.clear() or refresh().
JOIN FETCH on two collections simultaneously results in a MultipleBagFetchException or a Cartesian product. The solution is to use @BatchSize / SUBSELECT, or split it into two separate queries.
JOIN FETCH + pagination (setMaxResults) can yield incorrect results: Hibernate applies the limit in memory, not in the SQL query. This is a known limitation.

Criteria API: Queries as Code

The Criteria API is a programmatic way to build queries. Instead of a string, you construct the query from objects: CriteriaBuilder, CriteriaQuery, Root, and Predicate. This provides type safety (the compiler checks field names if you use the metamodel) and flexibility for dynamic conditions.

When the Criteria API is indispensable:

Search screens with a variable set of filters. For example, a user might specify a price, category, brand — or nothing at all. Concatenating an HQL string with if statements is a source of bugs; the Criteria API handles this cleanly.
Dynamic sorting and pagination with type checking.
Building queries in libraries and frameworks where you do not know the entity structure in advance.

Example (simplified):

CriteriaBuilder cb = session.getCriteriaBuilder();
CriteriaQuery<Book> cq = cb.createQuery(Book.class);
Root<Book> book = cq.from(Book.class);

List<Predicate> predicates = new ArrayList<>();
if (title != null) predicates.add(cb.like(book.get("title"), "%" + title + "%"));
if (minPrice != null) predicates.add(cb.ge(book.get("price"), minPrice));

cq.where(predicates.toArray(new Predicate[0]));
cq.orderBy(cb.asc(book.get("title")));

List<Book> result = session.createQuery(cq).getResultList();

Drawbacks of the Criteria API:

Verbosity. A simple query turns into 10–15 lines of code.
Poorer readability compared to HQL, especially for complex joins.
Not for "one-off" queries. If a query is static, HQL is shorter and clearer.

Practical rule: static queries → HQL/JPQL; dynamic queries (search, filters) → Criteria API.

Native SQL: When ORM is Powerless

Sometimes you need to drop down to the database level. Native SQL is justified when:

You need a database-specific feature (window functions, LATERAL JOIN, hints, FOR UPDATE SKIP LOCKED, specific syntax).
The query is too complex for HQL and easier to write in SQL than to assemble via Criteria.
You need maximum performance in a bottleneck where HQL generates suboptimal SQL.
You are working with stored procedures.

Example:

Book book = session.createNativeQuery(
    "SELECT * FROM books WHERE isbn = ?1", Book.class)
    .setParameter(1, isbn)
    .getSingleResult();

Native Query Pitfalls:

Flush behavior: Hibernate does not flush by default before executing native queries, because it does not know which tables the query will affect. If there are unsaved changes in the Persistence Context, the native query might return stale data. The solution is an explicit session.flush() before the query or configuring the FlushMode.
Result mapping: For simple cases (SELECT * matching an entity), Hibernate infers the mapping automatically. For complex queries (aliases, aggregates, joins), you need @SqlResultSetMapping or manual parsing of Object[], which is cumbersome and fragile.
Portability: Native SQL ties you to a specific database dialect. If you plan to switch databases, use it sparingly.

Spring Data JPA: How It Looks

In Spring Boot, you rarely write session.createQuery() directly. Instead, you use Spring Data JPA repositories, which offer three levels of abstraction:

Derived queries (from method names): findByEmailAddressAndLastname(String email, String lastname) is automatically translated into JPQL: SELECT u FROM User u WHERE u.emailAddress = ?1 AND u.lastname = ?2. This works for simple queries, but method names become cumbersome with 3+ conditions.
@Query with JPQL/HQL: An explicit query on a repository method. This is the standard for medium-complexity queries:

   @Query("SELECT b FROM Book b JOIN FETCH b.author WHERE b.title LIKE %:title%")
   List<Book> findWithAuthorByTitle(@Param("title") String title);

@Query(nativeQuery = true): Native SQL when JPQL is insufficient. The nativeQuery flag explicitly tells Spring Data that this is not JPQL.

Important: Spring Data JPA does not generate JPQL for UPDATE and DELETE from method names — only for SELECT. For modifications, you need @Query + @Modifying.

What to Use When

Approach	When to choose	Pros	Cons
HQL/JPQL	Static queries, 80% of cases	Compact, portable, readable	Not for dynamic queries; strings are not checked by the compiler
Criteria API	Dynamic filters, search, libraries	Type-safe, flexible	Verbose, harder to read
Native SQL	DB specifics, complex queries, performance	Full control over SQL	Not portable, requires manual mapping, flush nuances
Spring Data (derived)	Simple CRUD and selections	Minimal code	Cumbersome names, `SELECT` only
Spring Data `@Query`	Medium-complexity queries	Explicit, readable, located in the repository	Strings are not checked by the compiler

What to Remember

HQL is a superset of JPQL. Write in JPQL for portability; use HQL features consciously.
HQL operates on entities, not tables. This is its strength (compactness, portability) and its limitation (cannot use DB-specific features).
Criteria API is for dynamic queries, HQL is for static ones. Do not try to build a simple query using Criteria — it is overkill.
Native SQL is a targeted tool. Always remember about flush and result mapping.
JOIN FETCH is your best friend against N+1, but it has limitations (pagination, two collections).
Bulk update/delete in HQL does not synchronize with the first-level cache. You need clear() after them.
In Spring Data, 90% of queries are @Query with JPQL. Derived queries are for simple cases, native queries are for exceptions.

Hibernate Under the Hood. Part 3: Entity Mapping

Silver_dev — Wed, 21 Oct 2026 15:08:03 +0000

Entity mapping is the foundation of working with Hibernate/JPA. It defines how Java objects are mapped to database tables.

Basic Annotations: Where an Entity Begins

Any mapping starts with declaring a class as an entity and defining its primary key.

@Entity: Marks the class as an entity that will be mapped to a database table. This is a mandatory annotation.
@Table: Allows you to explicitly specify the table name. If omitted, Hibernate will default to the class name (e.g., for User, the table will be User).
@Id: Defines the field that serves as the primary key.
@GeneratedValue: Specifies that the primary key value will be generated automatically. The GenerationType.IDENTITY strategy (database auto-increment) is one of the most common and straightforward.
@Column: Used for fine-tuning the column: you can specify its name, length, precision, forbid null values, etc.

Example of a simple entity:

@Entity
@Table(name = "users")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(name = "full_name", nullable = false)
    private String name;

    // ... getters and setters
}

Relationship Types: From One-to-One to Many-to-Many

In JPA, there are four main types of relationships. The key concept to understand is the owning side. It is on the owning side that the relationship is defined in the database (e.g., which table will hold the foreign key or the join table).

@ManyToOne (Many-to-One): The most common and basic relationship. It maps directly to a foreign key in the table. Important: By default, JPA uses FetchType.EAGER for this, which is almost always undesirable.

@Entity
public class Book {
    // ...
    @ManyToOne(fetch = FetchType.LAZY) // Explicitly specify lazy loading!
    @JoinColumn(name = "publisher_id") // Name of the foreign key column
    private Publisher publisher;
}

@OneToMany (One-to-Many): The inverse side of @ManyToOne. In JPA, this relationship is almost always bidirectional and must be the non-owning (inverse) side. For this, the mappedBy attribute is used, pointing to the field in the child entity that owns the relationship.

@Entity
public class Publisher {
    // ...
    @OneToMany(mappedBy = "publisher", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<Book> books = new ArrayList<>();
}

@OneToOne (One-to-One): A relationship where one record in table A corresponds to exactly one record in table B. Like @ManyToOne, it defaults to EAGER fetching. To enable lazy loading on the child side (where the foreign key resides), you must explicitly use @JoinColumn.
@ManyToMany (Many-to-Many): Requires an intermediate join table. The owning side defines this table using the @JoinTable annotation.

// Owning side
@Entity
public class Student {
    @ManyToMany
    @JoinTable(
        name = "student_course",
        joinColumns = @JoinColumn(name = "student_id"),
        inverseJoinColumns = @JoinColumn(name = "course_id")
    )
    private Set<Course> courses = new HashSet<>();
}

// Inverse (non-owning) side
@Entity
public class Course {
    @ManyToMany(mappedBy = "courses")
    private Set<Student> students = new HashSet<>();
}

Cascades (`CascadeType`) and `orphanRemoval`

These mechanisms determine how operations performed on one entity affect its related entities.

CascadeType: Defines which operations (persist, remove, update) should be cascaded to related entities.
- CascadeType.PERSIST: When the parent is saved, new child entities are automatically saved as well.
- CascadeType.REMOVE: When the parent is deleted, all related child entities are also deleted.
- CascadeType.ALL: Applies all operations. Use with caution, only if the child entity cannot exist without the parent.
orphanRemoval = true: A more specific and powerful tool. It deletes a child entity if it is "unlinked" from the parent (e.g., removed from the List<Book> collection in Publisher), even if the parent entity itself is not deleted. This is ideal for modeling strict "composition" relationships.

Fetch Strategies (`FetchType`): `LAZY` vs `EAGER`

This is one of the most critical topics for application performance.

FetchType.LAZY (Lazy): Hibernate loads the related entity only upon the first access to it. This is the recommended default approach for all relationships, especially for collections (@OneToMany, @ManyToMany), as it prevents the N+1 query problem and excessive data loading.
FetchType.EAGER (Eager): Hibernate loads the related entity immediately, along with the parent. While this might seem convenient, in practice, it often leads to loading massive amounts of unnecessary data and severe performance issues.

The golden rule: Always explicitly specify fetch = FetchType.LAZY for all @ManyToOne and @OneToOne relationships, as EAGER is their default value.

Best Practices and Common Pitfalls

Always use FetchType.LAZY for @ManyToOne and @OneToOne. This is the single most important rule for avoiding performance bottlenecks.
Define the owning side correctly. For @OneToMany, use mappedBy on the "one" side, and @JoinColumn on the "many" (owning) side.
Be cautious with CascadeType.ALL. Apply it only for true compositions, where the child object has no business meaning without the parent.
Use orphanRemoval = true for clean deletion of child entities when they are removed from a collection.
Don't forget @JsonIgnoreProperties (or @JsonManagedReference/@JsonBackReference) when serializing bidirectional relationships to JSON to avoid infinite recursion.
To load lazy relationships, use JOIN FETCH or @EntityGraph, rather than relying on OpenSessionInView, which is widely considered an anti-pattern.

Hibernate Under the Hood. Part 2: Entity Lifecycle and the Persistence Context

Silver_dev — Tue, 20 Oct 2026 22:27:23 +0000

This is arguably the most important topic in Hibernate. If you understand entity states and what happens inside the Persistence Context, 80% of Hibernate-related bugs cease to be a mystery.

What is the Persistence Context

The Persistence Context is a container of managed entities within a Session/EntityManager. Its key properties are:

It is a first-level cache. All loaded entities live here until the session is closed.
It guarantees identity. Within a single session, calling get(User.class, 1L) twice will return the exact same Java object instance (Identity Map pattern).
It tracks changes. Upon flush, Hibernate compares the current state of entities with their snapshot and generates an UPDATE only for the modified fields (dirty checking).
It implements write-behind. save/persist do not write to the DB immediately — changes are accumulated and synchronized upon flush.

User u1 = session.get(User.class, 1L);
User u2 = session.get(User.class, 1L);
System.out.println(u1 == u2); // true — the exact same object instance

This is not "optimization for the sake of optimization". It is a semantic guarantee: within a single unit of work, you always work with the same object instance, preventing the scenario of "two objects, both representing User with id=1, one with name='A' and the other with name='B'".

The Four Entity States

1. Transient (New / Unmanaged)

The object is created via new, but Hibernate knows nothing about it.

User user = new User();  // Transient
user.setName("Alice");

This is a regular Java object created with the new operator. It is not associated with the database or the current Hibernate session.

Database connection: None. No corresponding record exists in the database.
Identifier (ID): Usually null (unless set manually, but Hibernate will ignore it).
Tracking: Hibernate does not track changes to its fields. If you modify a field and do nothing else, nothing goes to the DB.
Analogy: A document draft written on your desk. It is not yet registered in the archive.

How to transition to another state:

To Persistent: call session.save() or session.persist().
To Detached: (rarely done directly; usually, the object is saved first, and then the session is closed).

2. Persistent (Managed)

session.persist(user);   // user is now Persistent
user.setName("Bob");     // changes are tracked
// upon flush, Hibernate will generate an UPDATE

The object is managed by the current session. It has a representation in the database (it is already saved there or will be upon flush).

Database connection: Direct. The object corresponds to a row in the table.
Identifier (ID): Must have a value (the ID from the DB).
Tracking: Hibernate closely monitors the object (via Dirty Checking). If you modify any field of this object, Hibernate will notice and automatically generate and execute an UPDATE SQL query on the next flush().
Analogy: A document you pulled from the archive, opened in the system, and are editing. The system sees all your changes and will save them when you click "Save" (flush).

How to get into this state:

From Transient: session.save(), session.persist().
From Detached: session.update(), session.saveOrUpdate(), session.merge().

How to leave this state:

To Detached: close the session (session.close()), clear it (session.clear()), or evict the object from the session cache (session.evict()).
To Removed: call session.delete() or session.remove().

3. Detached

session.close();
// all previously loaded entities are now Detached

The object was in the Persistent state (it has an ID and exists in the DB), but lost its connection to the current session (the session was closed or the object was evicted from it).

Database connection: The object exists in the database.
Identifier (ID): Must have a value.
Tracking: Hibernate does not track it. If you modify a Detached object's field, nothing goes to the DB until you "re-attach" it to a session.
Analogy: A document you physically took from the archive to your desk. You can read and even change it, but the archive system knows nothing about it. To apply changes to the archive, the document must be returned (via merge/update).

How to get into this state:

From Persistent: close the session (session.close()), clear the cache (session.clear()), or evict the object (session.evict()).

How to transition to another state:

To Persistent: call session.update(), session.saveOrUpdate(), or session.merge() (in a newly opened session).

4. Removed

session.remove(user);  // Removed
// upon flush → DELETE FROM users WHERE id = ?

The object is marked for deletion. It is still associated with the session, but "doomed".

Database connection: The record still exists in the DB but is marked for deletion.
Tracking: On the next flush() or commit(), Hibernate will generate a DELETE SQL query and remove the row from the database.
Analogy: A document stamped with a red "DESTROY" mark. It is still in the system, but at the end of the workday (upon commit), it will be sent to the shredder.

How to get into this state:

From Persistent: call session.delete() or session.remove().

Key Takeaway

The most common beginner mistake is attempting to modify a Detached object and expecting it to update in the DB automatically.

Remember: changes are automatically pushed to the DB only from the Persistent state. If an object becomes Detached (e.g., you fetched it from the DB in one method, but are trying to update it in another where the session is already closed), you must explicitly "re-attach" it via merge() or update().

`persist()` vs `save()`

Feature	`persist()` (JPA)	`save()` (Hibernate)
Returns	`void`	`Serializable` (the generated ID)
`INSERT` timing	Deferred (upon flush)	Can be immediate (if the ID is needed)
Outside a transaction	Throws an exception	Works (but it's a bad practice)
For detached objects	Throws an exception	May create a new object (or throw an error if ID exists)

Use persist() if you are working via the JPA API. It is the standard.

`merge()` vs `update()`

Feature	`merge()` (JPA)	`update()` (Hibernate)
What it does	Loads the current state from the DB, copies changes into a new managed object, and returns it	"Re-attaches" the passed detached object to the session
Returns	A managed copy	`void`
Original object	Remains detached	Becomes persistent
If the record was deleted	Creates a new record	Throws an exception

Crucial note: merge() does not make the passed object managed. It returns a different managed copy.

User detached = ...;               // Detached
User managed = session.merge(detached);
// detached — remains Detached
// managed — is now Persistent

`get()` vs `load()`

Feature	`get()`	`load()`
DB query	Immediate	Lazy (returns a proxy)
If not found	Returns `null`	Throws `EntityNotFoundException` upon access
Returns	Real object or `null`	Proxy or real object

load() returns a proxy — Hibernate provides a subclass that will fetch the actual data upon the first access to any field (except the ID).

Other Key Methods

refresh(): Reloads the object's state from the DB, overwriting it in memory. Useful if data might have been changed externally (another process, native SQL).

session.refresh(user);  // user is reloaded from the DB

evict() / detach(): Removes the object from the Persistence Context. The object becomes Detached.

session.evict(user);  // user is no longer managed

clear(): Completely clears the Persistence Context. All objects become Detached.

session.clear();  // 1st-level cache is empty

flush(): Synchronizes the Persistence Context with the DB. It does not commit the transaction — it only executes INSERT/UPDATE/DELETE statements.

session.flush();  // SQL is executed, but the transaction is not committed

When does automatic flush occur?

Before a transaction commit.
Before executing a query that might affect tables containing "dirty" entities (auto-flush).
Upon an explicit flush() call.
Upon session.close() (if uncommitted, it triggers a rollback).

Dirty Checking — How Hibernate Detects Changes

When loading an entity, Hibernate saves a snapshot — a copy of all its fields. Upon flush, it compares the current state with the snapshot.

@Transactional
public void rename(Long id, String newName) {
    User u = session.get(User.class, id);  // snapshot is saved
    u.setName(newName);                    // modified in memory
    // flush on commit: snapshot.name != u.name → UPDATE users SET name = ?
}

What this provides:

No need to call update() — changes are picked up automatically.
Generates an UPDATE only for modified fields (unless disabled).
If nothing changed, no UPDATE is executed at all.

Dirty checking triggers on flush, not on set. If you modify a field and roll back the transaction, the change won't reach the DB (which is correct). However, if you modify a field and don't commit, it remains in the object's memory.

Write-behind — Why `save` Doesn't Write Immediately

persist() does not execute an INSERT immediately. It registers the entity in the Persistence Context, and the SQL is generated upon flush.

Why:

Batching: Hibernate can collect several INSERTs and send them as a single batch (hibernate.jdbc.batch_size).
Operation ordering: Hibernate automatically sequences INSERT/UPDATE/DELETE statements to avoid violating foreign key constraints.
Efficiency: If the transaction rolls back, the INSERT was never actually executed against the DB.

Exception: If the ID generation strategy is IDENTITY (auto-increment), Hibernate is forced to execute the INSERT immediately to obtain the generated ID. This breaks batching.

Identity Map — The Uniqueness Guarantee

User u1 = session.get(User.class, 1L);
User u2 = session.get(User.class, 1L);
assert u1 == u2;  // true

How it works: The Persistence Context is essentially a Map<EntityKey, Object>, where the key is (entityClass, id). Upon get, Hibernate first checks the map. If the object is there, it returns it. If not, it loads it from the DB and puts it in the map.

Why it's needed:

Consistency guarantee: Prevents having two different objects with the same ID in memory.
Performance: Repeated get calls do not hit the DB.
Accurate dirty checking: Hibernate knows exactly which object instance to track.

The identity map lives only within a session. Across sessions, these are different objects.

// Session 1
User u1 = session1.get(User.class, 1L);
session1.close();

// Session 2
User u2 = session2.get(User.class, 1L);
assert u1 != u2;  // different object instances, both with id=1

Typical Mistakes and Pitfalls

1) LazyInitializationException

@Transactional
public User getUser(Long id) {
    return session.get(User.class, id);  // returns managed
}
// session is closed, user is now Detached

// in the controller:
user.getOrders().size();  // LazyInitializationException!

Solution: Fetch required data within the transaction (JOIN FETCH, @EntityGraph), or use DTO projections.

2) merge() does not make the original object managed

User detached = ...;
session.merge(detached);
detached.setName("new");  // NOT tracked! detached is still Detached

Solution: Work with the result of merge():

User managed = session.merge(detached);
managed.setName("new");  // NOW tracked

3) Modifying a detached object without merge()

@Transactional
public void update(User user) {  // user came from outside (detached)
    user.setName("new");
    // NOTHING happens — user is not managed
}

Solution: Use session.merge(user) or reload the entity and modify the managed instance.

4) save() vs persist() with an existing ID
If a transient object already has an ID (e.g., assigned manually), save() might assume the object is detached and execute an UPDATE instead of an INSERT. persist() will throw an exception in this situation, which is safer.

5) Long session → Memory Leak
The Persistence Context grows with every loaded entity. If a session is kept open for the entire HTTP request (OpenSessionInView) and loads thousands of objects, memory will leak.

Solution: Do not keep the session open longer than necessary; periodically flush() + clear() during batch processing.

6) flush() does not commit

session.flush();  // SQL is executed, but not committed
// if an exception occurs next — it will roll back

Solution: Remember: flush() is for synchronization, commit() is for finalizing.

7) Auto-flush before queries
Hibernate performs a flush before createQuery() if the query affects tables containing "dirty" entities. This can lead to unexpected UPDATEs in the middle of a method.

Solution: Understand this behavior; if necessary, configure FlushMode.MANUAL or COMMIT.

Example: All States in Action

@Transactional
public void demo() {
    // 1. Transient
    User user = new User();
    user.setName("Alice");

    // 2. Transient → Persistent
    session.persist(user);
    // upon flush → INSERT

    // 3. Persistent (managed)
    user.setName("Bob");  // dirty checking will pick this up on flush

    // 4. Persistent → Detached
    session.evict(user);
    user.setName("Charlie");  // NOT tracked

    // 5. Detached → Persistent (via merge)
    User managed = session.merge(user);
    // managed is now Persistent, user remains Detached

    // 6. Persistent → Removed
    session.remove(managed);
    // upon flush → DELETE
}

Summary

Persistence Context = 1st-level cache + identity map + dirty checking + write-behind. It is the heart of the Session.
Four states: Transient, Persistent, Detached, Removed. Transitions are managed via session methods.
persist() ≠ save(), merge() ≠ update(). Understand the difference.
merge() returns a copy; the original object remains detached.
Dirty checking triggers on flush, not on set.
flush() does not commit; it only synchronizes.
After session closure, objects are Detached → lazy fields are inaccessible.
The identity map lives only within a session — across sessions, objects are different instances.
Long session = memory leak. Do not keep it open longer than necessary.
LazyInitializationException is a symptom of improper state management, not a "Hibernate bug".

Hibernate Under the Hood. Part 1: Hibernate Architecture and Key Components: SessionFactory and Session

Silver_dev — Tue, 20 Oct 2026 19:37:28 +0000

Hibernate is an ORM framework that sits between your Java code and JDBC. To truly understand its behavior, you need a clear mental model of its architecture and the roles of two central objects: SessionFactory and Session. Everything else is derived from them.

Overall Architecture (Top to Bottom)

Application
    ↓
SessionFactory  (heavyweight, one per application)
    ↓
Session         (lightweight, one per unit of work)
    ↓
Persistence Context (first-level cache inside the Session)
    ↓
JDBC Connection / DataSource
    ↓
Database

And on the side: Second-Level Cache, Connection Pool, Transaction Manager, Dialect, Interceptor/Listener — all of these reside at the SessionFactory level.

SessionFactory

The SessionFactory is an immutable, thread-safe, heavyweight factory that is created exactly once per application (per database). It holds:

Mapping metadata — all entities, their fields, relationships, and fetch strategies. Built once at startup.
Second-Level Cache (if enabled).
Connection settings — DataSource, connection pool, Dialect.
Compiled SQL queries derived from HQL/JPQL (query plan cache).
Event listeners — interceptors, callbacks.
Configurations for query cache, batching, and statistics.

How it is created:

In modern Spring Boot, you don't do this manually — Spring creates the SessionFactory (more accurately, the EntityManagerFactory) during context initialization. However, understanding what happens under the hood is crucial.

In "vanilla" Hibernate:

Configuration cfg = new Configuration()
    .addAnnotatedClass(User.class)
    .configure("hibernate.cfg.xml");

SessionFactory sessionFactory = cfg.buildSessionFactory();

buildSessionFactory() is an expensive operation. It:

Reads all mappings.
Builds the metamodel.
Validates relationships.
Initializes the connection pool.
Initializes caches.
Compiles named queries.

At application startup, this takes seconds, and sometimes tens of seconds on large projects with thousands of entities.

Key Characteristics

Property	Value
Thread-safety	Yes
Lifespan	Entire application (singleton)
Creation cost	High
State	Immutable after creation
Scope	One per Application × Database
Spring equivalent	`LocalContainerEntityManagerFactoryBean`

Typical Mistakes

Creating a SessionFactory per request. This is a performance catastrophe: the entire metamodel and connection pool are rebuilt every time.
Holding multiple SessionFactory instances without a valid reason. Usually, this is only needed for multi-tenancy or working with multiple databases.
Treating it as a "connection factory". No, connections are managed by the DataSource / Connection Pool. SessionFactory is a factory for sessions, not connections.

Session

The Session is a lightweight, short-lived, NON thread-safe object representing a single unit of work with the database. In JPA terminology, it corresponds to the EntityManager.

Inside the Session lives the Persistence Context — the first-level cache where all loaded and managed entities are stored.

Lifespan

A Session is created for:

A single transaction (transaction-scoped) — the most common scenario in Spring.
A single HTTP request (request-scoped) — via OpenSessionInViewFilter (a controversial practice, see below).
A single user conversation (long session, rare).

In Spring Boot, the Session is opened and closed automatically thanks to @Transactional:

@Transactional
public void updateUser(Long id, String name) {
    User user = session.get(User.class, id); // session is open
    user.setName(name);
} // session is closed, changes are flushed

What the Session does

Provides the API for database operations: save, persist, merge, delete, get, load, createQuery, flush.
Manages the Persistence Context: tracks all loaded entities, their changes, and dirty fields (dirty checking).
Contains the First-Level Cache: every get/load checks the cache first, then the database.
Manages the transaction: via Transaction (or EntityTransaction in JPA).
Performs flushing: synchronizes in-memory changes to the database.

Key Characteristics

Property	Value
Thread-safety	No (cannot be shared across threads)
Lifespan	Single unit of work
Creation cost	Low (lightweight object)
State	Mutable
Scope	One per Transaction / Request / Unit of work

Typical Mistakes

Sharing a Session across threads. It is not thread-safe and will corrupt the Persistence Context.
Keeping a Session open for too long. The first-level cache grows, leading to memory leaks and stale data.
Using OpenSessionInView for lazy loading in controllers. This is an anti-pattern: it causes N+1 queries, unpredictable behavior, and transaction issues. It is better to explicitly fetch required data via JOIN FETCH or @EntityGraph.

Persistence Context — The Heart of the Session

This is the most crucial concept to grasp. The Persistence Context is the first-level cache living inside the Session.

What it does

Stores all managed (persistent) entities. Loaded a User? It's here.
Guarantees identity. Two calls to session.get(User.class, 1L) within the same session will return the exact same object instance (Identity Map pattern).
Dirty checking. Upon flush, Hibernate compares the current state of entities with their snapshot taken at load time, and generates an UPDATE only for the modified fields.
Write-behind. save/persist do not write to the DB immediately — they register the entity, and flush synchronizes everything in batches.

Entity States

State	Meaning	How to get there
Transient	New object, not associated with a session	`new User()`
Persistent	Managed by the session, inside the Persistence Context	`session.get()`, `session.persist()`, `session.merge()`
Detached	Was persistent, but the session is closed or the object was evicted	After `Session` closure, `session.evict()`
Removed	Marked for deletion	`session.remove()`

Dirty Checking Example

@Transactional
public void doWork() {
    User u = session.get(User.class, 1L); // loaded, snapshot saved
    u.setName("Bob");                      // modified in memory
    // flush on commit will compare with snapshot and execute UPDATE
}

No explicit session.update() is needed. This is the main magic of Hibernate.

How They Interact

Application → SessionFactory.openSession() → Session
                  ↑                              ↓
                  │                     Persistence Context (1st-level cache)
                  │                              ↓
            (created once)                 JDBC Connection (from pool)
                                                 ↓
                                          Transaction

Typical Workflow:

App startup: SessionFactory is created (once).
User request: Session is opened (for the duration of the request or transaction).
Work: Session loads entities into the Persistence Context, tracking changes.
Flush: Upon commit or explicitly, changes are synchronized to the DB.
Closure: Session is closed, Persistence Context is destroyed. Entities become Detached.

Spring Specifics

In Spring Boot, things work slightly differently:

SessionFactory → created by Spring as an EntityManagerFactory (usually LocalContainerEntityManagerFactoryBean).
Session → wrapped in an EntityManager and bound to the current thread via EntityManagerHolder.
@Transactional → manages the opening/closing of the session and transaction.
OpenEntityManagerInView → keeps the session open until the end of the HTTP request.

Useful Configuration Settings

# Logical? No — the physical connection is acquired from the pool
spring.jpa.properties.hibernate.connection.provider_disables_autocommit=true

# Batching — critical for performance
spring.jpa.properties.hibernate.jdbc.batch_size=50
spring.jpa.properties.hibernate.order_inserts=true
spring.jpa.properties.hibernate.order_updates=true

# Prevent Hibernate from modifying the DB at startup (use Flyway/Liquibase instead)
spring.jpa.hibernate.ddl-auto=validate

# Open session in view — do not use in production
spring.jpa.open-in-view=false

Summary

Criterion	`SessionFactory`	`Session`
Weight	Heavyweight	Lightweight
Thread-safety	Yes	No
Lifespan	Application	Transaction / Request
Creation	Expensive	Cheap
State	Immutable	Mutable
Contains	Metadata, 2nd-level cache, pool	Persistence Context, 1st-level cache
Spring equivalent	`EntityManagerFactory`	`EntityManager`

Key Takeaways:

SessionFactory — one per application, heavyweight, thread-safe. Created at startup, lives until shutdown.
Session — one per unit of work, lightweight, not thread-safe. Opened and closed per transaction.
Persistence Context — the first-level cache inside the Session. Provides identity, dirty checking, and write-behind.
Never share a Session across threads. Ever.
Never create a SessionFactory per request. Ever.
OpenSessionInView is an anti-pattern. Disable it in production.
After a Session is closed, entities become Detached. Attempting lazy loading will result in a LazyInitializationException.

Spring AI: First Steps

Silver_dev — Mon, 19 Oct 2026 21:50:50 +0000

Preparation

Ensure that Ollama is running and the model is downloaded:

ollama pull qwen2.5:3b

spring.ai.ollama.chat.options.model=qwen2.5:3b
spring.ai.ollama.base-url=http://localhost:11434

# Optional: temperature (0.0 - deterministic, 1.0 - creative)
spring.ai.ollama.chat.temperature=0.7

You can use any other model — the name must exactly match the output of ollama list.

1. AI Hello World

Create a controller:

package com.example.demo;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AiController {

    private final ChatClient chatClient;

    public AiController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    @GetMapping("/ai/hello")
    public String aiHello() {
        // Formulate the prompt
        String prompt = "Say 'Hello, World!' and add one short, interesting fact about the Java language.";

        // Call the model and get the response
        return chatClient.prompt()
                .user(prompt)
                .call()
                .content(); // .content() extracts just the response string from the ChatResponse object
    }
}

Open http://localhost:8080/ai/hello in your browser.

Notes:

The first request may take 2–5 seconds — the model is loading into memory.
Error 404 Model not found — check the exact model name in ollama list.
.call().content() is a synchronous call. For a chat with a typing effect, use .stream() (see section 5).

2. Structured Output (JSON → Java Record)

Spring AI can return not just plain text, but a ready-made Java object. Create a record:

package com.example.demo;

public record RoutingIntent(
    String targetService,
    String action,
    String userId,
    int priority
) {}

Add an endpoint to AiController.java:

@GetMapping("/ai/route")
public RoutingIntent routeRequest(@RequestParam String text) {
    String systemPrompt = """
        You are a smart API gateway. Analyze the user's request 
        and extract data for routing. 
        If a field is unknown, leave it empty (null or 0).
        """;

    return chatClient.prompt()
            .system(systemPrompt)
            .user(text)
            .call()
            .entity(RoutingIntent.class);
}

Example: http://localhost:8080/ai/route?text=Disable notifications for user user-999

Response: A ready-made JSON, serialized by Spring. No manual parsing required.

3. Function Calling (LLM calls Java code)

Give the model "tools" — Java methods annotated with @Tool. If the user asks, "What is the status of the payment service?", the LLM won't hallucinate an answer. Instead, it tells Spring AI: "Hey, call the getServiceStatus("payment") method, and I will use its result."

Create the SystemTools.java class. The @Tool annotation makes the method visible to the LLM.

package com.example.demo;

import org.springframework.stereotype.Service;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;

@Service
public class SystemTools {

    @Tool(description = "Checks the current status and latency (in ms) of the specified microservice")
    public String getServiceStatus(@ToolParam(description = "Name of the service, e.g., 'payment', 'auth', 'database'") String serviceName) {
        // A real call to Prometheus, ClickHouse, or your proxy logger could go here
        System.out.println(">>> LLM called Java method for service: " + serviceName);

        return switch (serviceName.toLowerCase()) {
            case "payment" -> "Status: OK, average latency 45ms.";
            case "auth" -> "Status: DEGRADED, latency 300ms, experiencing timeouts.";
            default -> "Status: Unknown service or no data available.";
        };
    }
}

Update AiController.java by adding a dependency on SystemTools:

package com.example.demo;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AiController {

    private final ChatClient chatClient;

    // Inject our tools
    public AiController(ChatClient.Builder chatClientBuilder, SystemTools systemTools) {
        this.chatClient = chatClientBuilder
                .defaultTools(systemTools) // <--- this is the key line
                .build();
    }

    @GetMapping("/ai/tool")
    public String askSystem(@RequestParam String question) {
        return chatClient.prompt()
                .user(question)
                .call()
                .content();
    }
}

Request: http://localhost:8080/ai/tool?question=What is the current status of the payment and auth services?

The LLM will decide to call getServiceStatus("payment"), Spring AI will execute the method, and the model will formulate the final response based on the result.

What happens "under the hood":

The LLM sees the question and realizes it doesn't know the answer.
It sees your @Tool and generates a special request: "Call getServiceStatus with the argument payment".
Spring AI intercepts this and calls your actual Java method.
In the console, you will see: >>> LLM called Java method for service: payment
The LLM receives the result ("Status: OK...") and formulates the final human-readable response.

4. Prompt Templates (Dynamic Prompts)

You need to formulate prompts dynamically, substituting data from the context (user name, request parameters, database results). Hardcoding prompts is a bad practice. Spring AI allows you to create prompt templates with variables, similar to Thymeleaf or Mustache.

Add a new endpoint to AiController.java:

package com.example.demo;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.prompt.PromptTemplate;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

@RestController
public class AiController {

    private final ChatClient chatClient;
    private final SystemTools systemTools;

    public AiController(ChatClient.Builder chatClientBuilder, SystemTools systemTools) {
        this.chatClient = chatClientBuilder
                .defaultTools(systemTools)
                .build();
    }

    // ... your previous /ai/hello, /ai/route, /ai/tool methods ...

    @GetMapping("/ai/template")
    public String generateWithTemplate(
            @RequestParam String userName,
            @RequestParam String serviceName,
            @RequestParam String action
    ) {
        // Create a prompt template with variables
        String templateText = """
            You are a system administrator. User {userName} wants to perform the action '{action}' 
            on the {serviceName} service. 
            Provide a brief instruction on how to do this safely.
            """;

        // Populate the variables
        PromptTemplate promptTemplate = new PromptTemplate(templateText);
        String finalPrompt = promptTemplate.render(Map.of(
                "userName", userName,
                "serviceName", serviceName,
                "action", action
        ));

        // Send the finalized prompt to the model
        return chatClient.prompt()
                .user(finalPrompt)
                .call()
                .content();
    }
}

Example: http://localhost:8080/ai/template?userName=John&serviceName=payment&action=restart

Response:

John, to safely restart the payment service, follow these steps:
1. Ensure there are no active transactions...
2. Execute the restart command...
3. Check the service logs...

Templates can be stored in separate files (.txt, .prompt) and versioned separately from the codebase.

5. Streaming (Real-time Response Streaming)

If your proxy communicates with the user in real time (e.g., a chatbot or voice assistant), waiting 2–3 seconds for a full response is bad UX. Streaming allows delivering the response token by token as soon as they are generated. For chat interfaces, use .stream() and Flux<String>. Spring Boot automatically converts this to Server-Sent Events (SSE).

Add the dependency:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

Add resources/static/stream-test.html:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>AI Stream Test</title>
    <style>
        body { font-family: Arial, sans-serif; max-width: 800px; margin: 50px auto; padding: 20px; }
        #question { width: 70%; padding: 10px; font-size: 16px; }
        button { padding: 10px 20px; font-size: 16px; cursor: pointer; }
        #response { margin-top: 20px; padding: 15px; border: 1px solid #ccc; border-radius: 8px; min-height: 150px; background: #f9f9f9; white-space: pre-wrap; font-size: 16px; line-height: 1.6; }
        .cursor { display: inline-block; width: 2px; height: 18px; background: black; animation: blink 0.7s infinite; vertical-align: text-bottom; }
        @keyframes blink { 0%, 100% { opacity: 1; } 50% { opacity: 0; } }
    </style>
</head>
<body>
    <h2>🤖 AI Streaming Chat</h2>
    <div>
        <input type="text" id="question" placeholder="Enter a question..." value="Tell me a short fact about Java">
        <button onclick="startStream()">Send</button>
    </div>
    <div id="response"></div>

    <script>
        function startStream() {
            const question = document.getElementById('question').value;
            const responseDiv = document.getElementById('response');

            // Clear previous response
            responseDiv.innerHTML = '<span class="cursor"></span>';

            // Use fetch + ReadableStream (more reliable than EventSource)
            fetch('/ai/stream?question=' + encodeURIComponent(question))
                .then(response => {
                    const reader = response.body.getReader();
                    const decoder = new TextDecoder('utf-8');

                    function read() {
                        reader.read().then(({ done, value }) => {
                            if (done) {
                                // Remove cursor when the stream ends
                                const cursor = responseDiv.querySelector('.cursor');
                                if (cursor) cursor.remove();
                                return;
                            }

                            // Decode bytes to text
                            const chunk = decoder.decode(value, { stream: true });

                            // Parse SSE: each "data:..." line
                            const lines = chunk.split('\n');
                            let text = '';
                            for (const line of lines) {
                                if (line.startsWith('data:')) {
                                    // Remove "data:" prefix and append to text
                                    text += line.substring(5);
                                }
                            }

                            // Insert text before the cursor
                            const cursor = responseDiv.querySelector('.cursor');
                            if (cursor) {
                                cursor.insertAdjacentText('beforebegin', text);
                            } else {
                                responseDiv.textContent += text;
                            }

                            // Read the next chunk
                            read();
                        });
                    }

                    read();
                })
                .catch(error => {
                    responseDiv.textContent = 'Error: ' + error.message;
                });
        }
    </script>
</body>
</html>

Add the streaming endpoint:

import org.springframework.http.MediaType;
import reactor.core.publisher.Flux;

// ... inside AiController ...

@GetMapping(value = "/ai/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE + ";charset=UTF-8")
public Flux<String> streamResponse(@RequestParam String question) {
    return chatClient.prompt()
            .user(question)
            .stream()
            .content();
}

Open in your browser: http://localhost:8080/stream-test.html

The response will appear gradually, word by word, just like in ChatGPT. This works via SSE (Server-Sent Events) — the browser receives a continuous data stream and renders it in real time.

The finale of the Vector Database Showroom series.

Silver_dev — Fri, 09 Oct 2026 19:21:26 +0000

The finale of the Vector Database Showroom series.

Six parts ago, this showroom made you a promise: we won't tell you which database to take — we'll give you a method to figure out what YOU should take. Today the showroom closes: one table, one tree, one checklist.

The roster, for the record: 🚙 pgvector, 🛴 Chroma, 🏎️ Qdrant, 🚐 Weaviate, 🚕 Pinecone, 🚄 Milvus — the station wagon, the scooter, the hatchback, the crossover, the taxi, and the train.

The cost-of-ownership table

Vehicle	License / self-host	Sweet spot	Signature feature	Main pain	Ops burden	Managed by
🚙 pgvector	PostgreSQL license, self-host anywhere	~1M comfortable, ~10M tuned	ACID + joins — vectors live with your data	Vertical ceiling; RAM for the HNSW graph	Your usual Postgres routine	RDS, Aurora, Cloud SQL, AlloyDB, Azure, Supabase, Neon
🛴 Chroma	Apache 2.0, embedded or server	Prototypes; single-digit millions	First search in 90 seconds, embeddings included	Single node by design; prototype-grade durability	None — until it's suddenly too many	Chroma Cloud
🏎️ Qdrant	Apache 2.0, single binary → cluster	Millions → hundreds of millions (quantized)	Filterable HNSW — filters live inside the index	Manual snapshots; a tuning culture	Light-to-medium DevOps	Qdrant Cloud
🚐 Weaviate	BSD-3-Clause, containers	Multi-tenant SaaS; scale via distributed mode	Factory vectorization + built-in BM25F hybrid + native tenancy	A service bay for all those options; the v3/v4 client split	Medium DevOps	Weaviate Cloud
🚕 Pinecone	Proprietary — cloud only	Prototype → billions, if the wallet agrees	True zero ops + serverless	A closed box, and the meter (read units)	None — the dealer's problem	Pinecone only
🚄 Milvus	Apache 2.0 — Lite / Standalone / Distributed	Hundreds of millions → billions	Capacity scales with object storage; GPU_CAGRA; DiskANN	The rails: etcd, Pulsar/Kafka, MinIO/S3	Real ops muscle	Zilliz Cloud

Two synthesis notes the table doesn't fit:

Hybrid search out of the box: yes — Qdrant (dense + sparse, RRF/DBSF fusion), Weaviate (BM25F built in), Milvus (built-in BM25). No — pgvector, Chroma. Pinecone: you bring the sparse vectors yourself (the Qdrant model, not the built-in-BM25 model of Weaviate/Milvus) — check the docs for the current state before betting on it.
Multi-tenancy, natively: Weaviate (tenant = shard), Pinecone (namespaces), Milvus (partition keys / separate databases). pgvector covers it with RLS; Qdrant expects payload filters; Chroma assembles nothing for you.

The recurring math of the series: 1M × 1536-dim × 4 bytes ≈ 6 GB of raw vectors — and an HNSW graph stores a copy of every vector, so roughly double it before picking instance sizes.

Honorable mentions, three lines: Elasticsearch/OpenSearch — if it's already your stack and the vector requirements are modest. Redis — when you need sub-millisecond and already run it. FAISS — an engine, not a car: blazingly fast, but no garage, no service, no keys — you build the car around it.

flowchart TD
    START["You need vector search"] --> Q1{"Prototyping, learning,\nor a personal tool?"}
    Q1 -- "Yes" --> CHROMA["🛴 Chroma"]
    Q1 -- "No" --> Q2{"Data already in Postgres\nand under ~10M vectors?"}
    Q2 -- "Yes" --> PGVECTOR["🚙 pgvector"]
    Q2 -- "No" --> Q3{"Anyone on the team\nwants to own infrastructure?"}
    Q3 -- "Yes — wants to own infra" --> Q4
    Q3 -- "Must self-host (compliance)" --> Q4
    Q4{"Hundreds of millions\nto billions of vectors?"}
    Q4 -- "Yes" --> MILVUS["🚄 Milvus — or rent Zilliz Cloud"]
    Q4 -- "No" --> Q5{"Many tenants, want\nvectorization + hybrid\nfrom the factory?"}
    Q5 -- "Yes" --> WEAVIATE["🚐 Weaviate"]
    Q5 -- "No" --> QDRANT["🏎️ Qdrant"]

Two honest notes on the tree:

No Postgres yet? The wagon is still an option — managed Postgres is one click away (Part 1). The garage is not a prerequisite.
Data can't leave your perimeter AND nobody wants ops? That's a hiring problem, not a database problem. No car in this showroom fixes it — and pretending otherwise is how two-week adventures begin.

The one-day test drive

Pick 2–3 finalists from the tree — not all six. Then:

Before you start

One embedding model for all candidates — the honest-comparison rule since Part 3
Real data: 10–50k real documents and 50–100 real queries from your product. Lorem ipsum measures lorem ipsum
Deploy the gauge you'll actually ride: if production is a cluster, benchmark the cluster shape — the Milvus lesson

(2–3 hours)

Create the schema and payload/metadata indexes before loading — the Qdrant and Milvus lessons
Load the data. Then wait: settled segments, built indexes (benchmark traps #1 and #2). A benchmark on fresh data measures brute force, not your index

(2 hours) — the scorecard

Recall@10 vs exact ground truth. Brute-force the same vectors yourself — at 50k rows it takes seconds:

import numpy as np

# vectors: (N, 1536) of your uploaded embeddings, query: (1536,)
# ground truth must use the SAME metric you query with —
# for cosine, normalize first
scores = vectors @ query
truth_indices = set(np.argsort(scores)[-10:][::-1])   # exact top-10 INDICES into `vectors`

# Option 1: if your DB returns positions in the same order you uploaded,
# compare indices directly
recall = len(truth_indices & set(returned_indices)) / 10

# Option 2: if your DB returns IDs, map indices to IDs first —
# the upload order defines the mapping, keep it consistent
# ids = ["doc_0", "doc_1", ...]          # index i -> id, fixed at upload time
# truth_ids = {ids[i] for i in truth_indices}
# recall = len(truth_ids & set(returned_ids)) / 10

p95 latency at your realistic QPS, not the demo QPS
RAM after indexing — expect roughly 2× the raw vectors (the series rule)
Filtered search: does "similar AND year=2024" return the full LIMIT? (the Part 1 trap)
Insert → immediately search: flaky? Now you know before production does (the taxi and the train)
Kill the process mid-write (self-hosted) or test retry after errors (managed) — then check nothing was lost
Export everything back out — measure the exit in hours, not promises

(1 hour) — the bill

Managed (Pinecone): your real QPS × top_k → read units → dollars. Managed (Qdrant / Weaviate / Zilliz Cloud): RAM + CPU → monthly subscription. Either way, the meter never sleeps
Self-hosted: the RAM you measured → the smallest instance that fits → × 12 months
Fill the scorecard, then sleep on it:

Candidate	recall@10	p95, ms	RAM after index, GB	$/month at your QPS	Exit, hours	Gut feeling
...

Yes, "gut feeling" is a column. DX is a cost of ownership too — you'll pay it every working day.

Next morning: re-run the same queries cold. Numbers that only look good warm are a finding, not a footnote.

The method doesn't expire

Everything in this series was true at the time of writing; databases evolve — verify versions against the docs. The method doesn't expire: judge by cost of ownership, verify on your data, buy for the scale you have, re-check at the scale you reach.

Vector database showroom. Part 6 Milvus — The High-Speed Freight Train

Silver_dev — Fri, 09 Oct 2026 18:58:22 +0000

🚄 Milvus — The High-Speed Freight Train

Billions of vectors aboard, uncontested on the mainline. But nobody rides before the rails are built.

Under the hood: a Go + C++ core, Apache 2.0, a graduated project of the Linux Foundation's LF AI & Data, driven by Zilliz (who also sell the managed ride, Zilliz Cloud). The distributed deployment is a real architecture: proxy, coordinator services, and worker nodes (query, data, index) — all hanging off a central log (Pulsar or Kafka), with etcd for metadata and MinIO/S3 for object storage. Your vectors live in object storage; storage and compute are separated. One train, three gauges: Milvus Lite (embedded, pip install, desk scale), Milvus Standalone (a rail bus — three containers: Milvus itself, etcd for metadata, MinIO for object storage), and Milvus Distributed (the mainline — Helm on Kubernetes).

Where it shines:

Billions of vectors is the home stadium: capacity scales with your object storage, not your RAM budget; horizontal scale means adding worker nodes. This is the tool that made "vector database" a category
GPU acceleration (since v2.4): GPU_CAGRA built on NVIDIA's RAPIDS — for when search is the bottleneck and you have the silicon
DiskANN (since v2.4): the index lives on SSD — vectors beyond RAM, latency traded for capacity
Sparse vectors since v2.4, and since v2.5 a built-in BM25 full-text search — the factory-grade hybrid, no separate sparse embedder required
Multi-tenancy with documented patterns (partition keys, separate databases), RBAC, TLS — and Attu, a proper admin GUI. The only vehicle in the showroom that ships with a cockpit display
One of the largest OSS communities in the category; SDKs for Python/Java/Go/Node; LangChain/LlamaIndex integrations; Zilliz Cloud if you'd rather rent the railway

Where it stalls:

The rails: Distributed means etcd + Pulsar/Kafka + MinIO/S3 + the Milvus pods themselves. Helm charts help, but the ops muscle is non-negotiable. (Lite and Standalone genuinely shrink this — see the manual below)
Bring your own embeddings — a database, not an embedder (same rule as the hatchback and the crossover)
No ACID transactions "like in Postgres": batches are not transactions — the station wagon still owns that lane
Tuning is part of the contract: M, efConstruction, nprobe/ef per index type — and a consistency level per query
Backups run through the dedicated milvus-backup tool: plan it and rehearse it. There's no "it's just my Postgres cluster" simplicity here

What breaks if you skip the manual:

Bought the mainline for the street corner. A composite story from community chats, details changed: a team runs semantic search over 300k documents on distributed Milvus — a small zoo of pods, of which exactly two kinds accept queries — because a big-tech talk mentioned billions. A junior asks: "Why not Postgres? We already have Postgres." Calculator: 300,000 × 1536 dims × 4 bytes ≈ 1.8 GB. The right gauge existed all along: Milvus Lite for the prototype, Standalone for small production, Distributed for the billions. Milvus isn't the mistake — the scale mismatch is
Benchmark trap #2 (the hatchback's cousin): fresh inserts land in growing segments that are searched by brute force until they're sealed and indexed. A naive benchmark right after loading — or on a tiny collection — measures exact search, not your index. Honest numbers: production-like volume, settled segments, warm queries
Consistency levels are per-query (default: bounded): strong / bounded / session / eventually. With weaker levels, "insert → immediately search" tests flake exactly like the taxi's eventual consistency. Pick session or strong for the paths that need it
Metric and dimension are locked at collection creation — same rule as the hatchback and the taxi. The escape hatch here is actually elegant: build the new collection and flip a collection alias — the zero-downtime re-index is a documented pattern
The partition key (if you use partition-key tenancy) is fixed at creation too — retrofitting tenancy later means re-shipping the data

Cost of ownership: the train is free (Apache 2.0); the railroad isn't — count the ops salary, not just the license. Zilliz Cloud (managed, serverless tier included) rents you the whole railway. Self-hosted Lite and Standalone genuinely fit a laptop and a small server respectively.

Mechanics & parts: Zilliz drives development; LF AI & Data provides neutral governance; the community is one of the largest in the category. "Milvus engineers" are rarer than Postgres ones — but this is a Kubernetes-native system your DevOps team can actually operate, with vendor support available when the stakes are high.

✅ Take it if: you're at hundreds of millions to billions of vectors, need GPU or beyond-RAM capacity, run many tenants, have (or hire) real ops muscle — or use Zilliz Cloud and skip the rails

❌ Pass if: you're under ~10M vectors on a single box (the hatchback or the wagon covers it), "we plan to grow" is your only argument, or nobody on the team wants to own a Helm chart

Test drive:

# Milvus Lite runs embedded — no containers needed (Linux/macOS)
# Production gauges: Standalone (3-container compose) or Distributed (Helm on K8s)
from pymilvus import MilvusClient, DataType

client = MilvusClient("./milvus_demo.db")  # the desk model of the train

# explicit schema: scalar fields never appear by themselves (Milvus is schema-first,
# no AutoSchema like Weaviate). auto_id=False keeps our own ids — same as Parts 3–5
schema = client.create_schema(auto_id=False, enable_dynamic_field=False)
schema.add_field("id", DataType.INT64, is_primary=True)
schema.add_field("vector", DataType.FLOAT_VECTOR, dim=1536)
schema.add_field("content", DataType.VARCHAR, max_length=512)
schema.add_field("year", DataType.INT64)

index_params = client.prepare_index_params()
index_params.add_index(field_name="vector", index_type="AUTOINDEX", metric_type="COSINE")

client.create_collection(
    collection_name="docs",
    schema=schema,
    index_params=index_params,
)

client.insert(
    collection_name="docs",
    data=[
        {"id": 1, "vector": embed("Quarterly report 2024"), "content": "Quarterly report 2024", "year": 2024},
        {"id": 2, "vector": embed("Legal contract draft"), "content": "Legal contract draft", "year": 2024},
    ],
)
# note: fresh data sits in "growing segments" searched by brute force until they are
# sealed and indexed (benchmark trap #2). flush() seals segments — but in production
# let auto-sealing do its job; frequent manual flushes are an anti-pattern

# embed() — your embedding function (the same one from Parts 3–5 — honest comparison)
res = client.search(
    collection_name="docs",
    data=[embed("annual financial summary")],
    filter="year == 2024",
    limit=10,
    output_fields=["content", "year"],
)

for hits in res:
    for hit in hits:
        print(hit["id"], round(hit["distance"], 3), hit["entity"].get("year"))

The train is magnificent — on the mainline, where it was built to run. Ask it at 300k vectors — Postgres wins. Ask it at 3 billion — the train wins. Buy for the scale you have; re-check at the scale you reach.

🚦 Final part of the showroom: all six vehicles side by side — the cost-of-ownership table, the decision tree, and a one-day test-drive checklist for the car you pick.

Vector database showroom. Part 5 Pinecone — The Car by Subscription

Silver_dev — Fri, 09 Oct 2026 17:36:20 +0000

🚕 Pinecone — The Car by Subscription

— I want a vector database. I don't want: HNSW tuning, container patching, changelog reading, or ever thinking about RAM.
— Have I got a car for you. You won't have to drive.
— What's the catch?
— No catch. It's a subscription: the meter ticks on every ride, and you can never buy the car. Now — the fine print.

For those who'd rather not drive at all. The fine print: the meter runs on every mile.

Under the hood: the only fully managed player in this showroom. Closed source, no self-hosting — not a limitation, a product decision. New users get the serverless architecture: storage and compute are decoupled and scale on their own. There's nothing to tune — and that's the advertised feature.

Where it shines:

Genuinely zero ops: no upgrades, no manual backups, no memory planning. pip install pinecone → API key → index → production. Of all the cars here, this one starts faster than the scooter
Integrated embedding (optional): ship raw text and Pinecone embeds it via hosted models — a feature the scooter from Part 2 envies. Heads-up: an integrated index is a separate index type and doesn't accept your own vectors — one approach per index. The test drive below uses the classic "bring your own vectors" — backend devs prefer it for apples-to-apples comparison (our promise since Part 3)
Multi-tenancy via namespaces: tenants isolated inside a single index
Best-in-class DX: docs, console, SDKs (Python/JS/Go/Java), LangChain/LlamaIndex integrations — Pinecone is the default of half the RAG tutorials on the internet
Enterprise compliance badges: cloud and region of your choice (AWS/GCP/Azure). Though your data still lives in their cloud — see fine print

Where it stalls:

A closed black box, no workarounds: reading the code, patching it, or moving to your own servers — not possible. If your compliance regime says "data never leaves our perimeter" — walk away, and check this before designing the system
Zero knobs: no hnsw_ef, no quantization — the server decides everything. Unhappy with recall? Your freedom is top_k. That's it
No joins, no SQL — expected; the station wagon is still around
Costs grow non-linearly: high-QPS at large top_k is the plot of those "our Pinecone invoice" posts

What breaks if you skip the manual:

The meter counts what you read: every query burns read units. top_k=100, include_values=true (returning the raw vectors!), and a nightly test run in CI — three shock absorbers burning your budget. Only set include_metadata when you actually need the metadata
Eventual consistency: right after an upsert, a query may not see the fresh vectors. The test "write → immediately read" fails flakily. A pause or retry is the standard pattern
Queries live inside a namespace: you uploaded to "2024" but queried without a namespace — empty result. Not a bug: the default namespace is literally the empty string "" — a separate apartment from "2024"
Metadata types are strict: "2024" (string) and 2024 (number) are different values — a numeric filter won't match strings. Pick the type once, for the whole team
The metric (cosine/dotproduct/euclidean) and dimension are locked at index creation — same rule as the hatchback, except there's no "rebuild the collection on our own servers" escape hatch: new index + re-upload

Cost of ownership: a subscription. Free tier for prototypes; then storage + read/write units. This is the only car in the showroom you cannot buy: there is no self-hosted edition and never will be. You can export your data (fetch, bulk export) — but that's moving your stuff out of a rented apartment, not selling the car.

Mechanics & parts: Pinecone (New York) behind it; the founder came out of Amazon's AI lab. You can't hire a "Pinecone mechanic" — you can't look under the hood. The upside: nothing for you to fix — if it breaks, the dealer repairs it. There's no grease-monkey community by design: all the wrenches belong to the vendor.

✅ Take it if: you have no ops team (and won't), prototype-to-production in one day, spiky traffic, no "data stays in our perimeter" requirement, and a variable bill doesn't scare you

❌ Pass if: your data can't leave your perimeter; you want to steer recall and cost with your own hands; or you're pushing billions of vectors at sustained high QPS — do the TCO math against the train

Test drive:

# modern SDK — pip install -U pinecone
# (the legacy `pinecone-client` package name is deprecated)
from pinecone import Pinecone, ServerlessSpec

pc = Pinecone(api_key="YOUR_API_KEY")

# metric and dimension are locked at creation — same rule as the hatchback
if "docs" not in pc.list_indexes().names():
    pc.create_index(
        name="docs",
        dimension=1536,
        metric="cosine",
        spec=ServerlessSpec(cloud="aws", region="us-east-1"),  # required in the modern SDK
    )

index = pc.Index("docs")

# embed() — your embedding function (the same one from Parts 3–4 — honest comparison)
index.upsert(
    vectors=[
        {"id": "1", "values": embed("Quarterly report 2024"), "metadata": {"year": 2024}},
        {"id": "2", "values": embed("Legal contract draft"), "metadata": {"year": 2024}},
    ],
    namespace="2024",
)
# heads-up: right after upsert, a query may not see these vectors yet (eventual consistency)

# the meter ticks here: top_k and include_metadata cost read units
# include_values=True is the budget-killer from "what breaks" above — only if you truly need raw vectors
res = index.query(
    namespace="2024",
    vector=embed("annual financial summary"),
    filter={"year": {"$eq": 2024}},
    top_k=10,
    include_metadata=True,
)

for match in res["matches"]:
    print(match["id"], round(match["score"], 3), match["metadata"].get("year"))

The whole ride without a single thought about servers. The subscription keeps its promise. The only question: how far will you drive — and what the meter reads at the end of the month.

Vector database showroom. Part 4 Weaviate — The Crossover That Ships Fully Loaded

Silver_dev — Fri, 09 Oct 2026 15:54:32 +0000

🚐 Weaviate — The Crossover That Ships Fully Loaded

Every option already installed: vectorization, hybrid search, multi-tenancy. One question — who services all those options?

Under the hood: a Go core under BSD-3-Clause, one container to start. Three protocols: REST, GraphQL, and gRPC, with the v4 client using gRPC as its fast lane. The philosophy: "bring your data, the factory does the rest" — vectorizer modules, hybrid search, and generation are toggled by config, not external code.

Where it shines:

Factory vectorization: attach a module (local transformers, OpenAI, Cohere, multimodal CLIP) and the database embeds on insert. Contrast with the scooter: there the embedder is hardwired; here it's a factory option you choose
Hybrid, factory-grade: BM25F (the lexical index is already inside) + vectors in a single query, with the alpha knob balancing semantics vs keywords. No separate sparse embedder needed — unlike the hatchback
Native multi-tenancy — the signature feature: tenant = its own shard, isolated search and performance, active/inactive tenants with cold storage. For a SaaS, this is what other databases make you assemble from payload filters
Generative search: RAG inside the database — a generative module builds the answer right next to the retrieved objects
Cross-references between objects: a mini-graph inside your vector DB (Neo4j ambitions excluded)
Above-average operations: built-in backups to S3/GCS/Azure/disk, Prometheus metrics, OIDC auth. The hatchback with its manual snapshots is jealous

Where it stalls:

Factory options need a service bay: self-hosted vectorization modules are separate containers — each eats RAM and needs babysitting. API modules put an external-provider dependency inside your database
No transactions "like in Postgres": batches are not ACID operations
Schema changes: some apply on the fly, but switching the vectorizer or a property type = re-import. Design the schema before loading
Distributed mode exists, but the tuning is plentiful: ef, efConstruction, quantization (scalar/product/binary) trading recall

What breaks if you skip the manual:

AutoSchema: by default the schema is inferred from the first objects — "the factory assembles the trim based on your first order." Wrong types in the first batch and you live with them or re-import. In production, define the schema explicitly
Changing the vectorizer module — or a model deprecation — means a full re-embedding. That's an operation, not a flag
Multi-tenancy is enabled at collection creation. Once on, queries must pass a tenant: an inactive one returns an activation error — not a search across everything. A feature, but a first-time surprise
Python clients v3 and v4 are incompatible: half the tutorials online use v3 syntax that won't run on v4 (even the terms changed: classes → collections). Install v4 (pip install -U weaviate-client) and keep the migration guide handy
Hybrid alpha: 0 = pure vector, 1 = pure BM25 (keyword). Don't copy the default from tutorials — run evals on your own queries

Cost of ownership: free under BSD-3-Clause. Weaviate Cloud (serverless/enterprise) — managed, if you'd rather outsource the service bay. Embedded mode for local tests and CI.

Mechanics & parts: Weaviate B.V. (Amsterdam) behind it; excellent docs, an active community. "Weaviate engineers" are as rare on the market as "Qdrant engineers" — but a backend developer can drive this one.

✅ Take it if: a SaaS with many tenants, you want a BM25+vector hybrid without rolling your own sparse embedder, or you want vectorization and generation bundled in one database

❌ Pass if: your logic lives in SQL (the station wagon), you're counting billions with GPUs (the train), or your ops budget is minimal — a fully-loaded crossover needs a service bay

Test drive:

# weaviate-client v4: pip install -U weaviate-client
# embedded mode downloads binaries once; in production — Docker or Weaviate Cloud
import weaviate
from weaviate.classes.config import Configure, Property, DataType
from weaviate.classes.query import Filter

client = weaviate.connect_to_embedded()

docs = client.collections.create(
    "Document",
    vectorizer_config=Configure.Vectorizer.none(),  # we bring vectors ourselves (hatchback-style)
    properties=[
        Property(name="title", data_type=DataType.TEXT),
        Property(name="year", data_type=DataType.INT),
    ],
)

docs.data.insert(
    properties={"title": "Quarterly report 2024", "year": 2024},
    vector=embed("Quarterly report 2024"),  # embed() — your embedding function
)

# hybrid: BM25F + vectors in one query
# alpha = balance: 0 — vector, 1 — BM25; tune on evals
res = docs.query.hybrid(
    query="annual financial summary",
    vector=embed("annual financial summary"),
    alpha=0.5,
    filters=Filter.by_property("year").equal(2024),
    limit=10,
)

for obj in res.objects:
    print(obj.uuid, obj.metadata.score, obj.properties["title"])

A crossover wins neither with the hatchback's speed nor the scooter's simplicity — it wins on equipment: a whole RAG factory inside one database. You don't pay for the steering wheel; you pay for the service bay that keeps the options running.

DEV Community: Silver_dev

Hibernate Under the Hood. Part 7: Performance and Common Pitfalls

How to Find Problems Before Production

1. SQL and Hibernate Statistics Logging

2. Slow Query Logging

Problem #1: N+1 (and How to Fix It)

Strategy 1: JOIN FETCH (or @EntityGraph)

Strategy 2: Batch Fetching (@BatchSize / default_batch_fetch_size)

Strategy 3: DTO Projections

Problem #2: The Open Session in View (OSIV) Anti-Pattern

Problem #3: Slow Batching (Bulk Inserts/Updates)

Summary

Hibernate Under the Hood. Part 6: Transaction Management and Locking

Transaction Management in Spring and Hibernate

Locking: Conflict Resolution Strategies

Typical Mistakes and Pitfalls

What to Use and When

Summary

Hibernate Under the Hood. Part 5: Caching

First-Level Cache

Second-Level Cache

Query Cache

Pitfalls and Common Mistakes

Summary

Hibernate Under the Hood. Part 4: Querying

HQL and JPQL: Object-Oriented SQL

Criteria API: Queries as Code

Native SQL: When ORM is Powerless

Spring Data JPA: How It Looks

What to Use When

What to Remember

Hibernate Under the Hood. Part 3: Entity Mapping

Basic Annotations: Where an Entity Begins

Relationship Types: From One-to-One to Many-to-Many

Cascades (CascadeType) and orphanRemoval

Fetch Strategies (FetchType): LAZY vs EAGER

Best Practices and Common Pitfalls

Hibernate Under the Hood. Part 2: Entity Lifecycle and the Persistence Context

What is the Persistence Context

The Four Entity States

1. Transient (New / Unmanaged)

2. Persistent (Managed)

3. Detached

4. Removed

persist() vs save()

merge() vs update()

get() vs load()

Other Key Methods

Dirty Checking — How Hibernate Detects Changes

Write-behind — Why save Doesn't Write Immediately

Typical Mistakes and Pitfalls

Example: All States in Action

Summary

Hibernate Under the Hood. Part 1: Hibernate Architecture and Key Components: SessionFactory and Session

Overall Architecture (Top to Bottom)

SessionFactory

Session

What the Session does

Persistence Context — The Heart of the Session

How They Interact

Summary

Spring AI: First Steps

Preparation

1. AI Hello World

2. Structured Output (JSON → Java Record)

3. Function Calling (LLM calls Java code)

4. Prompt Templates (Dynamic Prompts)

5. Streaming (Real-time Response Streaming)

The finale of the Vector Database Showroom series.

The cost-of-ownership table

The one-day test drive

Before you start

(2–3 hours)

(2 hours) — the scorecard

The method doesn't expire

Vector database showroom. Part 6 Milvus — The High-Speed Freight Train

🚄 Milvus — The High-Speed Freight Train

Where it shines:

Where it stalls:

What breaks if you skip the manual:

Strategy 1: `JOIN FETCH` (or `@EntityGraph`)

Strategy 2: Batch Fetching (`@BatchSize` / `default_batch_fetch_size`)

Problem #2: The `Open Session in View` (OSIV) Anti-Pattern

Cascades (`CascadeType`) and `orphanRemoval`

Fetch Strategies (`FetchType`): `LAZY` vs `EAGER`

`persist()` vs `save()`

`merge()` vs `update()`

`get()` vs `load()`

Write-behind — Why `save` Doesn't Write Immediately