Infinispan

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.

Vector search quickstart with Infinispan

2026-04-30T00:00:00+00:00

Vector databases have become essential building blocks for AI-powered applications. They let you store unstructured data — text, images, audio — as numerical embeddings that capture semantic meaning, and then find similar items using nearest-neighbour search.

Infinispan has supported vector search since version 15, and it does so with a distinctive approach: your data model is defined through ProtoStream annotations that generate Protobuf schemas automatically, your queries use the Ickle query language that seamlessly combines relational filters, full-text search, and kNN vector predicates, and your schemas can evolve over time without breaking existing clients.

This quickstart walks through a complete example — from defining a data model to running hybrid vector+metadata queries — using a catalogue of beers as our dataset. If the beer names look familiar, that’s because every Infinispan release is named after a beer.

Defining the data model

In Infinispan, entity classes are plain Java records (or POJOs) annotated with ProtoStream and indexing annotations. These annotations serve double duty: they define the Protobuf serialization schema and the search index mapping in a single place.

Here is our Beer entity:

@Proto
@Indexed
public record Beer(
   @Keyword(projectable = true, sortable = true)
   String name,

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

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

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

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

   @Text
   String description,

   @Vector(dimension = 3, similarity = VectorSimilarity.COSINE)
   float[] descriptionEmbedding
) {
}

A few things to note:

@Proto generates the Protobuf schema from the record fields — no separate .proto file to maintain.
@Indexed enables search indexing for the entity.
@Keyword fields are stored as exact tokens — ideal for beer names, styles, and brewery names. The normalizer option allows case-insensitive matching.
@Text fields are analyzed with a full-text tokenizer, enabling natural language search across tasting notes and descriptions.
@Vector(dimension = 3, similarity = VectorSimilarity.COSINE) marks the embedding field for kNN search. The dimension must match your vector size — here we use 3 for illustration, but a real embedding model would produce 384 or more dimensions.
@Basic handles numeric fields like ABV with support for range queries and sorting.

Generating the Protobuf schema

ProtoStream generates the schema and the marshaller at compile time. All you need is an interface:

@ProtoSchema(includeClasses = Beer.class, schemaPackageName = "quickstart")
public interface BeerSchema extends GeneratedSchema {
   BeerSchema INSTANCE = new BeerSchemaImpl();
}

The generated .proto schema is automatically registered with the server when your client connects. This schema can evolve — you can add new fields, deprecate old ones — without breaking clients that are still using the previous version. This is a direct benefit of Protobuf’s forwards and backwards compatibility guarantees.

Imagine you later want to add food pairing suggestions or IBU ratings: just add the field to the record, and older clients that don’t know about it will continue to work.

Connecting and storing data

ConfigurationBuilder builder = new ConfigurationBuilder();
builder.addServer().host("localhost").port(11222)
   .security().authentication().username("admin").password("secret");

RemoteCacheManager cacheManager = new RemoteCacheManager(builder.build());

RemoteCache cache = cacheManager.administration()
   .getOrCreateCache("beers", new XMLStringConfiguration(
      "" +
      "  " +
      "    " +
      "      quickstart.Beer" +
      "    " +
      "  " +
      ""));

Now let’s populate the cache with some beers — all named after Infinispan releases.

In a production application you would generate embeddings from a model such as all-MiniLM-L6-v2 (384 dimensions). For this quickstart we use hand-crafted 3-dimensional vectors where each axis captures a flavour profile: dark/roasty, light/crisp, and hoppy/craft. Beers of similar style naturally cluster together in this space — stouts near [1, 0, 0], lagers near [0, 1, 0], IPAs near [0, 0, 1] — so kNN queries return intuitive results.

cache.put("beer:1", new Beer(
   "Guinness", "Stout", "Guinness Brewery", "Ireland", 4.2,
   "A rich, creamy stout with deep roasted barley flavours, hints of coffee and chocolate, and a velvety smooth finish.",
   new float[]{0.95f, 0.05f, 0.10f}
));

