redis-om-type implements schemas, repositories, and fluent search over Redis. It follows the same model as Redis OM for Node.js, with TypeScript declarations and tooling for Node.js applications.

Related Redis OM clients: Redis OM .NET · Redis OM Node.js (upstream) · Redis OM Python · Redis OM Spring

• Overview
• Getting Started
• Connect to Redis with Node Redis
  • Redis Connection Strings
• Entities and Schemas
  • JSON and Hashes
    • Configuring JSON
    • Configuring Hashes
• Reading, Writing, and Removing with Repository
  • Creating Entities
  • Missing Entities and Null Values
• Searching
  • Build the Index
  • Finding All The Things (and Returning Them)
    • Pagination
    • First Things First
    • Counting
  • Finding Specific Things
    • Searching on Strings
    • Searching on Numbers
    • Searching on Booleans
    • Searching on Dates
    • Searching String Arrays
    • Searching Arrays of Numbers
    • Full-Text Search
    • Searching on Points
    • Chaining Searches
    • Running Raw Searches
  • Sorting Search Results
• Advanced usage
  • Schema Options
• Documentation
• Troubleshooting
• Contributing

Overview

Redis OM (often pronounced “redis-ohm”) maps Redis data to plain JavaScript objects so you can persist and query entities without hand-writing low-level commands. The API is fluent and composable, with strong TypeScript support in this package.

Define a schema:

const schema = new Schema('album', {
  artist: { type: 'string' },
  title: { type: 'text' },
  year: { type: 'number' }
})

Create a JavaScript object and save it:

const album = {
  artist: "Mushroomhead",
  title: "The Righteous & The Butterfly",
  year: 2014
}

await repository.save(album)

Search for matching entities:

const albums = await repository.search()
  .where('artist').equals('Mushroomhead')
  .and('title').matches('butterfly')
  .and('year').is.greaterThan(2000)
    .return.all()

The sections below describe schemas, repositories, and search in full.

Migrating from Redis OM 0.3.x

Version 0.4 introduced breaking changes relative to 0.3.6. If you are new to this API, follow this README from top to bottom.

If you already use redis-om on npm, read this document and CHANGELOG before upgrading. The redis-om 0.3.6 README remains available for comparison. Later 0.4.x releases add requested improvements; further non-breaking changes are expected.

Getting Started

Create or use an existing Node.js project (for example npm init).

Install this package and the Redis client:

npm install redis-om-type redis

Use Redis Stack (includes RediSearch and RedisJSON) or Redis Cloud. With Docker:

docker run -d --name redis-stack -p 6379:6379 -p 8001:8001 redis/redis-stack:latest

Connect to Redis with Node Redis

Before using redis-om-type, connect to Redis with Node Redis. Minimal setup (from the Node Redis README):

import { createClient } from 'redis'

const redis = createClient()
redis.on('error', (err) => console.log('Redis Client Error', err));
await redis.connect()

For advanced connection options, clustering, and tuning, see the Node Redis documentation.

With a connected client you can run ordinary Redis commands when needed:

const aString = await redis.ping() // 'PONG'
const aNumber = await redis.hSet('foo', 'alfa', '42', 'bravo', '23') // 2
const aHash = await redis.hGetAll('foo') // { alfa: '42', bravo: '23' }

When you are finished with a connection, close it with .quit:

await redis.quit()

Redis Connection Strings

By default, Node Redis connects to localhost:6379. Override this with a URL:

const redis = createClient({ url: 'redis://alice:[email protected]:6380' })

The basic format for this URL is:

redis://username:password@host:port

The full URI scheme is registered with IANA; TLS uses rediss://.

For sockets, clustering, and other options, see the Node Redis client configuration and clustering guides.

Entities and Schemas

This library is concerned with saving, reading, and deleting entities. An Entity is plain JavaScript object data you persist or load from Redis. Almost any object shape can serve as an Entity.

Schemas declare which fields an entity may have: each field’s type, how it is stored in Redis, and how it participates in RediSearch when indexing is enabled. By default, entities are stored as JSON (RedisJSON); you can opt into Redis Hashes instead (see below).

Define a Schema as follows:

import { Schema } from 'redis-om-type'

const albumSchema = new Schema('album', {
  artist: { type: 'string' },
  title: { type: 'text' },
  year: { type: 'number' },
  genres: { type: 'string[]' },
  songDurations: { type: 'number[]' },
  outOfPublication: { type: 'boolean' }
})

const studioSchema = new Schema('studio', {
  name: { type: 'string' },
  city: { type: 'string' },
  state: { type: 'string' },
  location: { type: 'point' },
  established: { type: 'date' }
})

The first argument is the schema name. It becomes part of the Redis key prefix for entities using this schema. Choose a name that is unique on your Redis instance and meaningful to your domain (here, album and studio).

The second argument lists fields that may appear on entities. Object keys are the names you use in queries; each field’s type must be one of: string, number, boolean, string[], number[], date, point, or text.

