Usage

Spring Data Valkey lets you easily implement domain entities, as shown in the following example:

Example 1. Sample Person Entity

@ValkeyHash("people")
public class Person {

  @Id String id;
  String firstname;
  String lastname;
  Address address;
}

We have a pretty simple domain object here. Note that it has a @ValkeyHash annotation on its type and a property named id that is annotated with org.springframework.data.annotation.Id. Those two items are responsible for creating the actual key used to persist the hash.

To now actually have a component responsible for storage and retrieval, we need to define a repository interface, as shown in the following example:

Example 2. Basic Repository Interface To Persist Person Entities

public interface PersonRepository extends CrudRepository<Person, String> {

}

As our repository extends CrudRepository, it provides basic CRUD and finder operations. The thing we need in between to glue things together is the corresponding Spring configuration, shown in the following example:

Example 3. JavaConfig for Valkey Repositories

@Configuration
@EnableValkeyRepositories
public class ApplicationConfig {

  @Bean
  public ValkeyConnectionFactory connectionFactory() {
    return new ValkeyGlideConnectionFactory();
  }

  @Bean
  public ValkeyTemplate<?, ?> valkeyTemplate(ValkeyConnectionFactory valkeyConnectionFactory) {

    ValkeyTemplate<byte[], byte[]> template = new ValkeyTemplate<byte[], byte[]>();
    template.setConnectionFactory(valkeyConnectionFactory);
    return template;
  }
}

Given the preceding setup, we can inject PersonRepository into our components, as shown in the following example:

Example 4. Access to Person Entities

@Autowired PersonRepository repo;

public void basicCrudOperations() {

  Person rand = new Person("rand", "al'thor");
  rand.setAddress(new Address("emond's field", "andor"));

  repo.save(rand);                                         // (1)

  repo.findOne(rand.getId());                              // (2)

  repo.count();                                            // (3)

  repo.delete(rand);                                       // (4)
}

1. Generates a new `id` if the current value is `null` or reuses an already set `id` value and stores properties of type `Person` inside the Valkey Hash with a key that has a pattern of `keyspace:id` -- in this case, it might be `people:5d67b7e1-8640-2025-beeb-c666fab4c0e5`.
2. Uses the provided `id` to retrieve the object stored at `keyspace:id`.
3. Counts the total number of entities available within the keyspace, `people`, defined by `@ValkeyHash` on `Person`.
4. Removes the key for the given object from Valkey.

Persisting References

Marking properties with @Reference allows storing a simple key reference instead of copying values into the hash itself. On loading from Valkey, references are resolved automatically and mapped back into the object, as shown in the following example:

Example 5. Sample Property Reference

_class = org.example.Person
id = e2c7dcee-b8cd-4424-883e-736ce564363e
firstname = rand
lastname = al'thor
mother = people:a9d4b3a0-50d3-4538-a2fc-f7fc2581ee56      // (1)

1. Reference stores the whole key (`keyspace:id`) of the referenced object.

Persisting Partial Updates

In some cases, you need not load and rewrite the entire entity just to set a new value within it. A session timestamp for the last active time might be such a scenario where you want to alter one property. PartialUpdate lets you define set and delete actions on existing objects while taking care of updating potential expiration times of both the entity itself and index structures. The following example shows a partial update:

Example 6. Sample Partial Update

PartialUpdate<Person> update = new PartialUpdate<Person>("e2c7dcee", Person.class)
  .set("firstname", "mat")                                                           // (1)
  .set("address.city", "emond's field")                                              // (2)
  .del("age");                                                                       // (3)

template.update(update);

update = new PartialUpdate<Person>("e2c7dcee", Person.class)
  .set("address", new Address("caemlyn", "andor"))                                   // (4)
  .set("attributes", singletonMap("eye-color", "grey"));                             // (5)

template.update(update);

update = new PartialUpdate<Person>("e2c7dcee", Person.class)
  .refreshTtl(true);                                                                 // (6)
  .set("expiration", 1000);

template.update(update);

1. Set the simple `firstname` property to `mat`.
2. Set the simple 'address.city' property to 'emond's field' without having to pass in the entire object.
This does not work when a custom conversion is registered.
3. Remove the `age` property.
4. Set complex `address` property.
5. Set a map of values, which removes the previously existing map and replaces the values with the given ones.
6. Automatically update the server expiration time when altering [Time To Live](/valkey/valkey-repositories/expirations).