cache.put("beer:2", new Beer(
   "Delirium", "Belgian Strong Ale", "Brouwerij Huyghe", "Belgium", 8.5,
   "A complex strong blonde ale with fruity esters, spicy phenols, and a warming alcohol presence balanced by a dry finish.",
   new float[]{0.30f, 0.30f, 0.70f}
));

cache.put("beer:3", new Beer(
   "Estrella Galicia", "Lager", "Hijos de Rivera", "Spain", 5.5,
   "A crisp European lager with a balanced malt backbone, mild hop bitterness, and a clean refreshing finish.",
   new float[]{0.10f, 0.90f, 0.15f}
));

cache.put("beer:4", new Beer(
   "Mahou", "Pilsner", "Mahou San Miguel", "Spain", 5.5,
   "A golden pilsner with delicate floral hop aromas, light biscuity malt, and a bright effervescent character.",
   new float[]{0.05f, 0.85f, 0.25f}
));

cache.put("beer:5", new Beer(
   "Corona Extra", "Pale Lager", "Grupo Modelo", "Mexico", 4.5,
   "A light, easy-drinking pale lager with subtle sweetness, a hint of citrus, and a crisp dry finish best enjoyed ice-cold.",
   new float[]{0.05f, 0.95f, 0.10f}
));

cache.put("beer:6", new Beer(
   "Tactical Nuclear Penguin", "Imperial Stout", "BrewDog", "Scotland", 32.0,
   "An extreme imperial stout aged in whisky casks, intensely smoky with dark chocolate, coffee, and dried fruit notes.",
   new float[]{0.98f, 0.02f, 0.20f}
));

cache.put("beer:7", new Beer(
   "Brahma", "Lager", "Ambev", "Brazil", 4.3,
   "A light Brazilian lager, smooth and mildly sweet, brewed for easy drinking in warm weather.",
   new float[]{0.05f, 0.92f, 0.05f}
));

cache.put("beer:8", new Beer(
   "Radegast", "Czech Lager", "Radegast Brewery", "Czech Republic", 5.0,
   "A traditional Czech lager with a prominent Saaz hop aroma, bready malt character, and a crisp bitter finish.",
   new float[]{0.15f, 0.80f, 0.30f}
));

cache.put("beer:9", new Beer(
   "Turia", "Märzen", "Turia Brewery", "Spain", 5.4,
   "A toasted amber märzen from Valencia with caramel malt sweetness, a nutty aroma, and a smooth medium body.",
   new float[]{0.60f, 0.40f, 0.15f}
));

cache.put("beer:10", new Beer(
   "Hoptimus Prime", "IPA", "Hoptimus Brewing", "USA", 7.5,
   "An aggressively hopped American IPA bursting with tropical fruit, pine resin, and grapefruit citrus over a sturdy malt backbone.",
   new float[]{0.10f, 0.15f, 0.95f}
));

cache.put("beer:11", new Beer(
   "Pagoa", "Basque Ale", "Pagoa Brewery", "Spain", 5.0,
   "A craft ale from the Basque Country with earthy hops, a light fruity character, and a balanced malty sweetness.",
   new float[]{0.25f, 0.35f, 0.60f}
));

Querying with Ickle

Before we get to vector search, let’s look at what Ickle can do with traditional queries. This is where Infinispan stands out: you don’t need to learn a separate query syntax for metadata filters and vector search — Ickle handles both.

Full-text search

Find beers whose description mentions "chocolate":

Query query = cache.query(
   "from quickstart.Beer b where b.description : 'chocolate'");
List results = query.list();
// Returns: Guinness, Tactical Nuclear Penguin

Keyword and range filters

Find session beers (under 5% ABV) from Spain:

Query query = cache.query(
   "from quickstart.Beer b where b.country = 'Spain' and b.abv < 5.0");
List results = query.list();

Projections and sorting

Select specific fields and sort by ABV — a good way to build a menu card:

