Ickle Queries with Embedded Infinispan

What You Will Learn

How to annotate entities for indexing, configure an indexed cache, execute Ickle queries to search for data, and use update by query to modify entries in an embedded Infinispan cache.

Prerequisites

Java 17+

Step 1: Add Dependencies

Add the Infinispan core, API, and query modules to your pom.xml:

<dependency>
   <groupId>org.infinispan</groupId>
   <artifactId>infinispan-api</artifactId>
</dependency>
<dependency>
   <groupId>org.infinispan</groupId>
   <artifactId>infinispan-core</artifactId>
</dependency>
<dependency>
   <groupId>org.infinispan</groupId>
   <artifactId>infinispan-query</artifactId>
</dependency>

Step 2: Define an Indexed Entity

Annotate your entity class with @Indexed and mark searchable fields with @Basic:

@Indexed
public class Person {
   @Basic
   String name;

   @Basic
   String surname;

   public Person(String name, String surname) {
      this.name = name;
      this.surname = surname;
   }

Step 3: Configure an Indexed Cache

Enable indexing on the cache configuration and register the indexed entity:

      // Create cache config
      ConfigurationBuilder builder = new ConfigurationBuilder();
      builder.indexing()
              .enable()
              .storage(IndexStorage.LOCAL_HEAP)
              .addIndexedEntity(Person.class);

      // Obtain the cache
      cache = cacheManager.administration()
              .withFlags(CacheContainerAdmin.AdminFlag.VOLATILE)
              .getOrCreateCache("cache", builder.build());

Step 4: Run an Ickle Query

Store some entries and query them using the Ickle query language:

      // Store some entries
      cache.put("person1", new Person("William", "Shakespeare"));
      cache.put("person2", new Person("William", "Wordsworth"));
      cache.put("person3", new Person("John", "Milton"));
      // Construct a query
      Query<Person> query = cache.query("from org.infinispan.tutorial.simple.query.Person where name = 'William'");
      // Execute the query
      return query.execute().list();

Step 5: Update Entries by Query

Use executeStatement() to run UPDATE queries that modify entries matching a WHERE clause. You can use named parameters with setParameter() just like in SELECT queries:

   static int updateByQuery() {
      Query<Person> query = cache.query("UPDATE FROM org.infinispan.tutorial.simple.query.Person SET surname = 'Bard' WHERE name = 'William'");
      int updated = query.executeStatement();
      System.out.printf("Updated %d entries%n", updated);
      return updated;
   }

   static int updateByQueryWithParameter() {
      Query<Person> query = cache.query("UPDATE FROM org.infinispan.tutorial.simple.query.Person SET name = :newName WHERE name = :oldName");
      query.setParameter("newName", "Johnny");
      query.setParameter("oldName", "John");
      int updated = query.executeStatement();
      System.out.printf("Updated %d entries with parameter%n", updated);
      return updated;
   }

Step 6: Run the Tutorial

mvn package exec:java

The output shows the two persons named William (Shakespeare and Wordsworth).

What’s Next

Try programmatic index definitions without annotations
Use distributed streams for parallel cache processing