The first three types do exactly what you think—they define a field that is a String, a Number, or a Boolean. string[] and number[] do what you'd think as well, specifically describing an Array of Strings or Numbers respectively.

date is a little different, but still more or less what you'd expect. It describes a property that contains a Date and can be set using not only a Date but also a String containing an ISO 8601 date or a number with the UNIX epoch time in seconds (NOTE: the JavaScript Date object is specified in milliseconds).

A point defines a point somewhere on the globe as a longitude and a latitude. It is expressed as a simple object with longitude and latitude properties. Like this:

const point = { longitude: 12.34, latitude: 56.78 }

A text field behaves like a string for plain read and write operations. For search, the two diverge: string fields support exact and tag-style matching (good for codes and identifiers), while text fields use RediSearch full-text indexing (stemming, stop words, and related features). See Searching.

JSON and Hashes

By default, entities are stored as JSON documents (RedisJSON). You can set this explicitly:

const albumSchema = new Schema('album', {
  artist: { type: 'string' },
  title: { type: 'string' },
  year: { type: 'number' },
  genres: { type: 'string[]' },
  songDurations: { type: 'number[]' },
  outOfPublication: { type: 'boolean' }
}, {
  dataStructure: 'JSON'
})

To store entities as Redis Hashes, set dataStructure to 'HASH':

const albumSchema = new Schema('album', {
  artist: { type: 'string' },
  title: { type: 'string' },
  year: { type: 'number' },
  genres: { type: 'string[]' },
  outOfPublication: { type: 'boolean' }
}, {
  dataStructure: 'HASH'
})

Hashes and JSON differ: hashes are flat field/value maps; JSON documents are trees and may be nested. That affects how you configure paths and fields.

Hash-backed schemas cannot use number[]; that type is JSON-only. Omit it from hash schemas or use JSON.

Configuring JSON

When you store your entities as JSON, the path to the properties in your JSON document and your JavaScript object default to the name of your property in the schema. In the above example, this would result in a document that looks like this:

{
  "artist": "Mushroomhead",
  "title": "The Righteous & The Butterfly",
  "year": 2014,
  "genres": [ "metal" ],
  "songDurations": [ 204, 290, 196, 210, 211, 105, 244, 245, 209, 252, 259, 200, 215, 219 ],
  "outOfPublication": true
}

However, you might not want your JavaScript object and your JSON to map this way. So, you can provide a path option in your schema that contains a JSONPath pointing to where that field actually exists in the JSON and your entity. For example, we might want to store some of the album's data inside of an album property like this:

{
  "album": {
    "artist": "Mushroomhead",
    "title": "The Righteous & The Butterfly",
    "year": 2014,
    "genres": [ "metal" ],
    "songDurations": [ 204, 290, 196, 210, 211, 105, 244, 245, 209, 252, 259, 200, 215, 219 ]
  },
  "outOfPublication": true
}

To do this, we'll need to specify the path property for the nested fields in the schema:

const albumSchema = new Schema('album', {
  artist: { type: 'string', path: '$.album.artist' },
  title: { type: 'string', path: '$.album.title' },
  year: { type: 'number', path: '$.album.year' },
  genres: { type: 'string[]', path: '$.album.genres[*]' },
  songDurations: { type: 'number[]', path: '$.album.songDurations[*]' },
  outOfPublication: { type: 'boolean' }
})

There are two things to note here:

1. We haven't specified a path for outOfPublication as it's still in the root of the document. It defaults to $.outOfPublication.
2. Our genres field points to a string[]. When using a string[] the JSONPath must return an array. If it doesn't, an error will be generated.
3. Same for our songDurations.

Configuring Hashes

When you store your entities as Hashes there is no nesting—all the entities are flat. In Redis, the properties on your entity are stored in fields inside a Hash. The default name for each field is the name of the property in your schema and this is the name that will be used in your entities. So, for the following schema:

const albumSchema = new Schema('album', {
  artist: { type: 'string' },
  title: { type: 'string' },
  year: { type: 'number' },
  genres: { type: 'string[]' },
  outOfPublication: { type: 'boolean' }
}, {
  dataStructure: 'HASH'
})

In your code, your entities would look like this:

{
  artist: 'Mushroomhead',
  title: 'The Righteous & The Butterfly',
  year: 2014,
  genres: [ 'metal' ],
  outOfPublication: true
}

Inside Redis, your Hash would be stored like this:

| Field | Value | |------------------|:----------------------------------------| | artist | Mushroomhead | | title | The Righteous & The Butterfly | | year | 2014 | | genres | metal | | outOfPublication | 1 |

However, you might not want the names of your fields and the names of the properties on your entity to be exactly the same. Maybe you've got some existing data with existing names or something.

Fear not! You can change the name of the field used by Redis with the field property:

const albumSchema = new Schema('album', {
  artist: { type: 'string', field: 'album_artist' },
  title: { type: 'string', field: 'album_title' },
  year: { type: 'number', field: 'album_year' },
  genres: { type: 'string[]' },
  outOfPublication: { type: 'boolean' }
}, {
  dataStructure: 'HASH'
})