Query query = cache.query(
   "select b.name, b.style, b.brewery, b.abv from quickstart.Beer b " +
   "where b.country = 'Spain' order by b.abv");
List results = query.list();
// Turia (5.4), Estrella Galicia (5.5), Mahou (5.5), Pagoa (5.0)

Vector search (kNN)

Now for the main event. Vector search in Ickle uses the <-> operator to express a kNN predicate: find the k nearest neighbours of a given vector.

Basic kNN query

Find the 3 beers closest to the "dark roasty" end of our flavour space:

Query query = cache.query(
   "from quickstart.Beer b where b.descriptionEmbedding <-> [:v]~:k");
query.setParameter("v", new float[]{0.9f, 0.1f, 0.1f});
query.setParameter("k", 3);

List results = query.list();
// Returns: Guinness, Tactical Nuclear Penguin, Turia

Both the vector and k are parameterised — you don’t need to interpolate values into the query string.

Score projection

To see how close each result is to the query vector, project the score:

Query query = cache.query(
   "select b.name, b.style, score(b) from quickstart.Beer b " +
   "where b.descriptionEmbedding <-> [:v]~:k");
query.setParameter("v", new float[]{0.05f, 0.9f, 0.1f});
query.setParameter("k", 3);

List results = query.list();
for (Object[] row : results) {
   System.out.printf("%-30s %-20s score=%.4f%n", row[0], row[1], row[2]);
}
// Corona Extra  score=1.0000
// Brahma        score=0.9992
// Estrella      score=0.9985

Hybrid queries: vector + metadata

This is where Ickle really shines. You can combine kNN search with any classic predicate — keyword matches, range filters, full-text search — using a filtering clause.

"Something like a lager, but not too strong"

Find the 3 beers closest to the "light crisp" vector, but only lagers under 5% ABV:

Query query = cache.query(
   "select score(b), b.name, b.style, b.abv from quickstart.Beer b " +
   "where b.descriptionEmbedding <-> [:v]~:k " +
   "filtering (b.style = 'Lager' and b.abv < 5.0)");
query.setParameter("v", new float[]{0.05f, 0.95f, 0.05f});
query.setParameter("k", 3);

List results = query.list();
// Returns: Brahma (4.3%)

Vector search filtered by country

Find beers from Spain closest to a "toasted malty" profile:

Query query = cache.query(
   "select score(b), b.name, b.style, b.abv from quickstart.Beer b " +
   "where b.descriptionEmbedding <-> [:v]~:k filtering b.country = 'Spain'");
query.setParameter("v", new float[]{0.7f, 0.3f, 0.1f});
query.setParameter("k", 3);

List results = query.list();
// Returns: Turia (0.99), Pagoa (0.80), Estrella Galicia (0.75)

Combining full-text and vector search

Find beers whose descriptions mention "citrus" and are closest to the "hoppy craft" vector:

Query query = cache.query(
   "select score(b), b.name, b.brewery, b.abv from quickstart.Beer b " +
   "where b.descriptionEmbedding <-> [:v]~:k " +
   "filtering b.description : 'citrus'");
query.setParameter("v", new float[]{0.1f, 0.1f, 0.95f});
query.setParameter("k", 5);

List results = query.list();
// Returns: Hoptimus Prime (0.9993), Corona Extra (0.6061)

The filtering clause accepts any valid Ickle predicate — including boolean combinations with and / or — so you can build arbitrarily complex filters. The filter is applied before the kNN search, narrowing the candidate set.

Why Infinispan for vector search?

If you’re evaluating vector databases, here is what sets Infinispan apart:

Unified query language. Ickle gives you relational queries, full-text search, and vector kNN search in a single language. No need for a separate "search module" with its own syntax — the same cache.query(…) call handles everything.

Type-safe data modelling. ProtoStream annotations let you define your schema, serialization, and index mappings in one place. The Protobuf schema is generated at compile time, so schema mismatches are caught before they reach production.

