Redis OM

Objecting mapping, and more, for Redis.

---

Redis OM Python makes it easy to model Redis data in your Python applications.

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

Table of contents

• 💡 Why Redis OM?
• Starting Redis
• 📇 Modeling your domain (and indexing it!)
• 🔎 Querying
• Why this is important
• So how do you get RediSearch and RedisJSON?
• Why Redis OM?
• Getting started
• Installation
• Documentation
• Troubleshooting
• Contributing
• License

💡 Why Redis OM?

Redis OM provides high-level abstractions for using Redis in Python, 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

🏁 Getting started

Object Mapping

With Redis OM, you get powerful data modeling, extensible data validation with Pydantic, and rich query expressions.

Check out this example of how we'd model customer data with Redis OM. First, we create a Customer model:

import datetime
from typing import Optional

from pydantic import EmailStr

from redis_om.model import (
    HashModel,
)


class Customer(HashModel):
    first_name: str
    last_name: str
    email: EmailStr
    join_date: datetime.date
    age: int
    bio: Optional[str]

NOTE: Redis OM uses Python type annotations for data validation. See the Data Validation section of this README for more details.

Now that we have a Customer model, let's use it to save customer data to Redis.

First, we create a new Customer object:

andrew = Customer(
    first_name="Andrew",
    last_name="Brookins",
    email="andrew.brookins@example.com",
    join_date=datetime.date.today(),
    age=38,
    bio="Python developer, works at Redis, Inc."
)

The model generates a globally unique primary key automatically without needing to talk to Redis.

print(andrew.pk)
'01FJM6PH661HCNNRC884H6K30C'

We can save the model to Redis by calling save():

andrew.save()

To retrieve this customer with its primary key, we use Customer.get():

other_andrew = Customer.get('01FJM6PH661HCNNRC884H6K30C')

Ready to learn more? Check out the getting started guide.

Or, continue reading to see how Redis OM makes data validation a snap.

Data Validation

Redis OM uses Pydantic to validate data based on the type annotations you assign to fields in a model class.

This validation ensures that fields like first_name, which the Customer model marked as a str, are always string. But every Redis OM model is also a Pydantic model, so you can use Pydantic validators like EmailStr, Pattern, and many more for complex validation!

As an example, because we used the EmailStr validator, we'll get a validation error if we try to save a Customer with an invalid email address:

Customer(
    first_name="Andrew",
    last_name="Brookins",
    email="Not an email address!",
    join_date=datetime.date.today(),
    age=38,
    bio="Python developer, works at Redis, Inc."
)

This code generates a validation error:

 Traceback:
 pydantic.error_wrappers.ValidationError: 1 validation error for Customer
 email
   value is not a valid email address (type=value_error.email)

What's great about this is any existing Pydantic validator should work as a drop-in type annotation with a Redis OM model. You can also write arbitrarily complex custom validations!

To learn more, see the documentation on data validation.

Rich Queries and Embedded Models

Data modeling, validation, and saving models to Redis all work regardless of how you run Redis.

Next, we'll show you the rich query expressions and embedded models Redis OM provides when the RediSearch and RedisJSON modules are installed in your Redis deployment.

TIP: Wait, what's a Redis module? If you aren't familiar with Redis modules, review the "RediSearch and RedisJSON" section of this README.

Querying

Let's make a small change to the Customer model we defined earlier to let Redis OM know that we want to query using the last_name and age fields:

class Customer(HashModel):
    first_name: str
    last_name: str = Field(index=True)
    email: EmailStr
    join_date: datetime.date
    age: int = Field(index=True)
    bio: Optional[str]

Now, if we use this model with a Redis deployment that has the RediSearch module installed, we can run queries like the following:

# Find all customers with the last name "Brookins"
Customer.find(Customer.last_name == "Brookins").all()

# Find all customers that do NOT have the last name "Brookins"
Customer.find(Customer.last_name != "Brookins").all()
 
# Find all customers whose last name is "Brookins" OR whose age is 
# 100 AND whose last name is "Smith"
Customer.find((Customer.last_name == "Brookins") | (
    Customer.age == 100
) & (Customer.last_name == "Smith")).all()

These queries -- and more! -- are possible because Redis OM manages indexes for you automatically.

Querying with this index features a rich expression syntax inspired by the Django ORM, SQLAlchemy, and Peewee. We think you'll enjoy it!

To see more example queries, see the documentation on querying.

Embedded Models

Redis OM can store and query nested models like any document database, with the speed and power you get from Redis. Let's see how this works.

In the next example, we'll define a new Address model and embed it within the Customer model.

import datetime
from typing import Optional

from redis_om.model import (
    EmbeddedJsonModel,
    JsonModel,
    Field,
)

class Address(EmbeddedJsonModel):
    address_line_1: str
    address_line_2: Optional[str]
    city: str = Field(index=True)
    state: str = Field(index=True)
    country: str
    postal_code: str = Field(index=True)


class Customer(JsonModel):
    first_name: str = Field(index=True)
    last_name: str = Field(index=True)
    email: str = Field(index=True)
    join_date: datetime.date
    age: int = Field(index=True)
    bio: Optional[str] = Field(index=True, full_text_search=True,
                               default="")

    # Creates an embedded model.
    address: Address

With these two models and a Redis deployment with the RedisJSON module installed, we can run queries like the following:

# Find all customers who live in San Antonio, TX
Customer.find(Customer.address.city == "San Antonio",
              Customer.address.state == "TX")

To learn more, read the documentation on embedded models.

💻 Installation

Installation is simple with pip, Poetry, or Pipenv.

# With pip
$ pip install redis-om

# Or, using Poetry
$ poetry add redis-om

📚 Documentation

The Redis OM documentation is available here.

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

Some advanced features of Redis OM rely on core features from two source available Redis modules: RediSearch and RedisJSON.

You can run these modules in your self-hosted Redis deployment, or you can use Redis Enterprise, which includes both modules.

To learn more, read our documentation.

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

License

Redis OM uses the BSD 3-Clause license.