Skip to main content
Upstash Documentation

Schemas

6 min read

Every search index requires a schema that defines the structure of searchable documents. The schema allows for type-safety and allows us to optimize your data for very fast queries.

We provide a schema builder utility called s that makes it easy to define a schema.

Field Type Reference#

SDK MethodRedis CLI TypeDescriptionSupports FASTMultiple valuesRange OperatorsText Operators
s.string()TEXTFull-text searchable field with tokenization and stemmingNoYesNo$smart, $phrase, $fuzzy, $regex
s.keyword()KEYWORDExact-match string (no tokenization)YesYesYes ($gt, $gte, $lt, $lte)No
s.number()F64 (default), U64, I64Numeric fieldYesYesYesNo
s.date()DATEDate/time fieldYesYesYesNo
s.boolean()BOOLBoolean fieldYesNoNoNo
s.facet()FACETHierarchical path-based fieldNoNoNoNo (only $eq, $in)
Note

In the TypeScript SDK, s.number() defaults to F64. You can specify s.number("U64") or s.number("I64") for unsigned or signed 64-bit integers. F64 fields are FAST by default.

FAST Fields#

The FAST flag creates a columnar store for a field, enabling:

  • Sorting with ORDERBY in queries
  • Score functions with SCOREFUNC FIELDVALUE
  • Metric aggregations ($avg, $sum, $min, $max, $count, etc.)

In the TypeScript SDK, numeric (F64), boolean, and date fields are FAST by default. You can disable it with .fast(false). In Redis CLI, you must explicitly add the FAST keyword after the field type.

If you attempt to use ORDERBY, SCOREFUNC, or metric aggregations on a non-FAST field, you will get an error.

Basic Usage#

The schema builder provides methods for each field type:

The schema builder also supports chaining field options. We'll see what noTokenize() and noStem() are used for in the section below.

Nested Objects#

The schema builder supports nested object structures:

Multi-value fields#

A document field can contain several values without a separate array type in the schema. Declare the field as TEXT, KEYWORD, U64, I64, F64, or DATE, then store its value as a JSON array. Search indexes every valid array element under the same field.

For example, this schema accepts several tags, descriptions, prices, and restock dates per product:

The way you store the array depends on the index data type:

Index data typeHow to store multiple valuesExample
JSONA JSON array in the documentJSON.SET product:1 $ '{"tags":["new","sale"]}'
STRINGA JSON array inside the JSON object stored in the stringSET product:1 '{"tags":["new","sale"]}'
HASHA complete, JSON-encoded array in the hash field stringHSET product:1 tags '["new","sale"]'
STREAMA complete, JSON-encoded array in the stream field stringXADD events * services '["checkout","payments"]'

There is no separator option, a value such as new,sale remains one value. Use a valid JSON array ["new","sale"] to index two values.

Each array element must match the schema type. Search ignores an invalid element while still indexing the valid elements in the same array. An empty array, or an array with no valid elements, acts like a missing field. BOOL and FACET fields do not support array values.

Queries match a document when any indexed element satisfies the condition. For example, both of these queries match a product whose tags value is ["new","sale"] and whose prices value is [19.99,24.99]:

Each TEXT array element is analyzed separately. A phrase can match within one element, but cannot start in one element and continue in another. See Multi-value queries for more examples and highlighting behavior.

Where to use the Schema#

We need the schema when creating or querying an index:

For the complete index creation syntax, see SEARCH.CREATE.

Tokenization & Stemming#

When you store text in a search index, it goes through two transformations: Tokenization and Stemming. By default, text fields are both tokenized and stemmed. Understanding these helps you configure fields correctly.

Tokenization#

Tokenization splits text into individual searchable words (tokens) by breaking on spaces and punctuation.

Original TextTokens
"hello world"["hello", "world"]
"user@example.com"["user", "example", "com"]
"SKU-12345-BLK"["SKU", "12345", "BLK"]

This is great for natural language because searching for "world" will match "hello world". But it breaks values that should stay together.

When to disable tokenization with .noTokenize():

  • Email addresses (user@example.com)
  • URLs (https://example.com/page)
  • Product codes and SKUs (SKU-12345-BLK)
  • UUIDs (550e8400-e29b-41d4-a716-446655440000)
  • Category slugs (electronics/phones/android)

Stemming#

Stemming reduces words to their root form so different variations match the same search.

WordStemmed Form
"running", "runs", "runner""run"
"studies", "studying", "studied""studi"
"experiments", "experimenting""experi"

This way, a user searching for "running shoes" will also find "run shoes" and "runner shoes".

When to disable stemming with .noStem():

  • Brand names (Nike shouldn't match Nik)
  • Proper nouns and names (Johnson shouldn't become John)
  • Technical terms (React shouldn't match Reac)
  • When using regex patterns (stemmed text won't match your expected patterns)

Keyword Fields#

The KEYWORD field type is for exact-match strings. Unlike TEXT fields, keywords are not tokenized or stemmed — the entire value is treated as a single token.

KEYWORD fields support numeric query operators ($eq, $in, $gt, $gte, $lt, $lte), which are not available on TEXT fields.

When to use KEYWORD instead of TEXT:

  • When you need range operators ($gt, $gte, $lt, $lte) on string values
  • When the entire string should be treated as a single unit (no word splitting)
  • For tags, labels, status codes, or any string that should match exactly

Facet Fields#

The FACET field type is for hierarchical path-based faceted search. Values must be /-delimited paths starting with /.

FACET fields only support $eq and $in operators. They are primarily used with the $facet aggregation to build category trees and faceted navigation.

Example — querying facet fields:

Aliased Fields#

Aliased fields allow you to index the same document field multiple times with different settings, or to create shorter names for complex nested paths. Use the FROM keyword to specify which document field the alias points to.

Common use cases for aliased fields:

  • Same field with different settings: Index a text field both with and without stemming. Use the stemmed version for general searches and the non-stemmed version for exact matching or regex queries.
  • Shorter query paths: Create concise aliases for deeply nested fields like metadata.author.displayName to simplify queries.
Note

When using aliased fields:

  • Use the alias name in queries and highlighting (e.g., descriptionExact, authorName)
  • Use the actual field name when selecting fields to return (e.g., description, metadata.author.displayName)

This is because aliasing happens at the index level and does not modify the underlying documents.

Non-Indexed Fields#

Documents don't need to match the schema exactly:

  • Extra fields: Fields in your document that aren't defined in the schema are simply ignored. They won't be indexed or searchable.
  • Missing fields: If a document is missing a field defined in the schema, that document won't appear in search results that filter on the missing field.

Schema Examples#

E-commerce product schema

User directory schema

Document UpdatesQueries