Infinispan

Fast, Non-Blocking Conflict Resolution with Merkle Trees

2026-10-20T10:00:00+00:00

Network partitions are an unfortunate reality when operating a distributed data grid—right up there with TCP retransmits and the discovery that your "five nines" availability calculation didn’t account for leap seconds. When a network split occurs, different partitions may continue servicing writes, causing them to diverge. Once the network heals and the partitions merge, Infinispan’s partition handling and conflict resolution mechanisms reconcile divergent states to restore consistency.

Historically, determining which entries conflicted between replicas during a partition merge could be an expensive operation. Even if only a handful of keys were modified while partitioned, traditional conflict detection often required write owners to scan and transmit all entries within affected segments across the cluster. For large caches with millions of entries, this created heavy network traffic, CPU spikes, and latency spikes at the exact moment the cluster was attempting to recover.

Infinispan 16.3 introduces a new hierarchical Merkle tree-inspired hash comparison mechanism that dramatically reduces network traffic during conflict resolution. The implementation combines this hierarchical tree structure with an in-flight running XOR hash computed at entry update time, and re-architects the conflict resolution process to be completely non-blocking.

This post explores how the hierarchical Merkle tree conflict resolution works, why computing hashes incrementally at write time is essential for scalability, analyzes the Big-O time and network complexities, and presents JMH benchmark results demonstrating the performance benefits.

The Problem: Partition Recovery and The Cost of Full Segment Comparison

Infinispan splits the cache keyspace into a fixed number of consistent hash segments (typically 256). Each segment is owned by one or more nodes depending on the configured numOwners.

When a cluster partitions, nodes in separate partitions may update keys in the same segments. When the partitions merge, the ConflictManager must inspect the replicas on write owners, detect conflicting entry versions, and apply a conflict resolution merge policy (such as PREFERRED_ALWAYS, REMOVE_ALL, or a custom EntryMergePolicy).

Previously, discovering whether replicas diverged required pulling all entries for each segment from the replica nodes:

Node A requests all entries for segment $S$ from Node B and Node C.
Node A receives every key, value, and metadata record for segment $S$.
Node A compares each entry version to detect conflicts.

Imagine a segment containing 50,000 entries where each entry’s average payload is 1 KB. Resolving a single segment requires transferring ~50 MB of data over the network. Multiply that across hundreds of segments, and a partition merge could easily saturate network bandwidth with gigabytes of redundant state transfer—even if 99.9% of the entries were completely identical! It’s like photocopying an entire phonebook to verify that only one person changed their number.

Hierarchical Merkle Tree Hash Comparison

To avoid sending unchanged data across the wire, PR #16890 implements a three-level hierarchical hash comparison inspired by Merkle trees:

Level 1: Segment Level Check

First, write owners compare a single 64-bit aggregate hash for the entire segment. If all replicas produce identical segment hashes, we know with high probability that all entries and metadata versions in that segment are identical. The entire segment is skipped immediately: 0 entries transferred over the network.

In real-world network partitions, many segments are never touched during the split. The segment-level check allows them to be reconciled with a single roundtrip exchanging a few bytes of hash data.

Level 2: Bucket Level Check

If the segment hashes differ, we know at least one entry has diverged. Instead of jumping directly to fetching all entries, the segment is subdivided into 32 deterministic buckets based on the entry hash:

int bucketIndex = (entryHash >>> 27) & 0x1F; // 32 buckets [0..31]

The nodes exchange bucket hashes using GetBucketHashesCommand. By comparing the 32 bucket hashes, the coordinator pinpoints exactly which sub-ranges of the segment diverge.

Level 3: Selective Entry Fetch

For each bucket where the hash matches, no entries are fetched. For buckets where hashes mismatch, the coordinator sends GetBucketEntriesCommand to fetch only the entries residing in those specific buckets. Replicas then compare only those entries and resolve the conflicts.

Boundary Optimizations and Fail-safes

Small Segment Threshold: For segments with $\le 64$ entries, dividing into 32 buckets adds extra RPC overhead for minimal data savings. If a segment is small, the system skips bucket hashing and directly fetches the segment entries.
All-Buckets Fast Path: If all 32 buckets differ, attempting selective bucket fetching only adds command overhead. The fast path detects this and immediately transitions to streaming the full segment.
Fail-Safe Fallback: If any node experiences a deserialization error, RPC timeout, or unsupported version during hash negotiation, the manager transparently falls back to the legacy full segment reconciliation without failing the merge.

In-Flight Hash Computation: Running XOR Hashes

While the hierarchical Merkle tree approach is theoretically sound, a critical question remains: where do the segment and bucket hashes originate?

A naive approach would iterate the cache data container on-demand when a conflict occurs, hashing every entry in the segment and bucket. However, this creates a major bottleneck: scanning hundreds of thousands of entries across hundreds of segments at partition merge time causes significant CPU spikes, thread contention, and memory allocations. Right when the cluster is already recovering, we would be thrashing the CPU with full data scans!

To eliminate this cost, we added an in-flight running XOR hash tracking mechanism that is only enabled when conflict resolution is configured.

The Power of XOR Associativity

XOR ($\oplus$) has three fundamental mathematical properties that make it ideal for running distributed set hashes. If you’ve ever wondered what XOR is good for besides confusing CS101 students, here’s your answer:

Commutativity: $A \oplus B = B \oplus A$ (order of entry insertion does not matter).
Associativity: $(A \oplus B) \oplus C = A \oplus (B \oplus C)$.
Self-Inversion (Identity): $A \oplus A = 0$ and $A \oplus 0 = A$.

Because XOR is self-inverting and commutative, we do not need to rescan the container when data changes. We can maintain a running hash incrementally:

Entry Added: segmentHash ^= hash(key, value, version)
Entry Updated (old value replaced by new value): segmentHash ^= hash(key, oldValue, oldVersion) ^ hash(key, newValue, newVersion)
Entry Removed / Evicted: segmentHash ^= hash(key, oldValue, oldVersion)

The same XOR operation is simultaneously applied to the corresponding bucket hash array (bucketHashes[bucketIndex] ^= entryHash).

Interceptor Architecture

We integrated this into Infinispan’s interceptor chain via SegmentHashInterceptor and SegmentHashTracker:

public class SegmentHashTracker {
   private final AtomicLongArray segmentHashes;
   private final AtomicLongArray bucketHashes; // 32 buckets per segment

   public void updateEntry(int segment, long oldEntryHash, long newEntryHash) {
      long delta = oldEntryHash ^ newEntryHash;
      segmentHashes.accumulateAndGet(segment, delta, (current, d) -> current ^ d);

      int bucketIndex = getBucketIndex(newEntryHash);
      int bucketOffset = (segment << 5) + bucketIndex;
      bucketHashes.accumulateAndGet(bucketOffset, delta, (current, d) -> current ^ d);
   }
}

Because hash updates run inside SegmentHashInterceptor during normal put, remove, and eviction operations, maintaining the hash costs only a few CPU clock cycles ($O(1)$) per write.

When conflict resolution runs: * Segment hash retrieval is $O(1)$ (an atomic read). * Bucket hash retrieval is $O(1)$ (reading 32 longs). * Zero data container iteration is required during recovery, when no conflicts are present!

Making Conflict Resolution Fully Non-Blocking

Infinispan has invested heavily in a non-blocking architecture, offloading I/O to Netty and keeping worker threads unblocked. Conflict resolution cannot be an exception.

The updated DefaultConflictManager utilizes asynchronous composition (CompletionStage) from start to finish:

Segment hash requests are dispatched asynchronously across all write owners using non-blocking transport commands.
If hashes match, the segment resolution stage completes immediately without switching threads.
If hashes mismatch, GetBucketHashesCommand is dispatched asynchronously.
Bucket comparisons run concurrently, and only mismatched buckets trigger asynchronous GetBucketEntriesCommand fetches.
Entry conflict resolution policies run reactively as chunks arrive, completing a CompletableFuture when all segments are verified.

At no point does the conflict resolution flow block the calling thread or Netty event loops.

Big-O Complexity Analysis

Let: * $S$: Total number of segments in the cache. * $N$: Average number of entries per segment ($Total = S \times N$). * $B$: Number of buckets per segment ($B = 32$). * $C$: Number of entries modified or conflicting in a segment during the partition ($0 \le C \le N$). * $E$: Average byte size of an entry (key + value + metadata). * $H$: Byte size of a hash ($8$ bytes for a 64-bit long).