With this configuration, your entities will remain unchanged and will still have properties for artist, title, year, genres, and outOfPublication. But inside Redis, the field will have changed:

| Field | Value | |------------------|:----------------------------------------| | album_artist | Mushroomhead | | album_title | The Righteous & The Butterfly | | album_year | 2014 | | genres | metal | | outOfPublication | 1 |

Reading, Writing, and Removing with Repository

Given a connected Redis client and a schema, create a repository to create, read, update, delete, and search entities:

import { Repository } from 'redis-om-type'

const albumRepository = new Repository(albumSchema, redis)
const studioRepository = new Repository(studioSchema, redis)

Call .save to persist entities:

let album = {
  artist: "Mushroomhead",
  title: "The Righteous & The Butterfly",
  year: 2014,
  genres: [ 'metal' ],
  songDurations: [ 204, 290, 196, 210, 211, 105, 244, 245, 209, 252, 259, 200, 215, 219 ],
  outOfPublication: true
}

album = await albumRepository.save(album)

.save returns the persisted entity, including a generated entity ID. The ID is not a normal string property (to avoid collisions with your own fields); it is exposed through a Symbol. Import EntityId from redis-om-type and read the ID with entity[EntityId]:

import { EntityId } from 'redis-om-type'

album = await albumRepository.save(album)
album[EntityId] // '01FJYWEYRHYFT8YTEGQBABJ43J'

Generated IDs are ULIDs. To use your own ID, pass it as the first argument to .save:

album = await albumRepository.save('BWOMP', album)

Load an entity by ID with .fetch:

const album = await albumRepository.fetch('01FJYWEYRHYFT8YTEGQBABJ43J')
album.artist // "Mushroomhead"
album.title // "The Righteous & The Butterfly"
album.year // 2014
album.genres // [ 'metal' ]
album.songDurations // [ 204, 290, 196, 210, 211, 105, 244, 245, 209, 252, 259, 200, 215, 219 ]
album.outOfPublication // true

If the entity already has an ID (for example after a .fetch), .save updates the existing record:

let album = await albumRepository.fetch('01FJYWEYRHYFT8YTEGQBABJ43J')
album.genres = [ 'metal', 'nu metal', 'avantgarde' ]
album.outOfPublication = false

album = await albumRepository.save(album)

To copy data to a new ID, call .save with a new entity ID as the first argument:

const album = await albumRepository.fetch('01FJYWEYRHYFT8YTEGQBABJ43J')
album.genres = [ 'metal', 'nu metal', 'avantgarde' ]
album.outOfPublication = false

const clonedEntity = await albumRepository.save('BWOMP', album)

Delete entities with .remove:

await albumRepository.remove('01FJYWEYRHYFT8YTEGQBABJ43J')

Set a TTL in seconds with .expire (Redis removes the key when it elapses):

const ttlInSeconds = 12 * 60 * 60  // 12 hours
await albumRepository.expire('01FJYWEYRHYFT8YTEGQBABJ43J', ttlInSeconds)

Missing Entities and Null Values

Redis (and this library) do not fully distinguish “missing field” from “null,” especially for hashes. Fetching a non-existent key still yields an object whose fields are empty and whose [EntityId] is the ID you requested:

const album = await albumRepository.fetch('TOTALLY_BOGUS')
album[EntityId] // 'TOTALLY_BOGUS'
album.artist // undefined
album.title // undefined
album.year // undefined
album.genres // undefined
album.outOfPublication // undefined

If you strip all schema fields and save, the key may be removed from Redis:

const album = await albumRepository.fetch('01FJYWEYRHYFT8YTEGQBABJ43J')
delete album.artist
delete album.title
delete album.year
delete album.genres
delete album.outOfPublication

const entityId = await albumRepository.save(album)

const exists = await redis.exists('album:01FJYWEYRHYFT8YTEGQBABJ43J') // 0

Because of that, .fetch always returns an object shape; treat empty fields as “no data” for that ID.

Searching

With RediSearch available on your server, repositories support indexed search—for example:

const albums = await albumRepository.search()
  .where('artist').equals('Mushroomhead')
  .and('title').matches('butterfly')
  .and('year').is.greaterThan(2000)
    .return.all()

Build the Index

Search requires a RediSearch index. Create (or update) it with .createIndex on the repository:

await albumRepository.createIndex();

After schema changes, call .createIndex again; the library rebuilds the index only when the schema definition changes, so it is safe to invoke during application startup.

Rebuilding can be slow on large datasets—plan that in deployment scripts if needed. To drop an index without immediately rebuilding, use .dropIndex:

await albumRepository.dropIndex();

Finding All The Things (and Returning Them)

Return every entity matching the (possibly empty) query:

const albums = await albumRepository.search().return.all()

Pagination

Request a slice with a zero-based offset and page size:

const offset = 100
const count = 25
const albums = await albumRepository.search().return.page(offset, count)

If the offset is past the end of the result set, you get an empty array.

First Things First

Return the first match, or null if none:

const firstAlbum = await albumRepository.search().return.first();

Counting

Return the number of matches without loading documents:

const count = await albumRepository.search().return.count()

Finding Specific Things

Narrow results using strings, numbers, booleans, string arrays, numeric arrays, full-text, dates, and geo radius. The fluent API offers several equivalent phrasings for the same predicate; the sections below list common patterns.

Searching on Strings

When you set the field type in your schema to string, you can search for a particular value in that string. You can also search for partial strings (no shorter than two characters) that occur at the beginning, middle, or end of a string. If you need to search strings in a more sophisticated manner, you'll want to look at the text type and search it using the Full-Text Search syntax.

let albums

// find all albums where the artist is 'Mushroomhead'
albums = await albumRepository.search().where('artist').eq('Mushroomhead').return.all()

// find all albums where the artist is *not* 'Mushroomhead'
albums = await albumRepository.search().where('artist').not.eq('Mushroomhead').return.all()

// find all albums using wildcards
albums = await albumRepository.search().where('artist').eq('Mush*').return.all()
albums = await albumRepository.search().where('artist').eq('*head').return.all()
albums = await albumRepository.search().where('artist').eq('*room*').return.all()

// fluent alternatives that do the same thing
albums = await albumRepository.search().where('artist').equals('Mushroomhead').return.all()
albums = await albumRepository.search().where('artist').does.equal('Mushroomhead').return.all()
albums = await albumRepository.search().where('artist').is.equalTo('Mushroomhead').return.all()
albums = await albumRepository.search().where('artist').does.not.equal('Mushroomhead').return.all()
albums = await albumRepository.search().where('artist').is.not.equalTo('Mushroomhead').return.all()

Searching on Numbers

When you set the field type in your schema to number, you can store both integers and floating-point numbers. And you can search against it with all the comparisons you'd expect to see:

let albums

// find all albums where the year is ===, >, >=, <, and <= 1984
albums = await albumRepository.search().where('year').eq(1984).return.all()
albums = await albumRepository.search().where('year').gt(1984).return.all()
albums = await albumRepository.search().where('year').gte(1984).return.all()
albums = await albumRepository.search().where('year').lt(1984).return.all()
albums = await albumRepository.search().where('year').lte(1984).return.all()

// find all albums where the year is between 1980 and 1989 inclusive
albums = await albumRepository.search().where('year').between(1980, 1989).return.all()

// find all albums where the year is *not* ===, >, >=, <, and <= 1984
albums = await albumRepository.search().where('year').not.eq(1984).return.all()
albums = await albumRepository.search().where('year').not.gt(1984).return.all()
albums = await albumRepository.search().where('year').not.gte(1984).return.all()
albums = await albumRepository.search().where('year').not.lt(1984).return.all()
albums = await albumRepository.search().where('year').not.lte(1984).return.all()

// find all albums where year is *not* between 1980 and 1989 inclusive
albums = await albumRepository.search().where('year').not.between(1980, 1989);

// fluent alternatives that do the same thing
albums = await albumRepository.search().where('year').equals(1984).return.all()
albums = await albumRepository.search().where('year').does.equal(1984).return.all()
albums = await albumRepository.search().where('year').does.not.equal(1984).return.all()
albums = await albumRepository.search().where('year').is.equalTo(1984).return.all()
albums = await albumRepository.search().where('year').is.not.equalTo(1984).return.all()

albums = await albumRepository.search().where('year').greaterThan(1984).return.all()
albums = await albumRepository.search().where('year').is.greaterThan(1984).return.all()
albums = await albumRepository.search().where('year').is.not.greaterThan(1984).return.all()

albums = await albumRepository.search().where('year').greaterThanOrEqualTo(1984).return.all()
albums = await albumRepository.search().where('year').is.greaterThanOrEqualTo(1984).return.all()
albums = await albumRepository.search().where('year').is.not.greaterThanOrEqualTo(1984).return.all()

albums = await albumRepository.search().where('year').lessThan(1984).return.all()
albums = await albumRepository.search().where('year').is.lessThan(1984).return.all()
albums = await albumRepository.search().where('year').is.not.lessThan(1984).return.all()

albums = await albumRepository.search().where('year').lessThanOrEqualTo(1984).return.all()
albums = await albumRepository.search().where('year').is.lessThanOrEqualTo(1984).return.all()
albums = await albumRepository.search().where('year').is.not.lessThanOrEqualTo(1984).return.all()

albums = await albumRepository.search().where('year').is.between(1980, 1989).return.all()
albums = await albumRepository.search().where('year').is.not.between(1980, 1989).return.all()

Searching on Booleans

You can search against fields that contain booleans if you defined a field type of boolean in your schema:

let albums

// find all albums where outOfPublication is true
albums = await albumRepository.search().where('outOfPublication').true().return.all()

