Available in:
Redis Stack / Search 1.0.0
Time complexity:

Search the index with a textual query, returning either documents or just ids


FT.SEARCH index query 
          [ FILTER numeric_field min max [ FILTER numeric_field min max ...]] 
          [ GEOFILTER geo_field lon lat radius m | km | mi | ft [ GEOFILTER geo_field lon lat radius m | km | mi | ft ...]] 
          [ INKEYS count key [key ...]] [ INFIELDS count field [field ...]] 
          [ RETURN count identifier [AS property] [ identifier [AS property] ...]] 
          [ SUMMARIZE [ FIELDS count field [field ...]] [FRAGS num] [LEN fragsize] [SEPARATOR separator]] 
          [ HIGHLIGHT [ FIELDS count field [field ...]] [ TAGS open close]] 
          [SLOP slop] 
          [TIMEOUT timeout] 
          [LANGUAGE language] 
          [EXPANDER expander] 
          [SCORER scorer] 
          [PAYLOAD payload] 
          [ SORTBY sortby [ ASC | DESC]] 
          [ LIMIT offset num] 
          [ PARAMS nargs name value [ name value ...]] 
          [DIALECT dialect]


Required parameters


is index name. You must first create the index using FT.CREATE.


is text query to search. If it's more than a single word, put it in quotes. Refer to Query syntax for more details.

Optional parameters


returns the document ids and not the content. This is useful if RediSearch is only an index on an external document collection.


does not try to use stemming for query expansion but searches the query terms verbatim.


also returns the relative internal score of each document. This can be used to merge results from multiple instances.


retrieves optional document payloads. See FT.CREATE. The payloads follow the document id and, if WITHSCORES is set, the scores.


returns the value of the sorting key, right after the id and score and/or payload, if requested. This is usually not needed, and exists for distributed search coordination purposes. This option is relevant only if used in conjunction with SORTBY.

FILTER numeric_attribute min max