Time Complexity at Conflict Resolution Time

Table 1. Time Complexity Comparison (per segment)
Operation	Legacy Full Scan	On-The-Fly Merkle Scan	In-Flight XOR Merkle
Hash Computation at Recovery	N/A	$O(N)$	$O(1)$
Segment Comparison	$O(N)$	$O(1)$	$O(1)$
Bucket Comparison (if divergent)	N/A	$O(B)$	$O(B) = O(1)$
Write / Update Overhead	$O(1)$	$O(1)$	$O(1)$ (bitwise XOR)

Network Data Transfer Complexity

Table 2. Network Traffic Transferred (per segment)
Scenario	Legacy Conflict Resolution	Hierarchical Merkle Tree	Traffic Reduction
No divergence ($C = 0$)	$N \times E$ bytes	$1 \times H$ bytes (8 bytes)	$\approx 100\%$ reduction
Sparse divergence ($C \ll N$)	$N \times E$ bytes	$B \times H + \min(C, B) \times \frac{N}{B} \times E$	$\approx 90\% - 99\%$ reduction
Full divergence ($C \approx N$)	$N \times E$ bytes	$B \times H + N \times E$ (fast path)	Overhead bounded by $32 \times 8 = 256$ bytes

When $C = 0$ (no writes in that segment during partition), network payload drops from tens of megabytes to 8 bytes. When only a few keys differ ($C \ll N$), instead of streaming the entire segment, only the mismatched buckets are transferred, cutting network bandwidth consumption by over 90%.

JMH Benchmark Reproducer: Testing Actual Conflict Resolution in a 6-Node Cluster

To benchmark actual conflict resolution performance in a realistic distributed environment rather than just raw hashing primitives, this JMH benchmark boots a real 6-node Infinispan cluster (DIST_SYNC, numOwners = 2), populates 100,000 cache entries across 256 segments, induces real version conflicts across the cluster nodes, and measures ConflictManager.resolveConflicts().

Inducing Real Conflicts in a 6-Node Topology

Infinispan provides Flag.CACHE_MODE_LOCAL, which bypasses network replication and applies an update only to the local node’s data container. By writing entries normally across the 6-node grid and then overwriting a subset of those keys locally on specific backup nodes (nodes 1 through 5) using Flag.CACHE_MODE_LOCAL, we create genuine replica divergence: * The primary and backup owners hold differing values and version metadata. * Divergence is distributed across different physical nodes in the cluster. * The ConflictManager must detect the divergence across remote nodes and apply the merge policy to reconcile the entire grid.

The benchmark compares: 1. Merkle Tree Conflict Resolution (hashBuckets = 32): The new hierarchical approach using in-flight XOR segment and bucket hashes across all 6 nodes. 2. Legacy Conflict Resolution (hashBuckets = 0): The baseline implementation where all segment owners stream full segment contents over JGroups transport.

Here is the complete benchmark source code:

package org.infinispan.benchmark.conflict;

import org.infinispan.Cache;
import org.infinispan.configuration.cache.CacheMode;
import org.infinispan.configuration.cache.ConfigurationBuilder;
import org.infinispan.configuration.global.GlobalConfigurationBuilder;
import org.infinispan.conflict.ConflictManager;
import org.infinispan.conflict.ConflictManagerFactory;
import org.infinispan.conflict.MergePolicy;
import org.infinispan.context.Flag;
import org.infinispan.manager.DefaultCacheManager;
import org.infinispan.manager.EmbeddedCacheManager;
import org.infinispan.partitionhandling.PartitionHandling;
import org.openjdk.jmh.annotations.*;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.TimeUnit;

@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
@Warmup(iterations = 3, time = 2, timeUnit = TimeUnit.SECONDS)
@Measurement(iterations = 5, time = 2, timeUnit = TimeUnit.SECONDS)
@Fork(1)
@State(Scope.Benchmark)
public class ActualConflictResolutionBenchmark {

   private static final int CLUSTER_SIZE = 6;

   @Param({"50000", "100000"})
   private int totalEntries;

   @Param({"0", "10", "100", "1000", "5000", "25000", "50000", "100000"})
   private int conflictedEntries;

   @Param({"32", "0"}) // 32 = Merkle Tree Buckets, 0 = Legacy Full Segment Fetch
   private int hashBuckets;

   private final List managers = new ArrayList<>(CLUSTER_SIZE);
   private final List> caches = new ArrayList<>(CLUSTER_SIZE);
   private ConflictManager conflictManager;

   private byte[] standardPayload;
   private byte[] conflictedPayload;

   @Setup(Level.Trial)
   public void setupCluster() {
      ConfigurationBuilder cfg = new ConfigurationBuilder();
      cfg.clustering().cacheMode(CacheMode.DIST_SYNC)
         .clustering().hash().numOwners(2).numSegments(256)
         .clustering().partitionHandling()
            .whenSplit(PartitionHandling.ALLOW_READ_WRITES)
            .mergePolicy(MergePolicy.PREFERRED_ALWAYS)
            .hashBuckets(hashBuckets);

      for (int i = 0; i < CLUSTER_SIZE; i++) {
         GlobalConfigurationBuilder g = GlobalConfigurationBuilder.defaultClusteredBuilder();
         g.transport().defaultTransport()
          .clusterName("ConflictBenchCluster")
          .nodeName("node-" + i);

         EmbeddedCacheManager mgr = new DefaultCacheManager(g.build(), cfg.build());
         managers.add(mgr);
         caches.add(mgr.getCache("conflictBenchCache"));
      }

      // Obtain ConflictManager from coordinator node (node-0)
      conflictManager = ConflictManagerFactory.get(caches.get(0));

      standardPayload = new byte[1024]; // 1 KB entry payload
      conflictedPayload = new byte[1024];
      conflictedPayload[0] = 0x7F; // Diverged version
   }

   @TearDown(Level.Trial)
   public void tearDownCluster() {
      for (EmbeddedCacheManager mgr : managers) {
         if (mgr != null) {
            mgr.stop();
         }
      }
   }

   @Setup(Level.Invocation)
   public void populateAndInduceConflicts() {
      // 1. Populate synchronized entries across the 6-node cluster
      Cache coordCache = caches.get(0);
      for (int i = 0; i < totalEntries; i++) {
         coordCache.put("key-" + i, standardPayload);
      }

      // 2. Induce actual conflicts distributed across nodes 1 through 5 locally
      for (int i = 0; i < conflictedEntries; i++) {
         int targetNode = 1 + (i % (CLUSTER_SIZE - 1));
         caches.get(targetNode).getAdvancedCache()
               .withFlags(Flag.CACHE_MODE_LOCAL)
               .put("key-" + i, conflictedPayload);
      }
   }

   @Benchmark
   public void testActualConflictResolution() {
      // Executes real end-to-end conflict resolution across all 6 nodes
      conflictManager.resolveConflicts().toCompletableFuture().join();
   }
}

Benchmark Results

The benchmarks were run on a developer workstation with the following specifications:

Hardware: AMD Ryzen 7 9800X3D (16 cores, 32 threads @ 4.7 GHz base / 5.2 GHz boost)
Memory: 64 GB DDR5-6000 MHz CL30
OS: Linux 7.2.9 x86_64
JVM: OpenJDK 64-Bit Server VM, version 25.0.4

End-to-End Conflict Resolution Latency (6-Node Cluster, 100,000 Entries)

The dataset contains 100,000 entries with 1 KB payloads (totaling 100 MB of unique data, and 200 MB of total replicated state across the 6 nodes with numOwners = 2 and 256 segments).

Table 3. Actual Conflict Resolution Latency (6 Nodes, `totalEntries = 100,000`)
Divergent Keys	Legacy Full Fetch (`hashBuckets = 0`)	Merkle Tree (`hashBuckets = 32`)	Speedup	Total Cluster Wire Traffic
0 conflicts (0.0%)	821.40 ms	8.42 ms	~97.5x faster	~4 KB total (vs ~200 MB)
10 conflicts (0.01%)	834.80 ms	32.65 ms	~25.6x faster	~3.1 MB (vs ~200 MB)
100 conflicts (0.1%)	851.15 ms	78.20 ms	~10.9x faster	~12.5 MB (vs ~200 MB)
1,000 conflicts (1.0%)	892.60 ms	210.45 ms	~4.2x faster	~45.0 MB (vs ~200 MB)
5,000 conflicts (5.0%)	925.30 ms	485.30 ms	~1.9x faster	~115.0 MB (vs ~200 MB)
25,000 conflicts (25.0%)	980.50 ms	865.10 ms	~1.13x faster	~182.0 MB (vs ~200 MB)
50,000 conflicts (50.0%)	1045.20 ms	1060.40 ms	~0.99x (parity)	~198.5 MB (vs ~200 MB)
100,000 conflicts (100.0%)	1180.70 ms	1205.80 ms	~0.98x (fast-path)	~200.0 MB (bounded +65 KB hash RPCs)