// find all albums where outOfPublication is false
albums = await albumRepository.search().where('outOfPublication').false().return.all()

You can negate boolean searches. This might seem odd, but if your field is null, then it would match on a .not query:

// find all albums where outOfPublication is false or null
albums = await albumRepository.search().where('outOfPublication').not.true().return.all()

// find all albums where outOfPublication is true or null
albums = await albumRepository.search().where('outOfPublication').not.false().return.all()

And, of course, there's lots of syntactic sugar to make this fluent:

albums = await albumRepository.search().where('outOfPublication').eq(true).return.all()
albums = await albumRepository.search().where('outOfPublication').equals(true).return.all()
albums = await albumRepository.search().where('outOfPublication').does.equal(true).return.all()
albums = await albumRepository.search().where('outOfPublication').is.equalTo(true).return.all()

albums = await albumRepository.search().where('outOfPublication').true().return.all()
albums = await albumRepository.search().where('outOfPublication').false().return.all()
albums = await albumRepository.search().where('outOfPublication').is.true().return.all()
albums = await albumRepository.search().where('outOfPublication').is.false().return.all()

albums = await albumRepository.search().where('outOfPublication').not.eq(true).return.all()
albums = await albumRepository.search().where('outOfPublication').does.not.equal(true).return.all()
albums = await albumRepository.search().where('outOfPublication').is.not.equalTo(true).return.all()
albums = await albumRepository.search().where('outOfPublication').is.not.true().return.all()
albums = await albumRepository.search().where('outOfPublication').is.not.false().return.all()

Searching on Dates

If you have a field type of date in your schema, you can search on it using Dates, ISO 8601 formatted strings, or the UNIX epoch time in seconds:

studios = await studioRepository.search().where('established').on(new Date('2010-12-27')).return.all()
studios = await studioRepository.search().where('established').on('2010-12-27').return.all()
studios = await studioRepository.search().where('established').on(1293408000).return.all()

There are several date comparison methods to use. And they can be negated:

const date = new Date('2010-12-27')
const laterDate = new Date('2020-12-27')

studios = await studioRepository.search().where('established').on(date).return.all()
studios = await studioRepository.search().where('established').not.on(date).return.all()
studios = await studioRepository.search().where('established').before(date).return.all()
studios = await studioRepository.search().where('established').not.before(date).return.all()
studios = await studioRepository.search().where('established').after(date).return.all()
studios = await studioRepository.search().where('established').not.after(date).return.all()
studios = await studioRepository.search().where('established').onOrBefore(date).return.all()
studios = await studioRepository.search().where('established').not.onOrBefore(date).return.all()
studios = await studioRepository.search().where('established').onOrAfter(date).return.all()
studios = await studioRepository.search().where('established').not.onOrAfter(date).return.all()
studios = await studioRepository.search().where('established').between(date, laterDate).return.all()
studios = await studioRepository.search().where('established').not.between(date, laterDate).return.all()

More fluent variations work too:

const date = new Date('2010-12-27')
const laterDate = new Date('2020-12-27')

studios = await studioRepository.search().where('established').is.on(date).return.all()
studios = await studioRepository.search().where('established').is.not.on(date).return.all()

studios = await studioRepository.search().where('established').is.before(date).return.all()
studios = await studioRepository.search().where('established').is.not.before(date).return.all()

studios = await studioRepository.search().where('established').is.onOrBefore(date).return.all()
studios = await studioRepository.search().where('established').is.not.onOrBefore(date).return.all()

studios = await studioRepository.search().where('established').is.after(date).return.all()
studios = await studioRepository.search().where('established').is.not.after(date).return.all()

studios = await studioRepository.search().where('established').is.onOrAfter(date).return.all()
studios = await studioRepository.search().where('established').is.not.onOrAfter(date).return.all()

studios = await studioRepository.search().where('established').is.between(date, laterDate).return.all()
studios = await studioRepository.search().where('established').is.not.between(date, laterDate).return.all()

And, since dates are really just numbers, all the numeric comparisons work too:

const date = new Date('2010-12-27')
const laterDate = new Date('2020-12-27')

studios = await studioRepository.search().where('established').eq(date).return.all()
studios = await studioRepository.search().where('established').not.eq(date).return.all()
studios = await studioRepository.search().where('established').equals(date).return.all()
studios = await studioRepository.search().where('established').does.equal(date).return.all()
studios = await studioRepository.search().where('established').does.not.equal(date).return.all()
studios = await studioRepository.search().where('established').is.equalTo(date).return.all()
studios = await studioRepository.search().where('established').is.not.equalTo(date).return.all()

studios = await studioRepository.search().where('established').gt(date).return.all()
studios = await studioRepository.search().where('established').not.gt(date).return.all()
studios = await studioRepository.search().where('established').greaterThan(date).return.all()
studios = await studioRepository.search().where('established').is.greaterThan(date).return.all()
studios = await studioRepository.search().where('established').is.not.greaterThan(date).return.all()

