FT.SEARCH - Amazon MemoryDB for Redis
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

FT.SEARCH

Uses the provided query expression to locate keys within an index. Once located, the count and/or content of indexed fields within those keys can be returned. For more information, see Vector search query expression.

To create data for use in these examples, see the FT.CREATE command.

Syntax

FT.SEARCH <index-name> <query> [RETURN <token_count> (<field-identifier> [AS <alias>])+] [TIMEOUT timeout] [PARAMS <count> <name> <value> [<name> <value>]] [LIMIT <offset> <count>] [COUNT]
  • RETURN: This clause identifies which fields of a key are returned. The optional AS clause on each field overrides the name of the field in the result. Only fields that have been declared for this index can be specified.

  • LIMIT: <offset> <count>: This clause provides pagination capability in that only the keys that satisfy the offset and count values are returned. If this clause is omitted, it defaults to "LIMIT 0 10", i.e., only a maximum of 10 keys will be returned.

  • PARAMS: Two times the number of key value pairs. Param key/value pairs can be referenced from within the query expression. For more information, see Vector search query expression.

  • COUNT: This clause suppresses returning the contents of keys, only the number of keys is returned. This is an alias for "LIMIT 0 0".

Return

Returns an array or error reply.

  • If the operation completes successfully, it returns an array. The first element is the total number of keys matching the query. The remaining elements are pairs of key name and field list. Field list is another array comprising pairs of field name and values.

  • If the index is in progress of being back-filled, the command immediately returns an error reply.

  • If timeout is reached, the command returns an error reply.

Example: Do some searches

Note

The following example uses arguments native to redis-cli, such as de-quoting and de-escaping of data, before sending it to Redis. To use other programming-language clients (Python, Ruby, C#, etc.), follow those environments' handling rules for dealing with strings and binary data. For more information on supported clients, see Tools to Build on Amazon

A hash search

FT.SEARCH hash_idx1 "*=>[KNN 2 @VEC $query_vec]" PARAMS 2 query_vec "\x00\x00\x00\x00\x00\x00\x00\x00" DIALECT 2 1) (integer) 2 2) "hash:0" 3) 1) "__VEC_score" 2) "0" 3) "vec" 4) "\x00\x00\x00\x00\x00\x00\x00\x00" 4) "hash:1" 5) 1) "__VEC_score" 2) "1" 3) "vec" 4) "\x00\x00\x00\x00\x00\x00\x80\xbf"

This produces two results, sorted by their score, which is the distance from the query vector (entered as hex).

JSON searches

FT.SEARCH json_idx1 "*=>[KNN 2 @VEC $query_vec]" PARAMS 2 query_vec "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00" DIALECT 2 1) (integer) 2 2) "json:2" 3) 1) "__VEC_score" 2) "11.11" 3) "$" 4) "[{\"vec\":[1.1, 1.2, 1.3, 1.4, 1.5, 1.6]}]" 4) "json:0" 5) 1) "__VEC_score" 2) "91" 3) "$" 4) "[{\"vec\":[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]}]"

This produces the two closest results, sorted by their score, and note that the JSON vector values are converted to floats and the query vector is still vector data. Note also that because the KNN parameter is 2, there are only two results. A larger value will return more results:

FT.SEARCH json_idx1 "*=>[KNN 100 @VEC $query_vec]" PARAMS 2 query_vec "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00" DIALECT 2 1) (integer) 3 2) "json:2" 3) 1) "__VEC_score" 2) "11.11" 3) "$" 4) "[{\"vec\":[1.1, 1.2, 1.3, 1.4, 1.5, 1.6]}]" 4) "json:0" 5) 1) "__VEC_score" 2) "91" 3) "$" 4) "[{\"vec\":[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]}]" 6) "json:1" 7) 1) "__VEC_score" 2) "9100" 3) "$" 4) "[{\"vec\":[10.0, 20.0, 30.0, 40.0, 50.0, 60.0]}]"