Video
Introducing the Redis OM Client Libraries
Learn more
Become a Redis expert.
See what's new in Redis University
share
Redis is an awesome technology loved by millions of developers for two reasons: speed and simplicity. Redis provides an intuitive native interface logically organized into data structures that programmers already know. Moreover, those structures are simple to use and terrifically optimized. It’s this ultimate blend of speed and simplicity that we are angling at with the release of a new client library for .NET, Redis OM.
Redis OM is object mapping and more for Redis. The motivation behind Redis OM is to answer the question “How can developers get amazing leverage out of Redis without learning all the Redis commands?” For this first preview release, we’re looking to address the question, “How can we store and find our domain objects in Redis?” The preview release of Redis OM .NET is an object mapper, a secondary index builder, and a simplified and powerful query builder. All of this is geared towards helping you store and find your domain objects with Redis.
The Module API has been a game changer for Redis. The modules add a tremendous amount of flexibility to the platform while providing some essential features for Redis. RedisJSON, in particular, unlocks an enormous amount of functionality, particularly around secondary indexing and document modeling. While Redis OM works well with core Redis, Redis OM really hits its stride when you add RedisJSON, taking full advantage of RedisJSON to create a rich and powerful API for modeling objects and querying them in Redis.
The preview version of Redis OM .NET has four primary capabilities:
Before getting up and running with Redis OM, you need to install the package in your project. To do so, just run dotnet add package Redis.OM. The primary connection logic within the Redis OM library exists in the RedisConnectionProvider. This provider gives access to three different objects you can use to communicate with Redis:
To connect Redis OM to Redis in ASP.NET Core, you should inject an instance of the RedisConnectionProvider instance as a singleton. To do this, you’ll use a Redis URI. If you’re using .NET 6, this means opening your program.cs file and adding:
builder.Services.AddSingleton(new RedisConnectionProvider("redis://localhost:6379"));
For .NET 5, which uses the Startup.cs file, you can add the following to Startup.ConfigureServices:
services.AddSingleton(new RedisConnectionProvider("redis://localhost:6379"));
RedisJSON lets you store JSON objects in Redis natively and query those objects. But to query your JSON, you need to first define your indexes. To make this process easier, we’ve introduced a declarative model in Redis OM .NET to allow you to define these indexes through a declarative interface. If you want to declare a class to store in Redis and index its properties, you decorate the class with a Document attribute and then dress the individual properties with the Indexed or the Searchable attributes. Indexed implies a standard index, whereas Searchable applies only to strings and means that the property will be queryable with full-text search. Next, you can create the index in Redis by passing your newly decorated type into the IRedisConnection.CreateIndex method. So, for example, if you wanted to declare a Customer class with an index, you would do something like the following:
// declare index
[Document(StorageType = StorageType.Json)]
public class Customer
{
[Indexed]
public string FirstName { get; set; }
[Searchable(Aggregatable=true)]
public string LastName { get; set; }
[Searchable(Aggregatable=true)]
public string PersonalStatement { get; set; }
[Indexed(Aggregatable=true)]
public int Age { get; set; }
}
// create index
connection.CreateIndex(typeof(Customer));
With an index created, you can now use RedisCollection<T> to query objects in Redis. So, if you had John stored in Redis as a Customer object, you can then query him:
var customers = provider.RedisCollection<Customer>();
var john = customers.First(x => x.FirstName == "John");
You can also easily do range queries. For example, let’s find all the Customers who have not reached retirement age:
var customersNotOldEnoughToRetire = customers.Where(x => x.Age < 65);
With the RedisCollection and RedisJSON, you can build rich and complex queries as you ordinarily would in LINQ, and Redis OM will manage the translation to Redis’ query language for you.
In addition to querying, you can use Redis Aggregations to build aggregation pipelines that can do all sorts of things. For example, suppose you want to find the age of each customer in 3 years, you can do so with a straightforward arithmetic operation inside an Apply expression, which will translate to a properly formatted aggregation pipeline in Redis:
var customerAggregations = provider.AggregationSet<Customer>();
customerAggregations.Apply(x =>x.RecordShell.Age + 3,
"AgeInThreeYears");
You can also group records together and calculate summary statistics on them. So if you want to group customers by their last name, you can then calculate summary statistics. For example, here’s how you can calculate average age:
var averageAgeOfFamilies = customerAggregations.GroupBy(x=> x.RecordShell.LastName).Average(x=>x.RecordShell.Age);
This is just a brief overview of the capabilities of Redis OM for .NET. If you want to learn more, you can check out the tutorial and look through the API docs. We plan on adding more features to Redis.OM soon, and, to that end, we would love some community feedback. Come and try it out. If you find a problem or think of something you’d like to see added to the library, open an issue in GitHub. And naturally, we always love contributions from the community, so PRs are always welcome :).