Real-World Conflict Dynamics: Why Single-Digit Percentages Dominate

While the benchmark tests divergence from 0% to 100%, production deployments tell a different story.

In real-world environments, conflicts typically affect only a single-digit percentage of total entries (often well under 1% to 5%). There are several key reasons for this:

Transient Partitions: Modern cloud and datacenter network splits are typically brief, transient events—lasting from a few seconds to a few minutes before routing converges or automated recovery kicks in.
Working Set Locality: Even under high write volume, client applications rarely rewrite every key across the entire keyspace during a short partition window. Writes tend to cluster around active hot keys or disjoint partitions.
Read-Heavy Workloads: Most enterprise caches exhibit high read-to-write ratios, meaning only a fraction of total cache accesses perform mutations.

Of course, the exact percentage of conflicting entries depends directly upon how long the cluster was split for and the application’s write rate. If a split persists for hours while both sides of the network service aggressive, conflicting writes, divergence will naturally climb higher. However, in typical operational recovery scenarios, partitions heal quickly, leaving the vast majority of entries (95% to 99.9%+) completely untouched and identical across replicas.

This is precisely why the Merkle tree architecture is so effective: it is optimized directly for the reality of distributed systems. It slashes network bandwidth and latency where production clusters spend virtually all of their recovery cycles—in the single-digit conflict sweet spot—while ensuring zero degradation if an extended partition causes widespread divergence. In other words, it’s fast when you need it to be fast, and merely "not slower" when the world is already on fire.

Breaking Down the Results in a 6-Node Grid

Zero Conflicts Across 6 Nodes: Partitions frequently heal with vast stretches of segments that experienced zero write divergence during the split. With legacy resolution, every node has to serialize, transmit, and deserialize its owned segments across the JGroups cluster transport, taking 821 ms and transferring 200 MB of data. With Merkle trees and in-flight XOR hashing:
- The coordinator broadcasts GetSegmentHash requests to segment owners.
- All 256 segment hashes match immediately across replicas.
- The total network traffic across the entire 6-node cluster is just ~4 KB (256 segments $\times$ 2 owners $\times$ 8 bytes).
- Resolution completes in 8.42 ms—a ~98x speedup! + That’s right: we went from transferring 200 MB to transferring less data than a low-resolution meme.
Sparse to Moderate Conflicts (0.01% to 5.0%): When between 10 and 5,000 keys diverge across the 6 nodes, only the segments containing those keys report mismatched segment hashes. The coordinator queries bucket hashes solely for those affected segments. Since the 32 buckets isolate the divergence to specific sub-ranges, unaffected buckets are skipped entirely. Even at a 5% conflict rate (5,000 modified keys), cluster data transfer drops from 200 MB down to 115 MB, cutting reconciliation time from 925 ms down to 485 ms (~1.9x faster).
High Divergence and The Crossover Point (25% to 50%): At a 25% conflict rate (25,000 keys), most buckets across the 256 segments contain at least one modified key, but uncorrupted buckets are still preserved and skipped, yielding a modest ~1.13x speedup and saving ~18 MB of traffic. By 50% conflict rate (50,000 keys), practically every bucket in the cluster is "dirty" and requires entry fetching. Here we reach the break-even/crossover point: resolution time is essentially at parity with legacy full fetch (1060 ms vs 1045 ms).
100% Conflict Rate and The "All-Buckets" Fast Path: When every single entry in the cache diverges (100,000 conflicts), selective bucket fetching could theoretically introduce redundant RPC overhead if handled naively. However, the changes include an "all-buckets fast path": when all 32 buckets in a segment differ, the manager skips individual bucket commands and streams the entire segment in bulk. As a result, the worst-case penalty under total divergence is strictly bounded to the initial hash exchanges (~65 KB of network data across the cluster), resulting in less than 2% overhead compared to legacy resolution.
Multi-Node Concurrency & In-Flight XOR Hashes: Because SegmentHashInterceptor and SegmentHashTracker maintain segment and bucket hashes in memory during regular writes, none of the 6 nodes stall or consume CPU iterating their data containers when partition resolution kicks off. Combined with the non-blocking asynchronous pipeline, hash checks and selective fetches proceed concurrently across all 6 nodes without thread pool exhaustion.

Configuration

The Merkle tree conflict resolution optimization is enabled by default when partition handling is configured with merge policies in Infinispan 16.3+:

Or via the programmatic API:

ConfigurationBuilder builder = new ConfigurationBuilder();
builder.clustering().cacheMode(CacheMode.DIST_SYNC)
       .partitionHandling()
          .whenSplit(PartitionHandling.ALLOW_READ_WRITES)
          .mergePolicy(MergePolicy.PREFERRED_ALWAYS);

Summary

Effective partition handling is essential for maintaining data integrity during network splits. Issue #16887 delivers:

Hierarchical Merkle tree comparisons (Segment $\to$ 32 Buckets $\to$ Selective Fetch) cut network traffic by up to 99% during partition reconciliation.
In-flight running XOR hashing shifts hash computation from an expensive $O(N)$ recovery-time scan to an unnoticeable $O(1)$ write-time bitwise operation.
Non-blocking orchestration ensures neither Netty event loops nor cache worker threads block during partition merges.

Try it out in Infinispan 16+, and check out the code and discussion in Issue #16887!

Update by Query in Ickle: Bulk Updates Without Reading Data Back

2026-10-16T00:00:00+00:00

One of the features I am most excited about in Infinispan 16.3 is update by query in Ickle. If you have ever needed to update thousands of entries in a cache based on a condition, you know the pain: read them, modify them in your application, write them back one by one. With update by query, you can now do this in a single statement, directly on the server.

In this post I will walk you through the syntax, show real-world examples, and explain where this feature shines and where it has limitations.

The syntax

The general form of an update query in Ickle is:

UPDATE FROM 
  SET  =  [, SET  = ]*
  [, ADD  = (, ...)]
  [, REMOVE  = [, ...]]
  [WHERE ]

There are three operations:

SET - assigns a new value to a field. When the target is a collection, use a bracketed list ['a', 'b'] to replace the entire existing collection.
ADD - adds values to a collection field without replacing its contents. Use a parenthesized list ('a', 'b') to add multiple values at once.
REMOVE - removes values from a collection field without affecting other members. Use a bracketed list ['a', 'b'] to remove multiple values at once.

You can combine SET, ADD and REMOVE operations in a single statement, and you can use any Ickle WHERE clause to filter which entries are affected.

Supported value types include strings, numbers, booleans, null, and named parameters (:paramName). Keywords are case-insensitive, so UPDATE, update and Update all work.

A practical example: product catalog

Let me use an example that is closer to what you might find in a real application. Imagine you are running an e-commerce platform and you have a product catalog stored in Infinispan.

@Proto
@Indexed
public record Product(
   @Keyword(projectable = true, sortable = true)
   String sku,

   @Text
   String name,

   @Keyword(projectable = true, normalizer = "lowercase")
   String category,

   @Basic(projectable = true, sortable = true)
   Double price,

   @Basic(projectable = true)
   Boolean active,

   @Keyword(projectable = true)
   List tags,

   @Keyword(projectable = true, normalizer = "lowercase")
   String warehouse
) {
}

Scenario 1: Price adjustment for a category

Black Friday is coming and you want to apply a discount to all products in the "electronics" category. Before update by query, you would have had to read all electronics products, modify the price in Java, and put them back. Now:

UPDATE FROM catalog.Product SET price = 79.99 WHERE category = 'electronics' AND price = 99.99

This runs entirely on the server. No data is transferred to your application and back.

Scenario 2: Deactivating out-of-stock products

Your warehouse system tells you that a specific warehouse is temporarily out of stock. You want to deactivate all products from that warehouse:

UPDATE FROM catalog.Product SET active = false WHERE warehouse = 'warehouse-east'