studios = await studioRepository.search().where('established').gte(date).return.all()
studios = await studioRepository.search().where('established').not.gte(date).return.all()
studios = await studioRepository.search().where('established').greaterThanOrEqualTo(date).return.all()
studios = await studioRepository.search().where('established').is.greaterThanOrEqualTo(date).return.all()
studios = await studioRepository.search().where('established').is.not.greaterThanOrEqualTo(date).return.all()

studios = await studioRepository.search().where('established').lt(date).return.all()
studios = await studioRepository.search().where('established').not.lt(date).return.all()
studios = await studioRepository.search().where('established').lessThan(date).return.all()
studios = await studioRepository.search().where('established').is.lessThan(date).return.all()
studios = await studioRepository.search().where('established').is.not.lessThan(date).return.all()

studios = await studioRepository.search().where('established').lte(date).return.all()
studios = await studioRepository.search().where('established').not.lte(date).return.all()
studios = await studioRepository.search().where('established').lessThanOrEqualTo(date).return.all()
studios = await studioRepository.search().where('established').is.lessThanOrEqualTo(date).return.all()
studios = await studioRepository.search().where('established').is.not.lessThanOrEqualTo(date).return.all()

Searching String Arrays

If you have a field type of string[] you can search for whole strings that are in that array:

let albums

// find all albums where genres contains the string 'rock'
albums = await albumRepository.search().where('genres').contain('rock').return.all()

// find all albums where genres contains the string 'rock', 'metal', or 'blues'
albums = await albumRepository.search().where('genres').containOneOf('rock', 'metal', 'blues').return.all()

// find all albums where genres does *not* contain the string 'rock'
albums = await albumRepository.search().where('genres').not.contain('rock').return.all()

// find all albums where genres does *not* contain the string 'rock', 'metal', and 'blues'
albums = await albumRepository.search().where('genres').not.containOneOf('rock', 'metal', 'blues').return.all()

// alternative syntaxes
albums = await albumRepository.search().where('genres').contains('rock').return.all()
albums = await albumRepository.search().where('genres').containsOneOf('rock', 'metal', 'blues').return.all()
albums = await albumRepository.search().where('genres').does.contain('rock').return.all()
albums = await albumRepository.search().where('genres').does.not.contain('rock').return.all()
albums = await albumRepository.search().where('genres').does.containOneOf('rock', 'metal', 'blues').return.all()
albums = await albumRepository.search().where('genres').does.not.containOneOf('rock', 'metal', 'blues').return.all()

Wildcards work here too:

albums = await albumRepository.search().where('genres').contain('*rock*').return.all()

Searching Arrays of Numbers

If you have a field of type number[], you can search on it just like a number. If any number in the array matches your criteria, then it'll match and the document will be returned.

let albums

// find all albums where at least one song is at least 3 minutes long
albums = await albumRepository.search().where('songDurations').gte(180).return.all()

// find all albums where at least one song is at exactly 3 minutes long
albums = await albumRepository.search().where('songDurations').eq(180).return.all()

// find all albums where at least one song is between 3 and 4 minutes long
albums = await albumRepository.search().where('songDurations').between(180, 240).return.all()

The same numeric predicates as in Searching on numbers apply to number[] fields (any array element may satisfy the predicate).

Full-Text Search

If you've defined a field with a type of text in your schema, you can store text in it and perform full-text searches against it. Full-text search is different from how a string is searched. With full-text search, you can look for words, partial words, fuzzy matches, and exact phrases within a body of text.

Full-text search treats natural language: common words (a, an, the, …) may be skipped; related forms (give, gives, given) may match via stemming; punctuation and extra whitespace are normalized.

Here are some examples of doing full-text search against some album titles:

let albums

// finds all albums where the title contains the word 'butterfly'
albums = await albumRepository.search().where('title').match('butterfly').return.all()

// finds all albums using fuzzy matching where the title contains a word which is within 3 Levenshtein distance of the word 'buterfly'
albums = await albumRepository.search().where('title').match('buterfly', { fuzzyMatching: true, levenshteinDistance: 3 }).return.all()

// finds all albums where the title contains the words 'beautiful' and 'children'
albums = await albumRepository.search().where('title').match('beautiful children').return.all()

// finds all albums where the title contains the exact phrase 'beautiful stories'
albums = await albumRepository.search().where('title').matchExact('beautiful stories').return.all()

For prefix, suffix, or infix word fragments, add * where needed:

// finds all albums where the title contains a word that contains 'right'
albums = await albumRepository.search().where('title').match('*right*').return.all()

Do not combine partial-word searches or fuzzy matches with exact matches. Partial-word searches and fuzzy matches with exact matches are not compatible in RediSearch. If you try to exactly match a partial-word search or fuzzy match a partial-word search, you'll get an error.

// THESE WILL ERROR
albums = await albumRepository.search().where('title').matchExact('beautiful sto*').return.all()
albums = await albumRepository.search().where('title').matchExact('*buterfly', { fuzzyMatching: true, levenshteinDistance: 3 }).return.all()