Schema evolution. Protobuf’s compatibility guarantees mean you can add new fields (like a vector embedding column) to an existing entity without breaking older clients. Roll out vector search incrementally — existing applications keep working while new ones start populating and querying the embedding field.

Distributed by design. kNN queries work across a distributed cluster. Infinispan scatters data across nodes and fans out vector searches in parallel, merging results transparently.

Multiple access protocols. The same indexed cache is accessible via Hot Rod (Java, C#, JS, Python), REST, and the RESP (Redis-compatible) protocol. Your vector search investment is not locked into a single client ecosystem.

Tuning vector indexing

The @Vector annotation exposes HNSW graph parameters that let you trade indexing speed for search accuracy. These become important with real embedding models where the dimension is much larger (e.g. 384 or 768):

@Vector(
   dimension = 384,                         // match your embedding model
   similarity = VectorSimilarity.COSINE,
   beamWidth = 512,                         // graph construction quality (default: 512)
   maxConnections = 16                      // neighbours per node (default: 16, range: 2-100)
)
float[] descriptionEmbedding;

beamWidth (efConstruction): higher values build a more accurate graph at the cost of slower indexing.
maxConnections (m): controls memory consumption and search precision. Stay in the 2–100 range.
similarity: choose from L2 (default, euclidean), COSINE, INNER_PRODUCT, or MAX_INNER_PRODUCT depending on your embedding model’s recommendations.

Run it yourself

A complete runnable version of this quickstart is available in the infinispan-simple-tutorials repository. It uses Testcontainers to start an Infinispan server automatically — all you need is Docker and Maven:

git clone https://github.com/infinispan/infinispan-simple-tutorials.git
cd infinispan-simple-tutorials
mvn -pl infinispan-remote/vector-search compile exec:exec

The tutorial uses the same 3-dimensional hand-crafted vectors shown in this post. To move to a real embedding model, change the dimension in @Vector and replace the float[] literals with vectors from your model — the query patterns stay identical.

Next steps

Read the full Query guide for Ickle syntax details.
Explore ProtoStream encoding to learn about schema evolution and custom marshallers.
Check out the tutorials for more runnable examples.
Join the conversation on Zulip or GitHub Discussions.

Infinispan Joins the OGX Ecosystem as a Vector IO Provider

2026-04-17T10:00:00+00:00

Infinispan has been integrated into the OGX (Open GenAI Stack), formerly known as Llama Stack, as a vector IO provider, enabling developers to build RAG (Retrieval-Augmented Generation) applications with distributed vector search.

What is OGX?

OGX (Open GenAI Stack) is an open-source agentic API server that composes inference providers, vector stores, safety backends, tool runtimes, and file storage into a single deployable server for building complete AI applications. It serves as a drop-in replacement for the OpenAI API and can run anywhere with any model and infrastructure.

Infinispan’s Vector Capabilities

The integration brings Infinispan’s distributed caching architecture to RAG applications with three powerful search modes:

Vector Search: Embedding-based similarity search using cosine similarity
Keyword Search: Full-text search via Infinispan Query DSL or Ickle
Hybrid Search: Combined vector and keyword search with configurable reranking (RRF or weighted)

Additional features include HTTPS/TLS support, Basic and Digest authentication, and seamless REST API integration.

Try the Demo

Check out our demo project at https://github.com/rigazilla/infinispan-llama-stack-rag-demo that shows how to configure Infinispan as the vector IO backend for OGX RAG workflows, with examples demonstrating document upload, vector embedding storage, and semantic search. As a bonus, you’ll also learn about the fascinating pataphysical science of Chelonofelodynamics!

Learn More

Try it out and let us know what you build!

Exploring the New OpenAPI-Compliant REST API v3 in Infinispan 16.1

2026-04-02T18:00:00+00:00

Exploring the New OpenAPI-Compliant REST API v3 in Infinispan 16.1

With Infinispan 16.1 "Polly Want a Pilsner", we introduce the OpenAPI-compliant v3 REST API, bringing modern API standards to Infinispan.

The Evolution

Infinispan now embraces OpenAPI standards with the new v3 REST API, enabling better tooling, documentation, and developer experience through standardized API descriptions.

What’s New in v3?

Full OpenAPI 3.0 compliance
Interactive Swagger UI at /swagger-ui
Improved endpoint organization and type safety

Getting Started

Start an Infinispan Server 16.1+ and visit http://127.0.0.1:11222/swagger-ui/ to explore and test the API. The OpenAPI schema is available at http://127.0.0.1:11222/rest/v3/openapi.

OpenAPI Benefits

A standardized, rich API description like OpenAPI brings numerous advantages for developers:

Enhanced Documentation: Interactive, always-up-to-date API docs via Swagger UI
Automated Tooling: Generate client libraries in multiple languages automatically
Improved Testing: Built-in API testing interfaces
Polyglot Support: OpenAPI works across programming languages, enabling seamless integration regardless of your tech stack
AI-Assisted Development: AI code assistants can generate accurate client code from the OpenAPI spec, reducing development time and errors

Check out our demo at https://github.com/rigazilla/infinispan-sqlstore-demo/tree/openapi-demo, which demonstrates a live coding session where AI code assistants generate accurate Infinispan client code from the OpenAPI spec, showcasing rapid development and error reduction.

Conclusion

The v3 API brings modern API standards to Infinispan, enhancing developer productivity. Download 16.1, try the new OpenAPI v3 REST interface, and let us know your feedback!

For details, see REST API docs.

Infinispan 16.1

2026-02-04T00:00:00+00:00

"Polly Want a Pilsner"

Infinispan 16.1 is here, and it is codenamed "Polly Want a Pilsner".

It is the first release that follows our time-boxed plan.

Container-based eviction

Prior to this release, it was only possible to configure memory bounds for individual caches.

Infinispan 16.1 introduces the concept of bounded memory containers: configure a global container (you can have more than one), and whether you want it to be bound by count or by memory and reference that container name in the cache configuration.

The following diagram shows the difference between per-cache and container eviction

In the example below, the memory configuration for caches a and b combined will be bounded at 100MB:

OpenAPI / Swagger

Infinispan 10 introduced the v2 REST endpoint which aimed to improve the original API and expand it with all the requirements we added for data and system management. Unfortunately that API was designed in a way that made it impossible to represent via an OpenAPI descriptor.

Infinispan 16.1 introduces a new v3 REST API which is OpenAPI-compliant.

To try it out, start an Infinispan Server and point to http://127.0.0.1:11222/swagger-ui/

Query and Lucene 10

Thanks to the work done by our friends over at Hibernate Search, Infinispan now supports both Lucene 9 and 10.

Infinispan Server

Server now requires Java 25

Our server image has already included Java 25 since 16.0, but we’ve now made this a hard requirement for bare metal deployments too. Don’t worry: the clients can continue running with ye olde legacy Java versions of choice.

Lucene 10.3

By requiring Java 25, the server can now include Lucene 10.3, which can leverage SIMD to increase performance in several areas.

Pre-start batch scripts

The server can now automatically execute batch scripts before start. This feature is primarily intended for our operator in order to prepare the server according to its configuration, but it may also be useful for your own use-cases.

AOT cache in the container image

The server image now includes an AOT cache to reduce startup and warmup time.

CLI batch error handling

The CLI has been enhanced to better report errors during batch execution: you can now decide to fail-fast, fail-at-end or ignore batch errors altogether.

Default mechanisms

Infinispan Server no longer enables weak/vulnerable authentication mechanisms by default: algorithms which use MD5 and SHA-1 must be explicitly enabled if you want to keep using them.

Backwards compatibility

Infinispan 16.1 is fully backwards compatible with 16.0 deployments.

The next release

According to our roadmap, our next release will be 16.2, and it will happen on 2026-06-03.

Release notes

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

Get them from our download page.