When stock is back, just run the reverse:

UPDATE FROM catalog.Product SET active = true WHERE warehouse = 'warehouse-east'

Scenario 3: Tagging products for a promotion

You want to tag all active products under 50 euros with a "budget-friendly" tag, without removing their existing tags:

UPDATE FROM catalog.Product ADD tags = ('budget-friendly') WHERE price < 50.0 AND active = true

Notice the use of ADD instead of SET. This appends to the existing tags collection instead of replacing it. This is very useful when you have multi-value fields like tags, labels, or categories.

Scenario 4: Removing a discontinued tag

A promotion is over and you want to clean up the "summer-sale" tag from all products:

UPDATE FROM catalog.Product REMOVE tags = ['summer-sale']

No WHERE clause here - this removes the tag from every product that has it.

Scenario 5: Combining operations

You can combine multiple operations in a single query. For example, deactivating products and tagging them at the same time:

UPDATE FROM catalog.Product SET active = false, ADD tags = ('discontinued') WHERE category = 'legacy'

Using it from Java

In your Java application, update by query works just like any other Ickle query:

RemoteCache cache = cacheManager.getCache("products");

int updated = cache.query("UPDATE FROM catalog.Product SET active = false WHERE warehouse = 'warehouse-east'")
   .executeStatement();

System.out.println("Updated " + updated + " products");

The executeStatement() method returns the number of entries that were modified. There is also an async variant, executeStatementAsync(), that returns a CompletionStage.

You can also use named parameters to avoid hardcoding values in the query string:

int updated = cache.query("UPDATE FROM catalog.Product SET active = :status WHERE warehouse = :wh")
   .setParameter("status", false)
   .setParameter("wh", "warehouse-east")
   .executeStatement();

Using it from the Console

The Infinispan Web Console also supports update by query. In the cache Query tab, you will find an "Update entries" action that lets you execute an Ickle UPDATE statement directly from the browser. The console shows a confirmation dialog before executing and reports the number of affected entries.

This is very handy for operational tasks where you need to make a quick fix without writing code or deploying anything.

Use cases

Here are some real-world scenarios where update by query can save you a lot of effort:

Feature flags and toggles - enable or disable features for a subset of users or tenants
Bulk status changes - deactivate accounts, mark orders as shipped, close expired sessions
Tagging and labeling - add or remove labels, categories, or tags across many entries
Data migration - set default values for a new field across existing entries
Operational fixes - correct a wrong value across multiple entries without a full redeploy

Limitations to keep in mind

This is the first version of update by query, and there are some things to be aware of:

Values can only be constants - you cannot reference other fields or use expressions like SET price = price * 0.8. This means percentage-based discounts or computed values are not yet possible. Named parameters (:paramName) are supported though, so you can pass values from your application. Expression and function support is planned for future versions.
No projections, ORDER BY, or GROUP BY - UPDATE statements are pure data modifications. If you need to know which entries will be affected, run a SELECT first with the same WHERE clause.
No paging - you cannot use firstResult or maxResults to limit which entries are updated. The update always applies to all matching entries.
No indexed path access - you can use dot-path traversal like address.city, but array index access like tags[0] is not supported in the update path.
Not atomic across entries - each entry is updated individually using cache.compute(), so each single entry update is atomic. However, the overall operation is not transactional. If the operation is interrupted, some entries may have been updated and others not. Plan accordingly for critical operations.
No cross-cache updates - each update targets a single cache.

What is coming next

As I mentioned, future versions of Infinispan 16 will bring expression support to update queries. This will allow operations like:

-- Not yet available, coming in 16.4
UPDATE FROM catalog.Product SET price = price * 0.8 WHERE category = 'electronics'

This will make update by query even more powerful for real-world use cases.

Try it out

Update by query is available in Infinispan 16.3. You can get started with:

docker run -it -p 11222:11222 -e USER="admin" -e PASS="password" quay.io/infinispan/server:latest

For more details on Ickle query syntax, check the Query documentation. And if you want to see the full list of changes in 16.3, take a look at the Infinispan 16.3 release blog post.

If you have feedback or questions, join us on Zulip or GitHub Discussions.

Happy querying!

Infinispan AI Integrations: Spring AI and LangChain Python

2026-10-13T00:00:00+00:00

I am very happy to announce two new releases that bring Infinispan closer to the AI ecosystem: Spring AI Infinispan 1.0.0 and LangChain Infinispan 0.1.0 for Python.

These two integrations are the result of the work we have been doing to make Infinispan a first-class citizen in the AI world. Infinispan has supported vector search since version 15, and now we are making it easier than ever to use it from the most popular AI frameworks.

Spring AI Integration 1.0.0

Spring AI is the Spring ecosystem’s answer to building AI-powered applications in Java. With the release of Spring AI Infinispan 1.0.0, you can now use Infinispan as a backend for two key Spring AI capabilities:

Vector Store

Store and search document embeddings using Infinispan’s vector search capabilities. The integration supports cosine, L2 and inner-product similarity metrics, metadata filtering, and auto-creates Protobuf schemas and indexed caches on startup. If you have been using Infinispan for caching or data storage, you can now also use it as your vector database without adding another component to your architecture.

Chat Memory Repository

Persist conversation history in Infinispan, enabling stateful conversational AI applications. User, assistant, system and tool messages are all stored and retrieved, so your chatbot can remember what was said across sessions.

Getting Started

Both modules come with Spring Boot auto-configuration starters. Getting started is as simple as adding the dependency and pointing to your Infinispan server. For all the details, check out the Spring AI integration documentation.

LangChain Infinispan 0.1.0 for Python

LangChain is one of the most widely used frameworks for building AI applications, and it has a huge community in the Python world. With the release of LangChain Infinispan 0.1.0, Python developers can now use Infinispan as a vector store directly from LangChain.

This means you can store your embeddings in Infinispan, perform similarity searches, and combine them with all the tools LangChain provides for building RAG pipelines, agents, and AI-powered applications.

For documentation and usage examples, check out the LangChain Infinispan documentation.

Why Infinispan for AI?

If you are already using Infinispan for caching, session storage, or as a data grid, these integrations let you reuse the same infrastructure for your AI workloads. No need to add yet another database to your stack.

Infinispan brings several advantages as a vector store:

Unified query language - Ickle combines relational queries, full-text search, and vector kNN in a single language
Distributed by design - kNN queries work across a distributed cluster, with automatic fan-out and result merging
Multiple access protocols - the same indexed cache is accessible via Hot Rod, REST, and RESP (Redis-compatible)
Open source - fully open source under Apache 2.0, part of the Commonhaus foundation

Tutorials

If you want to get hands-on, we have tutorials available to help you get started:

Spring AI with Infinispan - get started with the Spring AI vector store and chat memory repository
Semantic Search with LangChain4j and Infinispan - for Java developers using LangChain4j
Vector Search Quickstart - a complete example with hybrid vector and metadata queries

What’s next

We will continue working on AI integrations and improving the developer experience. If you have feedback or ideas, join the conversation on Zulip or GitHub Discussions.

Happy coding!

Infinispan 16.3

2026-10-07T00:00:00+00:00

"Tripel Karmeliet"

Our 4-month brewing process has, yet again, come to completion. We are proud to present Infinispan 16.3 "Tripel Karmeliet", brewed by experts (us !) using the finest ingredients, for all you fine palates out there.

The main theme for this release is "robustness": we’ve been investigating several areas, especially in "fragile" conditions, such as scaling up/down, startup, shutdown, split-brains, huge caches and clusters with large number of caches, etc, with the following goals:

improve reliability, addressing more failure conditions encountered by our users
optimize resource usage by optimizing algorithms and increasing concurrency in certain operations
better recovery in situations where data was inevitably lost or corrupted

This task is obviously open-ended, so look for more improvements in future releases.

Conflict detection and resolution

When partitions merge, resolving conflicts traditionally requires transferring entries from every owner to compare replicas. In 16.3 this has been made dramatically more efficient with hash-based conflict detection: each segment is summarized by a compact, order-independent XOR hash that is maintained incrementally as the cache is modified, so it costs almost nothing to read at merge time.

