Multiple questions on caching

[alecStewart1]

Hello! I'm trying to put together something with Quarkus + Kotlin + Hibernate Reactive + Panache.

The thing I'm running into now is working with caching. There's a few things.

Jakarta's caching

So we have some entity that's marked as cacheable with Jakarta:

@Entity
@Cacheable
@Serializable // with kotlinx.serialization
class MyEntity : PanacheEntity() {}

Then that entity has a property that's marked with @Cache with Hibernate

    @OneToMany(
        mappedBy = "anotherEntity",
        targetEntity = SomeOtherEntity::class,
        cascade = [(CascadeType.ALL)],
        fetch = FetchType.LAZY,
        orphanRemoval = true
    )
    @Cache(usage = CacheConcurrencyStrategy.READ_ONLY)
    lateinit var otherEntitties: MutableSet<SomeOtherEntity>

My question here is, is there any guidance from Quarkus as to how we should utilize this caching mechanism?

Caching with Caffeine

This is where things get a bit weirder. I'm going off of the information provided here.

Firstly is the issue of refreshing the cache. If we set the expiration after write to 12 hours in the application properties:

quarkus.cache.caffeine.expire-after-write=PT12H
quarkus.cache.caffeine.maximum-size=15000

The question is: how do we refresh the cache? I understand one could do so with having @CacheInvalidate and @CacheResult on some method that can be used forcibly refreshes the cache. I'm guessing the idea would be to schedule tasks to refresh the cache?

So would the following be preferable?

@Entity
@Cacheable
@Serializable // with kotlinx.serialization
class MyEntity : PanacheEntity() {
    companion object : PanacheCompanion<MyEntity> {
        @CacheInvalidate(cacheName = "myEntity", keyGenerator = SomeCustomKeyGenerator::class)
        @CacheResult(cacheName = "myEntity", keyGenerator = SomeCustomKeyGenerator::class)
        @Scheduled(every = "12h")
        fun getAllEntities(): Uni<Set<MyEntity>> {
            /*
             *  CollectionConverts.uniListToLinkedSet is just the following
             *  fun <T> uniListToLinkedSet(uniList: Uni<List<T>>): Uni<Set<T>> = uniList.map { lst: List<T> -> LinkedHashSet<T>(lst) }
            */  
            return CollectionConverts.uniListToLinkedSet(listAll(Sort.by("year").descending()))
        }
    }

    @OneToMany(
        mappedBy = "anotherEntity",
        targetEntity = SomeOtherEntity::class,
        cascade = [(CascadeType.ALL)],
        fetch = FetchType.LAZY,
        orphanRemoval = true
    )
    @Cache(usage = CacheConcurrencyStrategy.READ_ONLY)
    lateinit var otherEntitties: MutableSet<SomeOtherEntity>
}

But I assume that's not the correct way to use @Scheduled.

The other thing is we're now mixing different kinds of caching, so there's a good chances things get a bit messy.

[quarkus-bot[bot]]

/cc @geoand (kotlin)

[geoand]

cc @gwenneg

[alecStewart1]

I did find an answer to my first question:

https://quarkus.io/guides/hibernate-orm#caching

This doesn't related to caching the results of functions for active record entities, nor refreshing caches. I'm assuming using the scheduling tools provided is the "correct" or "best" solution for now, unless someone says otherwise.

[geoand]

Perhaps @yrodiere can help with the question about Hibernate / JPA @Cache.

For the Cache with Caffeine question, @gwenneg can likely help

[yrodiere]

The question is: how do we refresh the cache?

You don't. You only specify what needs to be cached, i.e. annotate entities or associations, or mark queries as cacheable.

It's not your job to keep the cache up to date, it's Hibernate ORM's. The ORM will invalidate cache entries on write, try to get cache entries on read, and put cache entries on cache miss.

There is of course some tuning involved (cache size, eviction, ...), but hopefully the docs should cover that. If something specific is not covered, please tell.

Do note that the default caching solution (Caffeine) has limitations, though: https://quarkus.io/guides/hibernate-orm#limitations-of-caching

I think @karesti has worked on integrating Infinispan as a caching solution, but I'm not sure she worked on integrating Hibernate ORM caching -- the docs certainly don't mention it.

[yrodiere]

The Hibernate "magic" related to caching has been there for literal decades, so I'm not sure you need to cross your fingers.
But sure, that's how it goes.

On the caffeine side of things:

quarkus.cache.caffeine.expire-after-write
quarkus.cache.caffeine.maximum-size

I don't think these will affect the caches created by Hibernate ORM, because they are for application data caching only, not for internal uses of Caffeine. The code seems to concur, but @Sanne will know best, if you want to be absolutely sure.

[alecStewart1]

Sorry, by "magic" with Hibernate's caching I mean that, you know it's happening when you enable it, but there's really only so much you can do to control it.

Although there's likely stuff you can do to have more control, but it begins to be more configuration than you'd likely would want to deal with, instead of simply messing with more basic options for @Cacheable and @Cache annotations (usage, etc.).

[Sanne]

