Quarkus Infinispan Client

What You Will Learn

How to use the Quarkus Infinispan client extension to connect to an Infinispan Server, store indexed Protobuf entities, and perform full-text search queries through a JAX-RS REST resource.

Prerequisites

Java 17+
Quarkus
An Infinispan Server running on localhost:11222 (or Docker/Podman for Quarkus Dev Services)

Step 1: Add Dependencies

Add the Quarkus Infinispan client and REST Jackson extensions:

<dependency>
   <groupId>io.quarkus</groupId>
   <artifactId>quarkus-infinispan-client</artifactId>
</dependency>
<dependency>
   <groupId>io.quarkus</groupId>
   <artifactId>quarkus-rest-jackson</artifactId>
</dependency>

Step 2: Define the Protobuf Entity

Create an indexed Protobuf record with @Text fields for full-text search:

@Proto
@Indexed
public record Character(UUID id, @Text String name, @Text String bio, Archetype archetype) {

}

Step 3: Configure the Cache

In application.properties, point to the cache configuration and set server coordinates:

quarkus.infinispan-client.cache.characters.configuration-resource=indexedCache.xml
characters.filename = characters.csv

# Uncomment if you are running a server in local
# quarkus.infinispan-client.devservices.enabled=false
# quarkus.infinispan-client.hosts=localhost:11222
# quarkus.infinispan-client.username=admin
# quarkus.infinispan-client.password=password

# Assumes a server is running, with admin/password, locally
%prod.quarkus.infinispan-client.hosts=localhost:11222
%prod.quarkus.infinispan-client.username=admin
%prod.quarkus.infinispan-client.password=password

In dev mode, Quarkus Dev Services automatically starts an Infinispan container.

Step 4: Inject the RemoteCache and Query

Inject the remote cache and perform full-text queries using Ickle:

@ApplicationScoped
public class CharacterSearch {
   @Inject
   @Remote(DataLoader.CHARACTERS_CACHE)
   RemoteCache<String, Character> characters;

   public Character getById(String id) {
      return characters.get(id);
   }

   public CompletionStage<Character> getByIdAsync(String id) {
      return characters.getAsync(id);
   }

   /**
    * Performs a simple full-text query on name and bio
    *
    * @param term
    * @return character names
    */
   public Set<String> search(String term) {
      if (characters == null) {
         Log.error("Unable to search...");
         throw new IllegalStateException("Characters store is null. Try restarting the application");
      }
      String query = "FROM tutorial.Character c"
      + " WHERE c.name:'~"+ term + "'"
      + " OR c.bio: '~" + term + "'";

      List<Character> result = characters.<Character>query(query).execute().list();
      return result.stream().map(Character::name).collect(Collectors.toSet());
   }

}

Step 5: Run the Tutorial

mvn quarkus:dev

Then query the REST endpoints:

curl http://localhost:8080/characters/0
curl "http://localhost:8080/characters/query?term=dragon"

What’s Next

Vector search for kNN similarity search on embeddings
Remote queries for Ickle query basics with the Hot Rod client