Redis.OM 0.1.7

There is a newer version of this package available.
See the version list below for details.
dotnet add package Redis.OM --version 0.1.7                
NuGet\Install-Package Redis.OM -Version 0.1.7                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Redis.OM" Version="0.1.7" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Redis.OM --version 0.1.7                
#r "nuget: Redis.OM, 0.1.7"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Redis.OM as a Cake Addin
#addin nuget:?package=Redis.OM&version=0.1.7

// Install Redis.OM as a Cake Tool
#tool nuget:?package=Redis.OM&version=0.1.7                

<div align="center"> <br/> <br/> <img width="360" src="images/logo.svg" alt="Redis OM" /> <br/> <br/> </div>

<p align="center"> <p align="center"> Object mapping, and more, for Redis and .NET </p> </p>


NuGet 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

<details> <summary><strong>Table of contents</strong></summary>

</details>

💡 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]
public class Customer
{
   [Indexed(Sortable = true)] public string FirstName { get; set; }
   [Indexed(Aggregatable = true)] public string LastName { get; set; }
   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");
provider.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!

🔑 Keys and Ids

ULIDs and strings

Ids are unique per object, and are used as part of key generation for the primary index in Redis. The natively supported Id type in Redis OM is the ULID. You can bind ids to your model, by explicitly decorating your Id field with the RedisIdField attribute:

[Document]
public class Customer
{
    [RedisIdField] public Ulid Id { get; set; }
    [Indexed(Sortable = true)] public string FirstName { get; set; }
    [Indexed(Aggregatable = true)] public string LastName { get; set; }
    public string Email { get; set; }
    [Indexed(Sortable = true)] public int Age { get; set; }
}

When you call Set on the RedisConnection or call Insert in the RedisCollection, to insert your object into Redis, Redis OM will automatically set the id for you and you will be able to access it in the object. If the Id type is a string, and there is no explicitly overriding IdGenerationStrategy on the object, the ULID for the object will bind to the string.

Other types of ids

Redis OM also supports other types of ids, ids must either be strings or value types (e.g. ints, longs, GUIDs etc. . .), if you want a non-ULID id type, you must either set the id on each object prior to insertion, or you must register an IIdGenerationStrategy with the DocumentAttribute class.

Register IIdGenerationStrategy

To Register an IIdGenerationStrategy with the DocumentAttribute class, simply call DocumentAttribute.RegisterIdGenerationStrategy passing in the strategy name, and the implementation of IIdGenerationStrategy you want to use. Let's say for example you had the StaticIncrementStrategy, which maintains a static counter in memory, and increments ids based off that counter:

public class StaticIncrementStrategy : IIdGenerationStrategy
{
    public static int Current = 0;
    public string GenerateId()
    {
        return (Current++).ToString();
    }
}

You would then register that strategy with Redis.OM like so:

DocumentAttribute.RegisterIdGenerationStrategy(nameof(StaticIncrementStrategy), new StaticIncrementStrategy());

Then, when you want to use that strategy for generating the Ids of a document, you can simply set the IdGenerationStrategy of your document attribute to the name of the strategy.

[Document(IdGenerationStrategyName = nameof(StaticIncrementStrategy))]
public class ObjectWithCustomIdGenerationStrategy
{
    [RedisIdField] public string Id { get; set; }
}
Key Names

The key names are, by default, the fully qualified class name of the object, followed by a colon, followed by the Id. For example, there is a Person class in the Unit Test project, an example id of that person class would be Redis.OM.Unit.Tests.RediSearchTests.Person:01FTHAF0D1EKSN0XG67HYG36GZ, because Redis.OM.Unit.Tests.RediSearchTests.Person is the fully qualified class name, and 01FTHAF0D1EKSN0XG67HYG36GZ is the ULID (the default id type). If you want to change the prefix (the fully qualified class name), you can change that in the DocumentAttribute by setting the Prefixes property, which is an array of strings e.g.

[Document(Prefixes = new []{"Person"})]
public class Person

Note: At this time, Redis.OM will only use the first prefix in the prefix list as the prefix when creating a key name. However, when an index is created, it will be created on all prefixes enumerated in the Prefixes property

🔎 Querying

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

var customers = provider.RedisCollection<Customer>();

// Insert customer
customers.Insert(new Customer()
{
    FirstName = "James",
    LastName = "Bond",
    Age = 68,
    Email = "[email protected]"
});

// 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");

📚 Documentation

This README just scratches the surface. You can find a full tutorial on the Redis Developer Site. All the summary docs for this library can be found on the repo's github page.

⛏️ 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.

✨ RedisJSON

Redis OM can be used with regular Redis for Object mapping and getting objects by their IDs. For more advanced features like indexing, querying, and aggregation, Redis OM is dependeant on the Source Available RedisJSON module.

Why this is important

Without 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. You won't be able to nest models inside each other.
  2. 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 RedisJSON?

You can use RedisJSON with your self-hosted Redis deployment. Just follow the instructions on installing the binary version of the module in its Quick Start Guides.

NOTE: The quick start guide has instructions on how to run the module in Redis with Docker.

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

❤️ Contributing

We'd love your contributions! If you want to contribute please read our Contributing document.

❤️ Our Contributors

