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 valkey-cli
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]}]"