As always, there are several alternatives to make this a bit more fluent and, of course, negation is available:

albums = await albumRepository.search().where('title').not.match('butterfly').return.all()
albums = await albumRepository.search().where('title').matches('butterfly').return.all()
albums = await albumRepository.search().where('title').does.match('butterfly').return.all()
albums = await albumRepository.search().where('title').does.not.match('butterfly').return.all()

albums = await albumRepository.search().where('title').exact.match('beautiful stories').return.all()
albums = await albumRepository.search().where('title').not.exact.match('beautiful stories').return.all()
albums = await albumRepository.search().where('title').exactly.matches('beautiful stories').return.all()
albums = await albumRepository.search().where('title').does.exactly.match('beautiful stories').return.all()
albums = await albumRepository.search().where('title').does.not.exactly.match('beautiful stories').return.all()

albums = await albumRepository.search().where('title').not.matchExact('beautiful stories').return.all()
albums = await albumRepository.search().where('title').matchesExactly('beautiful stories').return.all()
albums = await albumRepository.search().where('title').does.matchExactly('beautiful stories').return.all()
albums = await albumRepository.search().where('title').does.not.matchExactly('beautiful stories').return.all()

Searching on Points

RediSearch supports geographic queries: supply a point and a radius to return entities within that area:

let studios

// finds all the studios with 50 miles of downtown Cleveland
studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).radius(50).miles).return.all()

Note that coordinates are specified with the longitude first, and then the latitude. This might be the opposite of what you expect but is consistent with how Redis implements coordinates in RediSearch and with GeoSets.

If you don't want to rely on argument order, you can also specify longitude and latitude more explicitly:

// finds all the studios within 50 miles of downtown Cleveland using a point
studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin({ longitude: -81.7758995, latitude: 41.4976393 }).radius(50).miles).return.all()

// finds all the studios within 50 miles of downtown Cleveland using longitude and latitude
studios = await studioRepository.search().where('location').inRadius(
  circle => circle.longitude(-81.7758995).latitude(41.4976393).radius(50).miles).return.all()

Radius can be in miles, feet, kilometers, and meters in all the spelling variations you could ever want:

// finds all the studios within 50 miles
studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).radius(50).miles).return.all()

studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).radius(50).mile).return.all()

studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).radius(50).mi).return.all()

// finds all the studios within 50 feet
studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).radius(50).feet).return.all()

studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).radius(50).foot).return.all()

studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).radius(50).ft).return.all()

// finds all the studios within 50 kilometers
studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).radius(50).kilometers).return.all()

studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).radius(50).kilometer).return.all()

studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).radius(50).km).return.all()

// finds all the studios within 50 meters
studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).radius(50).meters).return.all()

studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).radius(50).meter).return.all()

studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).radius(50).m).return.all()

If you omit the origin, the library defaults to longitude 0 and latitude 0 (Null Island):

// finds all the studios within 50 miles of Null Island (probably ain't much there)
studios = await studioRepository.search().where('location').inRadius(
  circle => circle.radius(50).miles).return.all()

If you don't specify the radius, it defaults to 1 and if you don't provide units, it defaults to meters:

// finds all the studios within 1 meter of downtown Cleveland
studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393)).return.all()

// finds all the studios within 1 kilometer of downtown Cleveland
studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).kilometers).return.all()

// finds all the studios within 50 meters of downtown Cleveland
studios = await studioRepository.search().where('location').inRadius(
  circle => circle.origin(-81.7758995, 41.4976393).radius(50)).return.all()

Equivalent fluent spellings include:

studios = await studioRepository.search().where('location').not.inRadius(
  circle => circle.longitude(-81.7758995).latitude(41.4976393).radius(50).miles).return.all()

studios = await studioRepository.search().where('location').is.inRadius(
  circle => circle.longitude(-81.7758995).latitude(41.4976393).radius(50).miles).return.all()

studios = await studioRepository.search().where('location').is.not.inRadius(
  circle => circle.longitude(-81.7758995).latitude(41.4976393).radius(50).miles).return.all()

studios = await studioRepository.search().where('location').not.inCircle(
  circle => circle.longitude(-81.7758995).latitude(41.4976393).radius(50).miles).return.all()

studios = await studioRepository.search().where('location').is.inCircle(
  circle => circle.longitude(-81.7758995).latitude(41.4976393).radius(50).miles).return.all()

studios = await studioRepository.search().where('location').is.not.inCircle(
  circle => circle.longitude(-81.7758995).latitude(41.4976393).radius(50).miles).return.all()

Chaining Searches

So far we've been doing searches that match on a single field. However, we often want to query on multiple fields. Not a problem:

const albums = await albumRepository.search()
  .where('artist').equals('Mushroomhead')
  .or('title').matches('butterfly')
  .and('year').is.greaterThan(1990).return.all()