hi @alecStewart1 we'd be happy to help if you had a more specific question, but I'm sure you understand that if it's about "you know it's happening .. likely stuff .. more control.. simply messing" it's all a bit confusing :)

Please don't enable caching if you're not sure of what you're doing or its semantics; there are several good books about Hibernate that will explain this in detail; the Hibernate ORM reference guide is also very clear about how this all works, and it's not different in Quarkus other than all dependencies being integrated out of the box.

[alecStewart1]

@Sanne
Apologies for my ignorance if that's caused confusion as to what the exact questions are. I'll definitely read more on how Hibernate's caching works.

Only thing I have left is if static methods to follow the active record model require any configuration/annotations to cache their results. So from the Simplified Hibernate Reactive with Panache:

import io.quarkus.hibernate.reactive.panache.PanacheEntity;

@Entity
public class Person extends PanacheEntity {
    public String name;
    public LocalDate birth;
    public Status status;

    public static Uni<Person> findByName(String name){
        return find("name", name).firstResult();
    }

    public static Uni<List<Person>> findAlive(){
        return list("status", Status.Alive);
    }

    public static Uni<Long> deleteStefs(){
        return delete("name", "Stef");
    }
}

If there's any more complex static methods that take an argument and return a Uni<List<Person>, is there anything that would need to be done to cache the results, or is that pointless?

The actual use case Quarkus for me might need caching in some places, but not everywhere.

[yrodiere]

There are two things to take into account: the entity cache, and the query (results) cache.

Entity cache

Caching entities through any other means than Hibernate ORM's own caching would be dangerous, and should not be done. Entity instances are attached to a Hibernate ORM session, and require specific care before they can be put into or extracted from a cache. FWIW the process is called hydration/dehydration.
Because that process is complex, the only way entities can be cached is in their dedicated region, where the cache key is the entity identifier, and the value is the (dehydrated) entity instance.

You can find most of this information in the docs at https://quarkus.io/guides/hibernate-orm#caching-of-entities and https://docs.jboss.org/hibernate/orm/6.5/userguide/html_single/Hibernate_User_Guide.html#caching-entity

Query cache

Caching query results can get quite technical because of the above: you can't just take the result, serialize it and put it in a cache. That's why in many (all?) cases, query results are cached by storing the identifiers of entities in the results. On cache hit, Hibernate ORM will take the list of identifiers extracted from the cache, and load the corresponding entities -- potentially from the cache, if the entities are cacheable.

Hibernate ORM implements cache invalidation in both cases: when an entity gets writen to, Hibernate ORM invalidates its entry in the entity cache, and any entry in the query cache involving that entity type.
You may have noticed this means entries in the query cache are invalidated way more often than they should be, for safety. That's why the query cache is only useful for entities that get written to rather rarely.

You can find most of this information in the docs at https://quarkus.io/guides/hibernate-orm#caching-of-queries and https://docs.jboss.org/hibernate/orm/6.5/userguide/html_single/Hibernate_User_Guide.html#caching-query

Collection cache

I'm out of time, so see the docs at https://quarkus.io/guides/hibernate-orm#caching-of-collections-and-relations and https://docs.jboss.org/hibernate/orm/6.5/userguide/html_single/Hibernate_User_Guide.html#caching-collection

Summary

To sum up:

1. In order to cache a query, you need to mark it as cacheable somehow. In Panache you'd use PanacheQuery#withHint, e.g. find("name", name).withHint(AvailableHints.CACHEABLE, true).firstResult(). That will result in Hibernate ORM caching the query results, with the cache key being the query string and set of parameter values, and the cache value being the identifiers of entities in the query results.
2. In order to cache entities, you need to annotate your entity type with @Cacheable and optionally configure the cache region, . That will allow Hibernate ORM to quickly retrieve an entity from the cache based on its ID.
3. In order to (fully) cache query results that contain entities, you need to follow both step 1 and 2.
4. Depending on how often instances of your entity type gets written to, you may want to stick with just the entity cache, as the query cache may get invalidated of every write to an instance (any instance) of that entity type.

[gwenneg]

Sorry for the late answer, I'm currently on PTO 😄

I don't think mixing Hibernate ORM caching and quarkus-cache is a good idea as they are completely unrelated, although both may depend on the same caching provider (Caffeine) depending on your quarkus-cache settings. There is no way to modify the data cached by Hibernate ORM in Caffeine through the quarkus-cache extension.

Setting the following property automatically leads to cached entries being removed from the cache 12 hours after they've been written. You don't need to perform any additional manual operation.

quarkus.cache.caffeine.expire-after-write=PT12H

It doesn't look like you need quarkus-cache so it would probably be a good idea to remove it and try to address your caching needs with Hibernate ORM only.

[alecStewart1]

Ah, I see. So when we're talking about using the active record model, there's no additional configuration to cache the results of those functions?

Example: there's a static method in an entity class/function in the companion object that takes 1 argument and returns a list/set of items.
There's nothing we need to configure/call/annotate with that function to make sure it utilize the caching mechanisms provided by Quarkus?