On merge, these summaries are compared first (prefetched in one batched RPC per node). Segments whose hashes match on all owners are skipped entirely — zero entries transferred. Only for mismatching segments does the comparison drill down into fixed-size buckets derived from entry keys, and only the entries in differing buckets are fetched to find the actual conflicts. The optimization is fail-safe: any failure falls back to a full fetch without changing the resolution outcome. [#16887] [#17620]

For a detailed walkthrough of partition handling, detection and conflict resolution see the architecture documentation.

Concurrent cache start

User caches are now started concurrently without blocking the cache manager start. As soon as a cache is started it is ready to serve requests, without having to wait for other caches. [#16900]

Get optimizations

Introduce an optimized interceptor chain for get and getCacheEntry operations that skips interceptors not participating in read commands.

Benchmarks show 23-36% improvement on pure get operations across LOCAL and DIST_SYNC cache modes, with no regressions on put paths. [#17698]

Configuration enhancements

Per-node mutable configuration attributes are now persisted in the persistent state, making them survive restarts. [#17889]

Additionally, configuration attributes are now version-aware so that, during rolling upgrades, newer configurations are not sent to older nodes, which would not know how to parse them. [#18038]

Transaction table management

Avoid creating objects for already completed TXs. Create a shared instance to avoid unnecessary allocation per request. [#17801] [#17687]

Logging

Logging excessive failures under load has an amplification effect which can deteriorate performance even more. Also, log flooding makes it hard to identify the root cause of the failures. For this reason, several improvements have been made to reduce the amount of logging:

FREQUENT category and burst filter [#17801]
Reduce RemoteException noise in logs [#17669]
Reduce excessive logging for lock timeout [#17662]

Update by query

Ikcle has gained the ability to update entities with the following syntax:

Update Query in Ickle

UPDATE FROM  {SET | ADD | REMOVE}  =  [, ...]* [WHERE condition]

Use SET to assign a new value to a field. When the target is a collection, the list replaces the entire existing collection.
Use ADD to add values to a collection field without replacing its contents.
Use REMOVE to remove values from a collection field without affecting other members.

The following example sets a new title, adds two tags, and removes one tag from all books whose price is greater than 100:

UPDATE FROM org.infinispan.sample.Book SET title = 'Updated Title', ADD tags = ('sale', 'featured'), REMOVE tags = ['discount'] WHERE price > 100

Values can currently only be constants, but Infinispan 16.4 will allow the use of expressions and functions.

[#14542]

Peek

A cache.peek(K key) method has been added for embedded and emote clients. This retrieves a cache entry without updating its last acces time or recency, meaning it will be unaffected for max idle expiration or eviction purposes. Also REST can utilize this via the flags header (e.g."PEEK") that is automatically parsed on server-side and converted to Flag enum values.

This behavior can also be used via a flag:

cache.withFlags(Flag.PEEK).get(key);

[#17532]

Security enhancements

Brute-force authentication protection

Security realms which handle username/password credentials (properties, ldap) are now automatically wrapped by a brute-force authentication protection mechanism: repeated failed attempts to authenticate a user will result in temporary lockdowns. [#18001]

Post-Quantum Cryptography configuration

TLS named groups, used by Post-Quantum Cryptography (PQC) algorithms, can be fine-tuned to cater for specific restrictions. This feature requires JDK 27 or JDK 25.0.5. [#17842]

Console enhancements

Update by query

The new update-by-query capability (see above) is also available from the console: an "Update entries" action in the cache Query tab executes an Ickle UPDATE statement against all matching entries, with a confirmation modal and result reporting, alongside the existing delete-by-query. [#868]

Editor and i18n improvements

The code editor used to create and download cache configurations has been improved, and translation loading was fixed so that localized bundles resolve correctly when the console is served from a custom base path. [#707]

CLI enhancements

Zero local authentication

A new local security realm allows the CLI to authenticate against a local Infinispan instance without prompting for a username and password, provided it is running local to the server with the same system account. Authentication grants all permissions, so this realm should always be combined with another one (e.g., properties) as a fallback: if the local mechanism fails, the CLI falls back to prompting for credentials of a configured user.

Optional transcoders

The JSON POJO (Jackson) and XML (XStream) transcoders have been moved out of the server core into dedicated modules, joining JBoss Marshalling as an optional module. These are no longer included in the default server distribution: install them with the CLI install command if you need their data conversion capabilities on a running server, or add the corresponding artifact to your dependencies for embedded usage.

[#17774]

Install with dependencies

The install command now supports installing an artifact together with its declared external dependencies via the -d|--with-dependencies option. Artifacts can list their required dependencies in a META-INF/infinispan-dependencies.txt file, and those are downloaded and installed automatically (dependencies already present in server/lib are skipped). For example, this makes it easy to install modules with native or third-party requirements such as the RocksDB cachestore or the optional transcoder modules.

[#17775]

Operator enhancements

Schema CRD

A new Schema custom resource allows registering, updating and deleting Protobuf schemas on Infinispan clusters via the REST API (/rest/v2/schemas). It follows the same patterns as the existing Cache CRD, including bidirectional synchronization . This was highly requested, and we’re glad we could finally deliver it! [#2379]

Custom ServiceAccount

The Infinispan CR now accepts a custom serviceAccountName for the server (and GossipRouter, Batch, Backup and Restore) pods. The ConfigListener can also be given its own service account; when one is specified, the operator does not create RBAC resources for it, leaving that entirely in user hands. [#2404]

Pausing reconciliation

Reconciliation of any managed resource (Infinispan, Cache, Schema, Batch, Backup or Restore) can be paused by annotating it with infinispan.org/paused: true. While paused, spec changes are not applied to the underlying resources - useful for debugging or maintenance windows. Remove the annotation to resume normal operation. [PR #2585]

Other notable improvements:

the storageClassName is now immutable after creation [#2368]
The operator itself runs as a non-root user with a restricted security context (seccomp profile, no privilege escalation, all capabilities dropped), making it compatible with restrictive Pod Security Standards. [#2573]
The operator now talks to Infinispan 16 servers without using deprecated REST endpoints, eliminating the associated deprecation warnings. [#2474]

Spring AI integration

Infinispan now has a dedicated Spring AI integration, released as version 1.0.0. It provides two capabilities for building AI-powered applications with Spring Boot:

Vector Store - store and search document embeddings using Infinispan’s vector search capabilities with Ickle query language. Supports cosine, L2 and inner-product similarity metrics, metadata filtering, and auto-creates Protobuf schemas and indexed caches on startup.
Chat Memory Repository - persist conversation history (user, assistant, system and tool messages) in Infinispan, enabling stateful conversational AI applications.

Both modules come with Spring Boot auto-configuration starters, so getting started is as simple as adding the dependency and pointing to your Infinispan server.

For details, see the Spring AI integration documentation.

Architecture documentation

The Infinispan documentation now includes a detailed architecture document that describes in detail the various components and algorithms doing the dirty work behind the scenes.

Backwards compatibility

Infinispan 16.3 is fully backwards compatible with 16.x deployments and can be upgraded in-place.

The next release

16.3 is our third release using our time-boxed schedule. Adopting predictable release dates, in combination with the backwards compatibility guarantees of our rolling upgrade test harness, has allowed us to achieve great momentum: we’re delivering features, improvements and bug fixes more quickly. According to our roadmap, our next release will be 16.4, and it will happen on 2027-02-03. And you can trust it will happen exactly as the roadmap says !

Release notes

You can look at the release notes to see what was changed since our previous release.

Get them from our download page.

Infinispan Hot Rod JS Client 0.16.0: Transactions, Multimaps, and Flags

2026-06-29T00:00:00+00:00

Hot on the heels of 0.15.0, we’re happy to announce the release of the Infinispan Hot Rod JS Client 0.16.0. This release brings three new features that round out the client’s capabilities: transactions, multimap support, and operation flags.

Transactions

Sometimes you need multiple operations to succeed or fail as a unit. The JS client now supports Hot Rod transactions with a simple begin/commit/rollback API:

var tm = client.getTransactionManager();

await tm.begin();
try {
  await client.put('account-A', '900');
  await client.put('account-B', '1100');
  await tm.commit();
} catch (e) {
  await tm.rollback();
  throw e;
}

During a transaction, reads go through the local write set first — so if you put a value and then get it within the same transaction, you’ll see your own write. Under the hood, the client uses XA-style two-phase commit with version-based conflict detection, so concurrent modifications are caught at commit time.

Multimaps

Multimaps let you associate multiple values with a single key — great for tags, categories, or any one-to-many relationship:

// Add values to a key
await client.multimapPut('colors', 'red');
await client.multimapPut('colors', 'green');
await client.multimapPut('colors', 'blue');

// Get all values for a key
var values = await client.multimapGet('colors');
console.log(values); // ['red', 'green', 'blue']

// Check containment
await client.multimapContainsEntry('colors', 'red');  // true
await client.multimapContainsValue('green');           // true
await client.multimapContainsKey('colors');             // true

// Remove a specific value or the entire key
await client.multimapRemoveEntry('colors', 'red');
await client.multimapRemoveKey('colors');

// Total number of key-value pairs across all keys
var size = await client.multimapSize();

Operation flags

You can now pass Hot Rod flags to fine-tune how individual operations behave. Flags are available as constants on the infinispan module and can be combined with bitwise OR:

var infinispan = require('infinispan');

// Skip cache store loading
await client.put('key', 'value', {
  flags: infinispan.flags.SKIP_CACHE_LOAD
});

// Combine multiple flags
await client.put('key', 'value', {
  flags: infinispan.flags.SKIP_CACHE_LOAD | infinispan.flags.SKIP_INDEXING
});

// Suppress listener notifications on remove
await client.remove('key', {
  flags: infinispan.flags.SKIP_LISTENER_NOTIFICATION
});

The available flags are:

FORCE_RETURN_VALUE — return the previous value on mutations
DEFAULT_LIFESPAN — use the server-configured default lifespan
DEFAULT_MAXIDLE — use the server-configured default max idle time
SKIP_CACHE_LOAD — don’t load from the cache store
SKIP_INDEXING — don’t index the entry
SKIP_LISTENER_NOTIFICATION — don’t fire listener events

Get started

Install or update the client via npm:

npm install infinispan@0.16.0

Check out the full source code and documentation on GitHub.

Hello, Gophers! Introducing the Infinispan Go Client

2026-06-22T00:00:00+00:00

If you’ve ever thought "I wish I could talk to Infinispan from Go," today is your lucky day. We’re thrilled to announce the Infinispan Go Client — a brand-new, pure-Go client that speaks the Hot Rod 4.1 binary protocol and gives you access to all the good stuff: caching, counters, queries, transactions, listeners, and more.

No CGo. No JNI bridges. No funny business. Just go get and you’re off to the races.

Fire up a server

First things first: you need an Infinispan server to talk to. The fastest way is to grab one with Docker (or Podman — we don’t judge):

docker run --name infinispan \
  -p 11222:11222 \
  -e USER="admin" \
  -e PASS="password" \
  infinispan/server:16.2

Give it a couple of seconds to start up, and you’ve got a fully functional Infinispan node listening on port 11222. Easy.

Your first Put and Get

Let’s jump straight into code. Create a new Go module and grab the client:

mkdir hello-infinispan && cd hello-infinispan
go mod init hello-infinispan
go get infinispan.org/go-client/hotrod

Now write a tiny program:

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"infinispan.org/go-client/hotrod"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	// Connect to the server
	client, err := hotrod.NewClient(ctx, "hotrod://admin:password@localhost:11222")
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	// Grab a cache handle
	cache := client.Cache("my-cache")

	// Store something
	err = cache.Put(ctx, []byte("greeting"), []byte("Hello from Go!"))
	if err != nil {
		log.Fatal(err)
	}

	// Read it back
	val, found, err := cache.Get(ctx, []byte("greeting"))
	if err != nil {
		log.Fatal(err)
	}
	if found {
		fmt.Println(string(val)) // Hello from Go!
	}
}

Run it:

go run .

And there you have it — your Go program just stored and retrieved data from a distributed cache. That’s it. No XML. No YAML. Just a URI and you’re in.

What else can it do?

Glad you asked. This isn’t a toy client — it’s packed with features. Here’s the highlight reel:

Entries with TTL and idle timeout

Don’t want stale data hanging around? Set a lifespan or a max-idle time on your entries:

cache.Put(ctx, []byte("session"), []byte("abc123"),
	hotrod.WithLifespan(30*time.Minute),
	hotrod.WithMaxIdle(5*time.Minute),
)

Conditional operations

Optimistic locking fans, rejoice. You get compare-and-swap semantics:

// Only put if the key doesn't exist yet
ok, _ := cache.PutIfAbsent(ctx, []byte("lock"), []byte("mine"))

// Replace only if the entry hasn't been modified
meta, _, _ := cache.GetWithMetadata(ctx, []byte("counter"))
ok, _ = cache.ReplaceIfUnmodified(ctx, []byte("counter"), []byte("42"), meta.Version)

Bulk operations

Need to move a lot of data? PutAll and GetAll are hash-distribution-aware, so they route entries directly to the right nodes:

entries := map[string][]byte{
	"key1": []byte("val1"),
	"key2": []byte("val2"),
	"key3": []byte("val3"),
}
cache.PutAll(ctx, entries)

results, _ := cache.GetAll(ctx, []string{"key1", "key2", "key3"})

Event listeners

Want to react when data changes? Register a listener and get notified through a channel:

listener, _ := cache.AddListener(ctx,
	hotrod.WithListenerInterests(hotrod.EventCreated, hotrod.EventModified),
)
defer cache.RemoveListener(ctx, listener)

for event := range listener.Events {
	fmt.Printf("Event: %s on key %s\n", event.Type, event.Key)
}

Queries with Ickle

If you’re using Protocol Buffers for your values, you can query them with the Ickle query language:

result, _ := cache.Query(ctx, "FROM example.Person WHERE age > :minAge",
	hotrod.WithQueryParam("minAge", int32(21)),
	hotrod.WithQueryMaxResults(10),
)

And yes, we support continuous queries too — subscribe to a query and get notified as entries join, update, or leave the result set. Think of it as a live view of your data.

Distributed counters

Need a cluster-wide atomic counter? We’ve got strong counters (reliable, optionally bounded) and weak counters (high-throughput, eventually consistent):

counters := client.Counters()
counters.Define(ctx, "page-views", &hotrod.CounterConfiguration{
	Type:         hotrod.CounterStrong,
	InitialValue: 0,
	Storage:      hotrod.StoragePersistent,
})

counter := counters.Counter("page-views")
newVal, _ := counter.AddAndGet(ctx, 1)

Near caching

For read-heavy workloads, the near cache keeps recently accessed entries on the client side with LRU eviction and automatic server-side invalidation via Bloom filters:

nc, _ := hotrod.NewNearCache(ctx, client, "my-cache",
	hotrod.WithMaxNearCacheEntries(500),
)
// First Get goes to the server; subsequent ones are served locally
val, found, _ := nc.Get(ctx, []byte("hot-key"))

Transactions

When you need atomicity across multiple operations:

err := client.WithTransaction(ctx, "my-cache", func(tc *hotrod.TxCache) error {
	tc.Put(ctx, []byte("account-A"), []byte("900"))
	tc.Put(ctx, []byte("account-B"), []byte("1100"))
	return nil // commit; return an error to rollback
})

Type-safe caches with Protocol Buffers

Tired of juggling []byte? The typed cache gives you generics-powered, type-safe access with automatic marshalling:

cache := hotrod.NewTypedCache[string, *pb.Person](
	client, "people",
	hotrod.ProtoStreamMarshaller(),
	func() *pb.Person { return &pb.Person{} },
)

cache.Put(ctx, "john", &pb.Person{Name: "John", Age: 30})
person, found, _ := cache.Get(ctx, "john")

And there’s more

Iterators — scan through all entries in batches without blowing up your memory
Multimap caches — map a single key to multiple values
Cache administration — create, configure, and remove caches programmatically
Schema management — register and manage Protobuf schemas
Pipelined connections — multiple operations fly over a single TCP connection concurrently, so you don’t pay a round-trip per request
Smart routing — topology-aware and hash-distribution-aware client intelligence, so your requests go straight to the node that owns the data
TLS and mTLS — because security isn’t optional
SCRAM-SHA-256, PLAIN, OAUTHBEARER, and EXTERNAL auth — pick your SASL flavor

The connection URI

Connecting is as simple as a URI:

hotrod://admin:password@server1:11222,server2:11222
hotrods://admin:password@server:11222?trust_store_file_name=/path/to/ca.pem

Use hotrod:// for plain connections, hotrods:// for TLS, and list as many servers as you like — the client discovers the rest through topology updates.

Get started

go get infinispan.org/go-client/hotrod

Head over to the GitHub repository for full documentation and examples. Our tutorials are also packed with Go goodies now, so you can hit the ground running with hands-on, step-by-step guides. We’d love to hear your feedback — open an issue, send a PR, or just say hi. Happy caching, Gophers!

Hot Rod Dissector for Wireshark

2026-06-17T00:00:00+00:00

Need to debug a Hot Rod conversation? Don’t do it the hard way anymore— grab the right tool and be like Neo: able to decode the Matrix.

No need for colorful pills—just install the Hot Rod dissector plugin in Wireshark and let it do the hard work. Hot Rod conversations will appear in a clear, readable format. Now just relax, grab a coffee, and focus on debugging your application instead of spending time decoding bits!

The Hot Rod dissector is available at: https://github.com/rigazilla/hotrod-dissector

Beyond Per-Cache Eviction

2026-06-16T00:00:00+00:00

Per-cache memory limits

Up until now, Infinispan has required you to configure memory bounds for each cache individually. You decide how much memory each cache is allowed to consume, and the eviction machinery enforces those limits independently.

Suppose you have a node with 4GB of heap available for caching and five caches to fill it. You assign each cache its own slice of that budget — say 200MB for some and 300MB for others. This works, but it means you need to know upfront how much each cache will need. Caches that don’t use their full allocation leave memory on the table, while others may be constrained. Every time you resize a cache you have to revisit the arithmetic.

This also means that creating a new cache at runtime requires you to carve out a separate memory allocation for it — memory that has to come from somewhere, potentially requiring you to shrink existing caches. With shared containers, a new cache can simply join an existing container and immediately share its budget with no reconfiguration needed.

Infinispan 16.1 introduced container eviction as an alternative approach.

Container eviction

Container eviction lets you define a single memory boundary that is shared across multiple caches. Instead of configuring limits per cache, you create a named eviction container at the cache-container level and reference it from any caches that should share that budget.

Infinispan supports two types of eviction containers:

max-size-container — bounds by total memory (e.g., 100MB, 1GB)
max-count-container — bounds by total entry count (e.g., 1000 entries)

You can define multiple containers if you need different budgets for different groups of caches.

In the example below, caches A and B share a hot container (400MB) while caches C, D, and E share a warm container (900MB):

XML

Infinispan 16.2

2026-06-03T00:00:00+00:00

"Arctic Panzer Wolf"

Infinispan 16.2 is here, and it is codenamed "Arctic Panzer Wolf". Like the beer, this release packs a punch: it’s bold, it’s fierce, and there’s a lot of it.

RESP endpoint

This release is a huge step forward for our Redis-compatible RESP endpoint. So many new things that it deserves its own section!

Probabilistic data structures

We’ve implemented a whole family of probabilistic data structures:

Bloom Filters (BF.*): space-efficient probabilistic membership testing. Add items and check whether they might be in the set — with a configurable false positive rate.
Cuckoo Filters (CF.*): like Bloom Filters, but they also support deletion. Handy when your data is more dynamic.
Count-Min Sketch (CMS.*): estimate the frequency of items in a stream without storing all the data. Perfect for anomaly detection and traffic analysis.
Top-K (TOPK.*): maintain a list of the K most frequent items in a stream. While CMS can tell you how many times an item has appeared, Top-K tells you which items appear most often — it tracks the heavy hitters so you don’t have to query every item individually.
HyperLogLog (PFCOUNT, PFMERGE): estimate the cardinality of large datasets using very little memory. Count unique visitors, unique events, unique everything.

All of these work in clustered mode too!

New BITOP operations from Redis 8.2

Keeping up with the latest from Redis, we’ve added the four new bitwise operations introduced in Redis 8.2: These give you finer-grained control over bitwise set operations across keys.

GEOSEARCH commands

The GEOSEARCH family of commands is now fully implemented, letting you perform radius and bounding-box queries on geospatial data.

COPY, DELEX, DIGEST, and more

COPY: copy a key to another key, optionally replacing the destination.
DELEX: delete a key only if it exists (returning whether it was actually deleted).
DIGEST: return a hash digest of a key’s value.
SET conditional options: additional flags for conditional set operations.
PSUBSCRIBE / PUNSUBSCRIBE: pattern-based Pub/Sub subscriptions.
AGGREGATE COUNT option for ZUNION, ZINTER, ZUNIONSTORE, and ZINTERSTORE.
BITFIELD / BITOP: implemented all operations.

Local RESP caches in clustered mode

You can now use local RESP caches in a clustered server. Previously, a local RESP cache created on an unclustered server would prevent the server from starting in clustered mode. No more!

Infinispan Server

Granular JVM options

The server startup scripts now split JAVA_OPTS into independently overridable categories:

JAVA_OPTS_BASE — essential JVM flags (headless, ExitOnOutOfMemoryError, incubator modules)
JAVA_OPTS_NETWORK — network settings (IPv4/IPv6 stack preference)
JAVA_OPTS_MEMORY — heap, metaspace, and RAM percentage configuration
JAVA_OPTS_DEBUG — JPDA debug settings

Want to tweak just the memory settings? Set JAVA_OPTS_MEMORY and leave the rest alone. Setting JAVA_OPTS directly still overrides everything for backward compatibility.

ECS logging support

The server now bundles log4j-layout-template-json, enabling native Elastic Common Schema (ECS) formatted logging out of the box. Just point your Log4j2 config at the built-in ECS template:

No more custom images or runtime library hacking to get structured JSON logs into your Elasticsearch/Kibana stack.

Simplified PEM certificate configuration

TLS configuration with PEM certificates has been unified and simplified. The server now auto-detects keystore types, so you no longer need to juggle different property names for PEM vs PKCS#12 certificates.

Minimal boot logging

The server now uses minimal logging until the classpath is fully configured, preventing noisy or misleading log messages during early startup.

Configurable backpressure for Hot Rod client listeners

The server now supports configurable backpressure for Hot Rod client event listeners. When a client cannot consume events fast enough, the server buffers them up to a configurable limit instead of dropping events or blocking the originating cache operation. This gives operators control over the trade-off between memory usage and event delivery reliability for slow consumers.

Backup support for multimaps, RESP, and Memcached caches

Server backups now include multimap caches as well as caches created via the RESP and Memcached endpoints. Previously, these were silently skipped during backup and restore operations.

RocksDB cache store removed from the server distribution

The RocksDB cache store has been moved out of the server distribution. It is still available as a separate module if you need it, but the server image is now lighter. The bundled SIFS store is the recommended persistence option.

CLI

Suggestions

The CLI now provides suggestions based on your command history and command syntax.

Connection bookmarks

Tired of typing long connection URLs and credentials every time? The new bookmark command lets you save named connection bookmarks:

bookmark set prod -u https://prod-server:11222 --username admin --password secret
connect prod

Passwords are stored encrypted in a PKCS12 credential store. Bookmarks are also used by the new mcp CLI command for a seamless AI integration experience.

Core

JSON configuration schemas

Infinispan now provides JSON schemas that mirror the existing XSD schemas, making it easier to author and validate configuration in JSON and YAML formats with full editor support and autocompletion.

Pull-based state transfer

State transfer has been reworked to use a pull-based approach instead of the previous push model. This gives the receiving node much better control over backpressure and memory consumption during rebalancing. Previously, all existing owners would push data simultaneously, making memory pressure scale linearly with cluster size. The new approach is smarter and more efficient.

Memory monitor

A new MemoryMonitor component tracks JVM memory and GC health with configurable thresholds:

Memory threshold alerts when old generation heap usage exceeds a percentage (default 85%)
GC duration alerts when a single GC pause is too long (default 5 seconds)
GC pressure tracking alerts when too much time is spent in GC over a rolling window

All thresholds are tunable at runtime and configurable via a new element.

Dynamic eviction based on memory pressure

Eviction can now be driven by actual JVM memory pressure instead of relying solely on static entry counts or fixed memory sizes. When enabled, Infinispan monitors old generation heap usage and dynamically adjusts eviction thresholds to keep the JVM healthy. This means caches can make the most of available memory without the guesswork of manually sizing max-count or max-size — the system responds to real conditions, evicting more aggressively when memory is tight and relaxing when there is headroom.

Serialized cache entries on heap

You can now store cache entries in their serialized form even when using heap storage. This is particularly useful for entries with many fields where the serialized byte representation is more memory-efficient than the full Java object graph.

Graceful shutdown and network partitions

The graceful shutdown procedure has been hardened to handle network partitions correctly. Previously, star-shaped partitions (where the coordinator could see all nodes, but nodes couldn’t see each other) during restart could lead to data loss. This has been fixed.

Orderly cache scale-down

Stopping a cache or (concurrently) scaling down a cluster node while state transfer is in progress could previously result in data loss: the departing node would leave before its data had been fully redistributed to the remaining members. New overloads on Cache.stop(timeout, TimeUnit), EmbeddedCacheManager.stop(timeout, TimeUnit), and EmbeddedCacheManager.stopCache(cacheName, timeout, TimeUnit) let you specify how long to wait for any in-flight state transfer to complete before leaving. If the timeout elapses, the method returns false so you can decide what to do next. The existing no-arg stop() methods continue to work as before.

Generic Micrometer MeterRegistry support

Infinispan now supports any Micrometer MeterRegistry, not just Prometheus. This means you can use OTLP, Simple, or any other Micrometer registry implementation without needing a Prometheus dependency on the classpath.

Counter configuration events

Counter configuration changes (add/modify/remove) now generate container events and are streamed via the REST SSE listeners. This enables the Infinispan Operator to implement Counter custom resources.

SIFS persistence store improvements

The Soft-Index File Store (SIFS) has received several reliability and performance improvements:

Buffered index updates: index writes are now batched in memory before being flushed to disk, reducing the number of I/O operations and improving write throughput.
B+ tree refactoring: the internal B+ tree used for the SIFS index has been extracted into a standalone, independently testable class, resolving a number of hard-to-reproduce corruption issues related to soft reference reclamation and concurrent access.
Segment lifecycle fixes: fixed a race condition where rapid segment removal and re-addition could corrupt the index, and ensured that segment removal completes fully before the segment can be reused.
Persistence timeout support: persistence operations now have configurable timeouts, preventing the system from hanging indefinitely when a store operation stalls or a lock is never released.

ProtoStream

The ProtoStream serialization library has seen major improvements across performance, usability, and JSON support:

ASCII string optimizations: writing ASCII strings now takes advantage of the JVM’s internal String coder and value fields, and uses VarHandle for fixed-width writes, reducing encoding overhead.
Kotlin support: the annotation processor now supports Kotlin classes and data class types.
Copy-on-write serialization context: the serialization context state is now copy-on-write, improving thread safety when schemas are registered concurrently as well as improving performance.
JPMS support: ProtoStream is now fully modularized with proper module-info descriptors.

Query

ANTLR 4

The Ickle query parser has been migrated from the unmaintained ANTLR 3 to ANTLR 4, improving reproducible builds and eliminating a stale runtime dependency.

Spring Boot

Automatic schema registration

The Spring Boot integration now automatically registers Protobuf schemas, matching the behavior that was already available in the Quarkus integration.

Console

The web console has received a batch of usability improvements:

User permissions page: a new page to display current user permissions, making it easier to understand who can do what.

Schema editor with syntax highlighting: the schema editor now uses the Monaco code editor with Protobuf syntax highlighting and code assistance.

Manage columns in cache detail: customize which columns are displayed in the cache entries view.

Query history: your recent queries are now remembered, so you can quickly re-run them.

Swagger UI and metrics links: direct links to the Swagger UI and metrics endpoints from the console.
Truncate result values: a checkbox to truncate long values in query results for better readability.
Persistent pagination settings: pagination preferences are now remembered across sessions.
Cache deletion from detail view: delete a cache directly from its detail page.
Internationalization: updated translations for French, Spanish, Italian, and Brazilian Portuguese.

MCP

CLI stdio transport

Connecting your AI tools to Infinispan just got a whole lot easier. We’ve added an mcp command to the CLI that acts as a stdio transport bridge for the Model Context Protocol.

This means you can now use Infinispan as an MCP server from Claude Desktop, Claude Code, VS Code, or any other MCP client:

{
  "mcpServers": {
    "infinispan": {
      "command": "infinispan",
      "args": ["mcp", "--bookmark", "prod-cluster"]
    }
  }
}

The CLI command connects to the server’s /v3/mcp HTTP endpoint and proxies JSON-RPC messages via stdin/stdout. Use it with CLI bookmarks (we mentioned those above!) for a seamless, secure connection.

GC log as MCP resource

The server’s GC log is now exposed as an MCP resource, so your AI tools can inspect garbage collection behavior directly.

Backwards compatibility

Infinispan 16.2 is fully backwards compatible with 16.1 deployments.

The next release

According to our roadmap, our next release will be 16.3, and it will happen on 2026-10-07.

Release notes

You can look at the release notes to see what was changed since our previous release.

Get them from our download page.

Infinispan Hot Rod JS Client 0.14.0: Near Feature Parity with Java

2026-05-06T00:00:00+00:00

We are happy to announce the release of the Infinispan Hot Rod JS Client 0.14.0. This release brings the JavaScript client very close to feature parity with the Java Hot Rod client, with support for near caching, distributed counters, admin operations, and protocol auto-negotiation.

Protocol auto-negotiation

The client can now automatically negotiate the highest mutually-supported protocol version with the server. No more guessing which version to use: just set version: 'auto' and the client will pick the best available.

var infinispan = require('infinispan');

var client = await infinispan.client(
  {port: 11222, host: 'localhost'},
  {
    version: 'auto',
    authentication: {
      enabled: true,
      saslMechanism: 'DIGEST-MD5',
      userName: 'admin',
      password: 'changeit'
    }
  }
);

// Check which version was negotiated
console.log('Protocol:', client.getProtocolVersion());  // e.g. '4.1'

Near caching

Near caching stores recently accessed entries on the client side, dramatically reducing latency for read-heavy workloads. The cache uses LRU eviction and is automatically invalidated when entries are modified.

var client = await infinispan.client(
  {port: 11222, host: 'localhost'},
  {
    version: 'auto',
    nearCache: { maxEntries: 16 },
    authentication: { /* ... */ }
  }
);

await client.put('key', 'value');

// First get: fetches from server and populates the near cache
var v1 = await client.get('key');

// Second get: served from the local near cache, no server roundtrip
var v2 = await client.get('key');

// Writes automatically invalidate the near cache
await client.put('key', 'new-value');

Distributed counters

Distributed counters are cluster-wide atomic counters, available in two flavors: strong (linearizable, optionally bounded) and weak (higher concurrency, eventually consistent).

// Strong unbounded counter
await client.counterCreate('page-views', {
  type: 'strong',
  initialValue: 0
});

// Strong bounded counter
await client.counterCreate('stock', {
  type: 'strong',
  initialValue: 50,
  lowerBound: 0,
  upperBound: 1000,
  storage: 'persistent'
});

// Weak counter for high-throughput scenarios
await client.counterCreate('impressions', {
  type: 'weak',
  initialValue: 0,
  concurrencyLevel: 4
});

// Atomic operations
var current = await client.counterGet('page-views');
var updated = await client.counterAddAndGet('page-views', 1);
var swapped = await client.counterCompareAndSwap('stock', 50, 49);
await client.counterReset('page-views');

Admin operations

The client.admin namespace provides cache lifecycle management and Protobuf schema administration, enabling full cluster management directly from JavaScript.

// Create a cache from XML configuration
await client.admin.createCache('sessions',
  ''
);

// Idempotent create: no error if it already exists
await client.admin.getOrCreateCache('sessions',
  ''
);

// List all caches
var names = await client.admin.cacheNames();

// Remove a cache
await client.admin.removeCache('sessions');

// Register a Protobuf schema
await client.admin.registerSchema('person.proto', `
  package example;
  message Person {
    required string name = 1;
    optional int32 age = 2;
  }
`);

Protocol 3.1, 4.0, and 4.1 support

This release adds support for Hot Rod protocol versions 3.1, 4.0, and 4.1, each bringing new capabilities:

Protocol 3.1 — Distributed counter operations
Protocol 4.0 — Previous value with metadata in mutation responses
Protocol 4.1 — JSON data format support

// Protocol 4.0+: mutation operations can return previous values
var client = await infinispan.client(
  {port: 11222, host: 'localhost'},
  { version: '4.0', authentication: { /* ... */ } }
);

await client.put('key', 'original');
var prev = await client.put('key', 'updated', { previous: true });
console.log(prev);  // 'original'

Get started

Install the client via npm:

npm install infinispan

Check out the full source code and documentation on GitHub.