TypeScript-based Node.js library for Redis with object mapping and additional utilities.
---
[![Discord][discord-shield]][discord-url]
[![Twitch][twitch-shield]][twitch-url]
[![YouTube][youtube-shield]][youtube-url]
[![Twitter][twitter-shield]][twitter-url]
[![NPM][package-shield]][package-url]
[![Build][build-shield]][build-url]
[![License][license-shield]][license-url]
**redis-type-os** implements schemas, repositories, and fluent search over Redis. It follows the same model as [Redis OM for Node.js](https://github.com/redis/redis-om-node), with TypeScript declarations and tooling for Node.js applications.
Related Redis OM clients: [Redis OM .NET][redis-om-dotnet] · [Redis OM Node.js (upstream)](https://github.com/redis/redis-om-node) · [Redis OM Python][redis-om-python] · [Redis OM Spring][redis-om-spring]
Table of contents
- [Overview](#overview)
- [Getting Started](#getting-started)
- [Connect to Redis with Node Redis](#connect-to-redis-with-node-redis)
- [Redis Connection Strings](#redis-connection-strings)
- [Entities and Schemas](#entities-and-schemas)
- [JSON and Hashes](#json-and-hashes)
- [Configuring JSON](#configuring-json)
- [Configuring Hashes](#configuring-hashes)
- [Reading, Writing, and Removing with Repository](#reading-writing-and-removing-with-repository)
- [Creating Entities](#creating-entities)
- [Missing Entities and Null Values](#missing-entities-and-null-values)
- [Searching](#searching)
- [Build the Index](#build-the-index)
- [Finding All The Things (and Returning Them)](#finding-all-the-things-and-returning-them)
- [Pagination](#pagination)
- [First Things First](#first-things-first)
- [Counting](#counting)
- [Finding Specific Things](#finding-specific-things)
- [Searching on Strings](#searching-on-strings)
- [Searching on Numbers](#searching-on-numbers)
- [Searching on Booleans](#searching-on-booleans)
- [Searching on Dates](#searching-on-dates)
- [Searching String Arrays](#searching-string-arrays)
- [Searching Arrays of Numbers](#searching-arrays-of-numbers)
- [Full-Text Search](#full-text-search)
- [Searching on Points](#searching-on-points)
- [Chaining Searches](#chaining-searches)
- [Running Raw Searches](#running-raw-searches)
- [Sorting Search Results](#sorting-search-results)
- [Advanced usage](#advanced-usage)
- [Schema Options](#schema-options)
- [Documentation](#documentation)
- [Troubleshooting](#troubleshooting)
- [Contributing](#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:
```javascript
const schema = new Schema('album', {
artist: { type: 'string' },
title: { type: 'text' },
year: { type: 'number' }
})
```
Create a JavaScript object and save it:
```javascript
const album = {
artist: "Mushroomhead",
title: "The Righteous & The Butterfly",
year: 2014
}
await repository.save(album)
```
Search for matching entities:
```javascript
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](CHANGELOG) before upgrading. The [redis-om 0.3.6 README](https://www.npmjs.com/package/redis-om/v/0.3.6) 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:
```bash
npm install redis-type-os redis
```
Use [Redis Stack][redis-stack-url] (includes [RediSearch][redisearch-url] and [RedisJSON][redis-json-url]) or [Redis Cloud][redis-cloud-url]. With Docker:
```bash
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-type-os**, connect to Redis with [Node Redis](https://github.com/redis/node-redis). Minimal setup (from the Node Redis [README](https://github.com/redis/node-redis)):
```javascript
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](https://github.com/redis/node-redis).
With a connected client you can run ordinary Redis commands when needed:
```javascript
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`:
```javascript
await redis.quit()
```
### Redis Connection Strings
By default, Node Redis connects to `localhost:6379`. Override this with a URL:
```javascript
const redis = createClient({ url: 'redis://alice:foobared@awesome.redis.server:6380' })
```
The basic format for this URL is:
redis://username:password@host:port
The full URI scheme is [registered with IANA](https://www.iana.org/assignments/uri-schemes/prov/redis); TLS uses [`rediss://`](https://www.iana.org/assignments/uri-schemes/prov/rediss).
For sockets, clustering, and other options, see the Node Redis [client configuration](https://github.com/redis/node-redis/blob/master/docs/client-configuration.md) and [clustering](https://github.com/redis/node-redis/blob/master/docs/clustering.md) guides.
## Entities and Schemas
This library is concerned with saving, reading, and deleting *entities*. An [Entity](docs/README.md#entity) is plain JavaScript object data you persist or load from Redis. Almost any object shape can serve as an `Entity`.
[Schemas](docs/classes/Schema.md) 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:
```javascript
import { Schema } from 'redis-type-os'
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String), a [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), or a [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean). `string[]` and `number[]` do what you'd think as well, specifically describing an [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) and can be set using not only a Date but also a String containing an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date or a number with the [UNIX epoch time](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#the_ecmascript_epoch_and_timestamps) 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:
```javascript
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](https://redis.io/docs/stack/search/reference/stemming/), [stop words](https://redis.io/docs/stack/search/reference/stopwords/), and related features). See [Searching](#searching).
### JSON and Hashes
By default, entities are stored as JSON documents (RedisJSON). You can set this explicitly:
```javascript
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'`:
```javascript
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:
```json
{
"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](https://redis.io/docs/stack/json/path/#jsonpath-syntax) 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:
```json
{
"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:
```javascript
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:
```javascript
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:
```javascript
{
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:
```javascript
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*](docs/classes/Repository.md) to create, read, update, delete, and search entities:
```javascript
import { Repository } from 'redis-type-os'
const albumRepository = new Repository(albumSchema, redis)
const studioRepository = new Repository(studioSchema, redis)
```
Call `.save` to persist entities:
```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol). Import `EntityId` from **redis-type-os** and read the ID with `entity[EntityId]`:
```javascript
import { EntityId } from 'redis-type-os'
album = await albumRepository.save(album)
album[EntityId] // '01FJYWEYRHYFT8YTEGQBABJ43J'
```
Generated IDs are [ULIDs](https://github.com/ulid/spec). To use your own ID, pass it as the first argument to `.save`:
```javascript
album = await albumRepository.save('BWOMP', album)
```
Load an entity by ID with `.fetch`:
```javascript
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:
```javascript
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:
```javascript
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`:
```javascript
await albumRepository.remove('01FJYWEYRHYFT8YTEGQBABJ43J')
```
Set a TTL in seconds with `.expire` (Redis removes the key when it elapses):
```javascript
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:
```javascript
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:
```javascript
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][redisearch-url] available on your server, repositories support indexed search—for example:
```javascript
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:
```javascript
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`:
```javascript
await albumRepository.dropIndex();
```
### Finding All The Things (and Returning Them)
Return every entity matching the (possibly empty) query:
```javascript
const albums = await albumRepository.search().return.all()
```
#### Pagination
Request a slice with a zero-based offset and page size:
```javascript
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:
```javascript
const firstAlbum = await albumRepository.search().return.first();
```
#### Counting
Return the number of matches without loading documents:
```javascript
const count = await albumRepository.search().return.count()
```
### Finding Specific Things
Narrow results using [strings](#searching-on-strings), [numbers](#searching-on-numbers), [booleans](#searching-on-booleans), [string arrays](#searching-string-arrays), [numeric arrays](#searching-arrays-of-numbers), [full-text](#full-text-search), [dates](#searching-on-dates), and [geo radius](#searching-on-points). 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](#full-text-search) syntax.
```javascript
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:
```javascript
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:
```javascript
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:
```javascript
// 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:
```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formatted strings, or the [UNIX epoch time](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#the_ecmascript_epoch_and_timestamps) in *seconds*:
```javascript
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:
```javascript
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:
```javascript
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:
```javascript
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:
```javascript
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:
```javascript
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.
```javascript
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](#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:
```javascript
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:
```javascript
// 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.
```javascript
// 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:
```javascript
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:
```javascript
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](https://oss.redis.com/redisearch/Query_Syntax/) and with [GeoSets](https://redis.io/commands#geo).
If you don't want to rely on argument order, you can also specify longitude and latitude more explicitly:
```javascript
// 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:
```javascript
// 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](https://en.wikipedia.org/wiki/Null_Island)):
```javascript
// 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*:
```javascript
// 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:
```javascript
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:
```javascript
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:
```javascript
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](#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](https://oss.redis.com/redisearch/Query_Syntax/).
```javascript
// 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`.
```javascript
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):
```javascript
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](https://redis.io/commands/ft.create/#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:
```javascript
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](docs/classes/Schema.md) for additional `Schema` options.
## Documentation
Generated TypeDoc output lives under [`docs/`](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](https://github.com/redis/redis-om-node). Community help is available on the [Redis Discord][discord-url].
## Contributing
Contributions are welcome: reproducible bug reports, documentation fixes, and pull requests that include or update tests when behavior changes.
[package-shield]: https://img.shields.io/npm/v/redis-type-os?logo=npm
[build-shield]: https://img.shields.io/github/workflow/status/redis/redis-om-node/CI/main
[license-shield]: https://img.shields.io/npm/l/redis-type-os
[discord-shield]: https://img.shields.io/discord/697882427875393627?style=social&logo=discord
[twitch-shield]: https://img.shields.io/twitch/status/redisinc?style=social
[twitter-shield]: https://img.shields.io/twitter/follow/redisinc?style=social
[youtube-shield]: https://img.shields.io/youtube/channel/views/UCD78lHSwYqMlyetR0_P4Vig?style=social
[package-url]: https://www.npmjs.com/package/redis-type-os
[build-url]: https://github.com/redis/redis-om-node/actions/workflows/ci.yml
[license-url]: LICENSE
[discord-url]: http://discord.gg/redis
[twitch-url]: https://www.twitch.tv/redisinc
[twitter-url]: https://twitter.com/redisinc
[youtube-url]: https://www.youtube.com/redisinc
[redis-cloud-url]: https://redis.com/try-free/
[redis-stack-url]: https://redis.io/docs/stack/
[redisearch-url]: https://oss.redis.com/redisearch/
[redis-json-url]: https://oss.redis.com/redisjson/
[redis-om-dotnet]: https://github.com/redis/redis-om-dotnet
[redis-om-python]: https://github.com/redis/redis-om-python
[redis-om-spring]: https://github.com/redis/redis-om-spring
