Blogs Infinispan 14 indexing & query news

Infinispan 14 indexing & query news

Dear Infinispan community,

with the Infinispan 14 development release 03 we introduced improvements on indexing and search capabilities.

Infinispan indexing annotations

We are going to replace Hibernate annotations with Infinispan indexing annotations. The new annotations can be used in the same way for both embedded and remote queries.

Here are examples of two annotated POJOs:
public class Poem {

   private Author author;
   private String description;
   private Integer year;

   @Embedded(includeDepth = 2, structure = Structure.NESTED)
   public Author getAuthor() {
      return author;

   @Text(projectable = true, analyzer = "whitespace", termVector = TermVector.WITH_OFFSETS)
   public String getDescription() {
      return description;

   @Basic(projectable = true, sortable = true, indexNullAs = "1800")
   public Integer getYear() {
      return year;
public class Author {

   private String name;

   public Author(String name) { = name;

   @Keyword(projectable = true, sortable = true, normalizer = "lowercase", indexNullAs = "unnamed", norms = false)
   public String getName() {
      return name;

   public void setName(String name) { = name;

Use the @Basic annotation for indexed fields without any special string/text transformation. When you apply a normalizer to a String field, use the @Keyword annotation. When you apply an analyzer to a String field, use the @Text annotation.

The new annotations allow you to set a single annotation per indexed field if the field should be sortable or projectable and if you want to use an analyzer or normalizer on the field. However, the combination of an attribute and the annotation must be supported, for instance the attribute sortable cannot be used with the @Text annotation, since an analyzed field cannot be used to sort the result set.

When indexing entities with null values, define a default value with the indexNullAs attribute.

For embedded indexes use the @Embedded annotation and choose between two structures. The NESTED structure preserves the original object relationship structure and the FLATTENED structure makes the leaf fields multi-valued of the parent entity, so the embedded entity will not be present in the index.

Index startup mode

Indexes can be persistent and cache data can be volatile and vice versa. You can perform some operations to keep the index consistent with data in the cache.

We introduced the startup-mode configuration. Here is an example:

  <indexing storage="filesystem" startup-mode="purge">
    <!-- Additional indexing configuration goes here. -->

With this configuration every time the cache is started, the indexes will be purged. Possible values are: purge, reindex, none, and auto. When you choose auto mode, Infinispan decides what is the right operation to run to align cache data and indexes.

Index schema update

This is an advanced feature to be used only in case your model needs to be evolved while continuing querying the cache data without data migrations or re-indexing.

For a comprehensive guide about when to use schema update instead of migrating or re-indexing the data refer to the documentation.

The command can be triggered from the HotRod remote administration API:


or using the REST API, targeting the uri:

POST .../v2/caches/{cacheName}/search/indexes?action=updateSchema

or using the Infinispan CLI by running update-schema on the runtime cache instance.

Get it, Use it, Ask us!

We’re hard at work on new features, improvements and fixes, so watch this space for more announcements!

Please, download and test the latest release.

The source code is hosted on GitHub. If you need to report a bug or request a new feature, look for a similar one on our JIRA issues tracker. If you don’t find any, create a new issue.

If you have questions, are experiencing a bug or want advice on using Infinispan, you can use GitHub discussions. We will do our best to answer you as soon as we can.

The Infinispan community uses Zulip for real-time communications. Join us using either a web-browser or a dedicated application on the Infinispan chat.

Fabio Massimo Ercoli

Member of the Infinispan @core team at Red Hat. Accountable for indexing, query, serialization, transcoding, metrics and tracing for the hybrid cloud. Former Hibernate @core team, working on NoSql & searching. Former Red Hat consultant, working on intense data applications and solutions. An open source enthusiast and continuous learner.