These are executed in order from left to right, and ignore any order of operations. So this query will match an artist of "Mushroomhead" OR a title matching "butterfly" before it goes on to match that the year is greater than 1990.

If you'd like to change this you can nest your queries:

const albums = await albumRepository.search()
  .or(search => search
    .where('artist').equals('Mushroomhead')
    .and('year').is.greaterThan(1990)
  )
  .or(search => search.where('title').matches('butterfly'))
  .return.all()

This matches albums where (artist is Mushroomhead and year > 1990) or the title matches butterfly. Adjust grouping with nested callbacks if you need different precedence; see Chaining Searches.

Running Raw Searches

For queries that are easier to express in RediSearch’s native syntax, use .searchRaw with a query string. See the RediSearch query syntax.

// finds all the Mushroomhead albums with the word 'beautiful' in the title from 1990 and beyond
const query = "@artist:{Mushroomhead} @title:beautiful @year:[1990 +inf]"
const albums = albumRepository.searchRaw(query).return.all();

Results are the same entity objects as with the fluent builder.

Sorting Search Results

Sort by a single field with .sortBy, .sortAscending, or .sortDescending on these types: string, number, boolean, date, and text.

const albumsByYear = await albumRepository.search()
  .where('artist').equals('Mushroomhead')
    .sortAscending('year').return.all()

const albumsByTitle = await albumRepository.search()
  .where('artist').equals('Mushroomhead')
    .sortBy('title', 'DESC').return.all()

Mark fields as sortable in the schema so RediSearch can maintain a sortable side index where supported (not every field type benefits):

const albumSchema = new Schema('album', {
  artist: { type: 'string' },
  title: { type: 'text', sortable: true },
  year: { type: 'number', sortable: true },
  genres: { type: 'string[]' },
  outOfPublication: { type: 'boolean' }
})

If your schema is for a JSON data structure (the default), you can mark number, date, and text fields as sortable. You can also mark string and boolean fields as sortable, but this will have no effect and will generate a warning.

If your schema is for a Hash, you can mark string, number, boolean, date, and text fields as sortable.

Fields of the types point and string[] are never sortable.

Calling .sortBy on a field that could be sortable but is not may produce a runtime warning.

Advanced usage

Additional configuration for RediSearch-backed schemas:

Schema Options

Additional field options can be set depending on the field type. These correspond to the Field Options available when creating a RediSearch full-text index. Other than the separator option, these only affect how content is indexed and searched.

| schema type | RediSearch type | indexed | sortable | normalized | stemming | matcher | weight | separator | caseSensitive | | -------------- | :-------------: | :-------: | :--------: | :----------: | :--------: | :--------: | :------: | :---------: | :-------------: | | string | TAG | yes | HASH Only | HASH Only | - | - | - | yes | yes | | number | NUMERIC | yes | yes | - | - | - | - | - | - | | boolean | TAG | yes | HASH Only | - | - | - | - | - | - | | string[] | TAG | yes | HASH Only | HASH Only | - | - | - | yes | yes | | number[] | NUMERIC | yes | yes | - | - | - | - | - | - | | date | NUMERIC | yes | yes | - | | - | - | - | - | | point | GEO | yes | - | - | | - | - | - | - | | text | TEXT | yes | yes | yes | yes | yes | yes | - | - |

• indexed: true | false, whether this field is indexed by RediSearch (default true)
• sortable: true | false, whether to create an additional index to optimize sorting (default false)
• normalized: true | false, whether to apply normalization for sorting (default true)
• matcher: string defining phonetic matcher which can be one of: 'dm:en' for English, 'dm:fr' for French, 'dm:pt' for Portuguese, 'dm:es' for Spanish (default none)
• stemming: true | false, whether word-stemming is applied to text fields (default true)
• weight: number, the importance weighting to use when ranking results (default 1)
• separator: string, the character to delimit multiple tags (default '|')
• caseSensitive: true | false, whether original letter casing is kept for search (default false)

Example showing additional options:

const commentSchema = new Schema('comment', {
  name: { type: 'text', stemming: false, matcher: 'dm:en' },
  email: { type: 'string', normalized: false, },
  posted: { type: 'date', sortable: true },
  title: { type: 'text', weight: 2 },
  comment: { type: 'text', weight: 1 },
  approved: { type: 'boolean', indexed: false },
  iphash: { type: 'string', caseSensitive: true },
  notes: { type: 'string', indexed: false },
})

See docs/classes/Schema.md for additional Schema options.

Documentation

Generated TypeDoc output lives under docs/. This README covers day-to-day usage; the class reference fills in edge cases and full method signatures.

Troubleshooting

If something fails, confirm Redis Stack (RediSearch + RedisJSON) is available, indices are created, and your schema matches stored data. For upstream redis-om behavior, see issues on redis-om-node. Community help is available on the Redis Discord.

Contributing

Contributions are welcome: reproducible bug reports, documentation fixes, and pull requests that include or update tests when behavior changes.