For more examples, see the FT.CREATE and FT.SEARCH command pages.

Vector search

You can add vector similarity queries directly into the query language by:

1. Using a range query with the syntax of @vector:[VECTOR_RANGE {radius} $query_vec], which filters the results to a given radius from a given query vector. The distance metric derives from the definition of a @vector field in the index schema, for example, Cosine or L2 (as of v2.6.1).

2. Running a k nearest neighbors (KNN) query on a @vector field. The basic syntax is "*=>[ KNN {num|$num} @vector $query_vec ]". It is also possible to run a hybrid query on filtered results. A hybrid query allows the user to specify a filter criteria that all results in a KNN query must satisfy. The filter criteria can include any type of field (i.e., indexes created on both vectors and other values, such as TEXT, PHONETIC, NUMERIC, GEO, etc.). The general syntax for hybrid query is {some filter query}=>[ KNN {num|$num} @vector $query_vec], where => separates the filter query from the vector KNN query.

Examples:

• Return 10 nearest neighbors entities in which query_vec is closest to the vector stored in @vector_field:

  *=>[KNN 10 @vector_field $query_vec]

• Among entities published between 2020 and 2022, return 10 nearest neighbors entities in which query_vec is closest to the vector stored in @vector_field:

  @published_year:[2020 2022]=>[KNN 10 @vector_field $query_vec]

• Return every entity for which the distance between the vector stored under its @vector_field and query_vec is at most 0.5, in terms of the @vector_field distance metric:

  @vector_field:[VECTOR_RANGE 0.5 $query_vec]

As of v2.4, the KNN vector search can be used at most once in a query, while, as of v2.6, the vector range filter can be used multiple times in a query. For more information on vector similarity syntax, see Querying vector fields, and Vector search examples sections.

Prefix matching

When indexes are updated, Redis maintains a dictionary of all terms in the index. This can be used to match all terms starting with a given prefix. Selecting prefix matches is done by appending * to a prefix token. For example:

hel* world

Will be expanded to cover (hello|help|helm|...) world.

A few notes on prefix searches

1. As prefixes can be expanded into many terms, use them with caution. The expansion will create a Union operation of all suffixes.

2. As a protective measure to avoid selecting too many terms, blocking Redis, which is single threaded, there are two limitations on prefix matching:

• Prefixes are limited to 2 letters or more. You can change this number by using the MINPREFIX setting on the module command line.

• The minimum word length to stem is 4 letters or more. You can change this number by using the MINSTEMLEN setting on the module command line.

• Expansion is limited to 200 terms or less. You can change this number by using the MAXEXPANSIONS setting on the module command line.

3. Prefix matching fully supports Unicode and is case insensitive.

4. Currently, there is no sorting or bias based on suffix popularity.

Infix/suffix matching

As of v2.6.0, the dictionary can be used for infix (contains) or suffix queries by appending * to the token. For example:

*sun* *ing 

These queries are CPU intensive because they require iteration over the whole dictionary.

Using a suffix trie

A suffix trie maintains a list of terms that match the suffix. If you add a suffix trie to a field using the WITHSUFFIXTRIE keyword, you can create more efficient infix and suffix queries because it eliminates the need to iterate over the whole dictionary. However, the iteration on the union does not change.

Suffix queries create a union of the list of terms from the suffix term node. Infix queries use the suffix terms as prefixes to the trie and create a union of all terms from all matching nodes.

Wildcard matching

As of v2.6.0, you can use the dictionary for wildcard matching queries with these parameters.

• ? - for any single character
• * - for any character repeating zero or more times
• ' and \ - for escaping; other special characters are ignored

An example of the syntax is "w'foo*bar?'".

Using a suffix trie

A suffix trie maintains a list of terms which match the suffix. If you add a suffix trie to a field using the WITHSUFFIXTRIE keyword, you can create more efficient wildcard matching queries because it eliminates the need to iterate over the whole dictionary. However, the iteration on the union does not change.

With a suffix trie, the wildcard pattern is broken into tokens at every * character. A heuristic is used to choose the token with the least terms, and each term is matched with the wildcard pattern.

Fuzzy matching

As of v1.2.0, the dictionary of all terms in the index can also be used to perform fuzzy matching. Fuzzy matches are performed based on Levenshtein distance (LD). Fuzzy matching on a term is performed by surrounding the term with '%', for example:

%hello% world

This performs fuzzy matching on hello for all terms where LD is 1.

As of v1.4.0, the LD of the fuzzy match can be set by the number of '%' characters surrounding it, so that %%hello%% will perform fuzzy matching on 'hello' for all terms where LD is 2.

The maximum LD for fuzzy matching is 3.

Wildcard queries

As of v1.1.0, you can use a special query to retrieve all the documents in an index. This is meant mostly for the aggregation engine. You can call it by specifying only a single star sign as the query string, in other words, FT.SEARCH myIndex *.

You can't combine this with any other filters, field modifiers, or anything inside the query. It is technically possible to use the deprecated FILTER and GEOFILTER request parameters outside the query string in conjunction with a wildcard, but this makes the wildcard meaningless and only hurts performance.

Query attributes

As of v1.2.0, you can apply specific query modifying attributes to specific clauses of the query.

The syntax is (foo bar) => { $attribute: value; $attribute:value; ...}:

(foo bar) => { $weight: 2.0; $slop: 1; $inorder: true; }
~(bar baz) => { $weight: 0.5; }

The supported attributes are:

1. $weight: determines the weight of the sub-query or token in the overall ranking on the result (default: 1.0).
2. $slop: determines the maximum allowed slop (space between terms) in the query clause (default: 0).
3. $inorder: whether or not the terms in a query clause must appear in the same order as in the query. This is usually set alongside with $slop (default: false).
4. $phonetic: whether or not to perform phonetic matching (default: true). Note: setting this attribute to true for fields which were not created as PHONETIC will produce an error.

As of v2.6.1, the query attributes syntax supports these additional attributes:

• $yield_distance_as: specifies the distance field name, used for later sorting and/or returning, for clauses that yield some distance metric. It is currently supported for vector queries only (both KNN and range).
• vector query params: pass optional parameters for vector queries in key-value format.

A few query examples

• Simple phrase query - hello AND world:

    hello world
  

• Exact phrase query - hello FOLLOWED BY world:

    "hello world"
  

• Union - documents containing either hello OR world:

    hello|world
  

• Not - documents containing hello BUT NOT world:

    hello -world
  

• Intersection of unions:

    (hello|halo) (world|werld)
  

• Negation of union:

    hello -(world|werld)
  

• Union inside phrase:

    (barack|barrack) obama
  

• Optional terms with higher priority to ones containing more matches:

    obama ~barack ~michelle
  

• Exact phrase in one field, one word in another field:

    @title:"barack obama" @job:president
  

• Combined AND, OR with field specifiers:

    @title:"hello world" @body:(foo bar) @category:(articles|biographies)
  

• Prefix/infix/suffix queries:

    hello worl*
  
    hel* *worl
  
    hello -*worl*
  

• Wildcard matching queries:

    "w'foo??bar??baz'"
  
    "w'???????'"
  
    "w'hello*world'"
  

• Numeric filtering - products named tv with a price range of 200 to 500:

    @name:tv @price:[200 500]
  

• Numeric filtering - users with age greater than 18:

    @age:[(18 +inf]
  

Mapping common SQL predicates to Redis Query Engine

Technical notes

The query parser is built using the Lemon Parser Generator and a Ragel based lexer. You can see the DIALECT 2 grammar definition at this git repo.

You can also see the DEFAULT_DIALECT configuration parameter.