  • @slorello89
  • @banker
  • @simonprickett
  • @BenShapira
  • @satish860
  • @dracco1993
  • @ecortese
  • @DanJRWalsh
  • @baldutech
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (15)

Showing the top 5 NuGet packages that depend on Redis.OM:

Package Downloads
ShayganTadbir.Framework.Core

Package description

FCMicroservices

a boilerplate microservice framework

BSN.Commons

Commons library for enterprise application

Redis.OM.Vectorizers.AllMiniLML6V2

Sentence Vectorizer for Redis OM .NET using all-MiniLM-L6-v2

Dofus.Framework

Package Description

GitHub repositories (4)

Showing the top 4 popular GitHub repositories that depend on Redis.OM:

Repository Stars
eventflow/EventFlow
Async/await first CQRS+ES and DDD framework for .NET
redis/redis-om-dotnet
Object mapping, and more, for Redis and .NET
LBPUnion/ProjectLighthouse
Project Lighthouse is a clean-room, open-source custom server for LittleBigPlanet.
SapiensAnatis/Dawnshard
Server emulator for Dragalia Lost
Version Downloads Last updated
0.7.6 3,221 10/28/2024
0.7.5 9,011 10/4/2024
0.7.4 30,650 7/15/2024
0.7.3 3,252 7/12/2024
0.7.2 874 7/11/2024
0.7.1 50,860 5/2/2024
0.7.0 25,395 4/12/2024
0.6.1 117,256 12/6/2023
0.6.0 11,070 12/5/2023
0.5.5 5,552 11/27/2023
0.5.4 33,989 10/26/2023
0.5.3 101,266 8/16/2023
0.5.2 89,749 5/16/2023
0.5.1 10,893 5/3/2023
0.5.0 8,000 4/14/2023
0.4.2 73,701 3/14/2023
0.4.1 47,878 1/13/2023
0.4.0 31,122 12/12/2022
0.3.1 54,177 10/13/2022
0.3.0 1,212 10/11/2022
0.2.3 72,066 9/19/2022
0.2.1 70,794 7/19/2022
0.2.0 5,096 7/5/2022
0.1.9 38,927 4/1/2022
0.1.8 4,238 3/1/2022
0.1.7 1,178 2/9/2022
0.1.6 1,770 2/4/2022
0.1.5 515 1/31/2022
0.1.4 1,783 12/13/2021
0.1.3 713 12/7/2021
0.1.2 371 11/29/2021
0.1.1 6,221 11/24/2021
0.1.0 398 11/18/2021