Redis OM logo

Objecting mapping, and more, for Redis.

License Build Status

Redis OM .NET makes it easy to model Redis data in your .NET Applications.

Redis OM .NET | Redis OM Node.js | Redis OM Spring | Redis OM Python

Table of contents

💡 Why Redis OM?

Redis OM provides high-level abstractions for using Redis in .NET, making it easy to model and query your Redis domain objects.

This preview release contains the following features:

  • Declarative object mapping for Redis objects
  • Declarative secondary-index generation
  • Fluent APIs for querying Redis
  • Fluent APIs for performing Redis aggregations

💻 Installation

Using the dotnet cli, run:

dotnet add package Redis.OM

🏁 Getting started

Starting Redis

Before writing any code you'll need a Redis instance with the appropriate Redis modules! The quickest way to get this is with Docker:

docker run -p 6379:6379 redislabs/redismod:preview

📇 Modeling your domain (and indexing it!)

With Redis OM, you can model your data and declare indexes with minimal code. For example, here's how we might model a customer object:

[Document(StorageType = StorageType.Json)]
public class Customer
{
   [Indexed] public string FirstName { get; set; }
   [Indexed] public string LastName { get; set; }
   [Indexed] public string Email { get; set; }
   [Indexed(Sortable = true)] public int Age { get; set; }
}

Notice that we've applied the Document attribute to this class. We've also specified that certain fields should be Indexed.

Now we need to create the Redis index. So we'll connect to Redis and then call CreateIndex on an IRedisConnection:

var provider = new RedisConnectionProvider("redis://localhost:6379");
connection.CreateIndex(typeof(Customer));

Once the index is created, we can:

  • Insert Customer objects into Redis
  • Get a Customer object by ID from Redis
  • Query Customers from Redis
  • Run aggregations on Customers in Redis

Let's see how!

🔎 Querying

We can query our domain using expressions in LINQ, like so:

var customers = provider.RedisCollection<Customer>();
// Find all customers whose last name is "Bond"
customers.Where(x => x.LastName == "Bond");

// Find all customers whose last name is Bond OR whose age is greater than 65
customers.Where(x => x.LastName == "Bond" || x.Age > 65);

// Find all customers whose last name is Bond AND whose first name is James
customers.Where(x => x.LastName == "Bond" && x.FirstName == "James");

🖩 Aggregations

We can also run aggregations on the customer object, again using expressions in LINQ:

// Get our average customer age
customerAggregations.Average(x => x.RecordShell.Age);

// Format customer full names
customerAggregations.Apply(x => string.Format("{0} {1}", x.RecordShell.FirstName, x.RecordShell.LastName),
      "FullName");

// Get each customer's distance from the Mall of America
customerAggregations.Apply(x => ApplyFunctions.GeoDistance(x.RecordShell.Home, -93.241786, 44.853816),
      "DistanceToMall");

⛏️ Troubleshooting

If you run into trouble or have any questions, we're here to help!

First, check the FAQ. If you don't find the answer there, hit us up on the Redis Discord Server.

✨ RediSearch and RedisJSON

Redis OM relies on core features from two source-available Redis modules: RediSearch and RedisJSON.

These modules are the "magic" behind the scenes:

  • RediSearch adds querying, indexing, and full-text search to Redis
  • RedisJSON adds the JSON data type to Redis

Why this is important

Without RediSearch or RedisJSON, you can still use Redis OM to create declarative models backed by Redis.

We'll store your model data in Redis as Hashes, and you can retrieve models using their primary keys.

So, what won't work without these modules?

  1. Without RedisJSON, you won't be able to nest models inside each other.
  2. Without RediSearch, you won't be able to use our expressive queries to find object -- you'll only be able to query by primary key.

So how do you get RediSearch and RedisJSON?

You can use RediSearch and RedisJSON with your self-hosted Redis deployment. Just follow the instructions on installing the binary versions of the modules in their Quick Start Guides:

NOTE: Both quick start guides also have instructions on how to run these modules in Redis with Docker.

Don't want to run Redis yourself? RediSearch and RedisJSON are also available on Redis Cloud. Get started here.

❤️ Contributing

We'd love your contributions!

Bug reports are especially helpful at this stage of the project. You can open a bug report on GitHub.

You can also contribute documentation -- or just let us know if something needs more detail. Open an issue on GitHub to get started.