limits results to those having numeric values ranging between min and max, if numeric_attribute is defined as a numeric attribute in FT.CREATE. min and max follow ZRANGE syntax, and can be -inf, +inf, and use ( for exclusive ranges. Multiple numeric filters for different attributes are supported in one query.

GEOFILTER {geo_attribute} {lon} {lat} {radius} m|km|mi|ft

filter the results to a given radius from lon and lat. Radius is given as a number and units. See GEORADIUS for more details.

INKEYS {num} {attribute} ...

limits the result to a given set of keys specified in the list. The first argument must be the length of the list and greater than zero. Non-existent keys are ignored, unless all the keys are non-existent.

INFIELDS {num} {attribute} ...

filters the results to those appearing only in specific attributes of the document, like title or URL. You must include num, which is the number of attributes you're filtering by. For example, if you request title and URL, then num is 2.

RETURN {num} {identifier} AS {property} ...

limits the attributes returned from the document. num is the number of attributes following the keyword. If num is 0, it acts like NOCONTENT. identifier is either an attribute name (for hashes and JSON) or a JSON Path expression (for JSON). property is an optional name used in the result. If not provided, the identifier is used in the result.


returns only the sections of the attribute that contain the matched text. See Highlighting for more information.


formats occurrences of matched text. See Highlighting for more information.

SLOP {slop}

allows a maximum of N intervening number of unmatched offsets between phrase terms. In other words, the slop for exact phrases is 0.


puts the query terms in the same order in the document as in the query, regardless of the offsets between them. Typically used in conjunction with SLOP.

LANGUAGE {language}

use a stemmer for the supplied language during search for query expansion. If querying documents in Chinese, set to chinese to properly tokenize the query terms. Defaults to English. If an unsupported language is sent, the command returns an error. See FT.CREATE for the list of languages.

EXPANDER {expander}

uses a custom query expander instead of the stemmer. See Extensions.

SCORER {scorer}

uses a custom scoring function you define. See Extensions.


returns a textual description of how the scores were calculated. Using this options requires the WITHSCORES option.

PAYLOAD {payload}

adds an arbitrary, binary safe payload that is exposed to custom scoring functions. See Extensions.

SORTBY {attribute} [ASC|DESC]

orders the results by the value of this attribute. This applies to both text and numeric attributes. Attributes needed for SORTBY should be declared as SORTABLE in the index, in order to be available with very low latency. Note that this adds memory overhead.

LIMIT first num

limits the results to the offset and number of results given. Note that the offset is zero-indexed. The default is 0 10, which returns 10 items starting from the first result. You can use LIMIT 0 0 to count the number of documents in the result set without actually returning them.

TIMEOUT {milliseconds}

overrides the timeout parameter of the module.

PARAMS {nargs} {name} {value}

defines one or more value parameters. Each parameter has a name and a value.

You can reference parameters in the query by a $, followed by the parameter name, for example, $user. Each such reference in the search query to a parameter name is substituted by the corresponding parameter value. For example, with parameter definition PARAMS 4 lon 29.69465 lat 34.95126, the expression @loc:[$lon $lat 10 km] is evaluated to @loc:[29.69465 34.95126 10 km]. You cannot reference parameters in the query string where concrete values are not allowed, such as in field names, for example, @loc. To use PARAMS, set DIALECT to 2.

DIALECT {dialect_version}

selects the dialect version under which to execute the query. If not specified, the query will execute under the default dialect version set during module initial loading or via FT.CONFIG SET command.


FT.SEARCH returns an array reply, where the first element is an integer reply of the total number of results, and then array reply pairs of document ids, and array replies of attribute/value pairs.


  • If NOCONTENT is given, an array is returned where the first element is the total number of results, and the rest of the members are document ids.
  • If a hash expires after the query process starts, the hash is counted in the total number of results, but the key name and content return as null.


FT.SEARCH complexity is O(n) for single word queries. n is the number of the results in the result set. Finding all the documents that have a specific term is O(1), however, a scan on all those documents is needed to load the documents data from redis hashes and return them.

The time complexity for more complex queries varies, but in general it's proportional to the number of words, the number of intersection points between them and the number of results in the result set.


Search for a term in every text attribute

Search for the term "wizard" in every TEXT attribute of an index containing book data.> FT.SEARCH books-idx "wizard"
Search for a term in title attribute

Search for the term dogs in the title attribute.> FT.SEARCH books-idx "@title:dogs"
Search for books from specific years

Search for books published in 2020 or 2021.> FT.SEARCH books-idx "@published_at:[2020 2021]"
Search for a restaurant by distance from longitude/latitude

Search for Chinese restaurants within 5 kilometers of longitude -122.41, latitude 37.77 (San Francisco).> FT.SEARCH restaurants-idx "chinese @location:[-122.41 37.77 5 km]"
Search for a book by terms but boost specific term

Search for the term dogs or cats in the title attribute, but give matches of dogs a higher relevance score (also known as boosting).> FT.SEARCH books-idx "(@title:dogs | @title:cats) | (@title:dogs) => { $weight: 5.0; }"
Search for a book by a term and EXPLAINSCORE

Search for books with dogs in any TEXT attribute in the index and request an explanation of scoring for each result.> FT.SEARCH books-idx "dogs" WITHSCORES EXPLAINSCORE
Search for a book by a term and TAG

Searching for books with space in the title that have science in the TAG attribute categories:> FT.SEARCH books-idx "@title:space @categories:{science}"
Search for a book by a term but limit the number

Searching for books with Python in any TEXT attribute, returning ten results starting with the eleventh result in the entire result set (the offset parameter is zero-based), and returning only the title attribute for each result:> FT.SEARCH books-idx "python" LIMIT 10 10 RETURN 1 title
Search for a book by a term and price

Search for books with Python in any TEXT attribute, returning the price stored in the original JSON document.> FT.SEARCH books-idx "python" RETURN 3 $.book.price AS price
Search for a book by title and distance

Search for books with semantically similar title to Planet Earth. Return top 10 results sorted by distance.> FT.SEARCH books-idx "*=>[KNN 10 @title_embedding $query_vec AS title_score]" PARAMS 2 query_vec <"Planet Earth" embedding BLOB> SORTBY title_score DIALECT 2

See also



  • Starting with Redis version 2.0.0: Deprecated WITHPAYLOADS and PAYLOAD arguments


If you've found issues on this page, or have suggestions for improvement, please submit a request to merge or open an issue in the repository.