# Vector search commands
<a name="vector-search-commands"></a>

Following are a list of supported commands for vector search. 

**Topics**
+ [

# FT.CREATE
](vector-search-commands-ft.create.md)
+ [

# FT.SEARCH
](vector-search-commands-ft.search.md)
+ [

# FT.AGGREGATE
](vector-search-commands-ft.aggregate.md)
+ [

# FT.DROPINDEX
](vector-search-commands-ft.dropindex.md)
+ [

# FT.INFO
](vector-search-commands-ft.info.md)
+ [

# FT.\$1LIST
](vector-search-commands-ft.list.md)
+ [

# FT.ALIASADD
](vector-search-commands-ft.aliasadd.md)
+ [

# FT.ALIASDEL
](vector-search-commands-ft.aliasdel.md)
+ [

# FT.ALIASUPDATE
](vector-search-commands-ft.aliasupdate.md)
+ [

# FT.\$1ALIASLIST
](vector-search-commands-ft.aliaslist.md)
+ [

# FT.PROFILE
](vector-search-commands-ft.profile.md)
+ [

# FT.EXPLAIN
](vector-search-commands-ft.explain.md)
+ [

# FT.EXPLAINCLI
](vector-search-commands-ft.explain-cli.md)

# FT.CREATE
<a name="vector-search-commands-ft.create"></a>

 Creates an index and initiates a backfill of that index. For more information, see [Vector search overview](https://docs.aws.amazon.com/memorydb/latest/devguide/vector-search-overview.html) for details on index construction.

**Syntax**

```
FT.CREATE <index-name>
ON HASH | JSON
[PREFIX <count> <prefix1> [<prefix2>...]]
SCHEMA 
(<field-identifier> [AS <alias>] 
  NUMERIC 
| TAG [SEPARATOR <sep>] [CASESENSITIVE] 
| TEXT
| VECTOR [HNSW|FLAT] <attr_count> [<attribute_name> <attribute_value>])

)+
```

**Schema**
+ Field identifier:
  + For hash keys, field identifier is A field name.
  + For JSON keys, field identifier is A JSON path.

  For more information, see [Index field types](vector-search-overview.md#vector-search-index-field-types).
+ Field types:
  + TAG: For more information, see [Tags](https://redis.io/docs/interact/search-and-query/advanced-concepts/tags/) .
  + NUMERIC: Field contains a number.
  + TEXT: Field contains any blob of data.
  + VECTOR: vector field that supports vector search.
    + Algorithm – can be HNSW (Hierarchical Navigable Small World) or FLAT (brute force). 
    + `attr_count` – number of attributes that will be passed as algorithm configuration, this includes both names and values. 
    + `{attribute_name} {attribute_value}` – algorithm-specific key/value pairs that define index configuration. 

      For FLAT algorithm, attributes are:

      Required:
      + DIM – Number of dimensions in the vector.
      + DISTANCE\$1METRIC – Can be one of [L2 \$1 IP \$1 COSINE].
      + TYPE – Vector type. The only supported type is `FLOAT32`.

      Optional:
      + INITIAL\$1CAP – Initial vector capacity in the index affecting memory allocation size of the index.

      For HNSW algorithm, attributes are:

      Required:
      + TYPE – Vector type. The only supported type is `FLOAT32`.
      + DIM – Vector dimension, specified as a positive integer. Maximum: 32768
      + DISTANCE\$1METRIC – Can be one of [L2 \$1 IP \$1 COSINE].

      Optional:
      + INITIAL\$1CAP – Initial vector capacity in the index affecting memory allocation size of the index. Defaults to 1024.
      + M – Number of maximum allowed outgoing edges for each node in the graph in each layer. on layer zero the maximal number of outgoing edges will be 2M. Default is 16 Maximum is 512.
      + EF\$1CONSTRUCTION – controls the number of vectors examined during index construction. Higher values for this parameter will improve recall ratio at the expense of longer index creation times. Default value is 200. Maximum value is 4096.
      + EF\$1RUNTIME – controls the number of vectors examined during query operations. Higher values for this parameter can yield improved recall at the expense of longer query times. The value of this parameter can be overriden on a per-query basis. Default value is 10. Maximum value is 4096.

**Return**

Returns a simple string OK message or error reply.

**Examples**

**Note**  
The following example uses arguments native to [valkey-cli](https://valkey.io/topics/cli/), such as de-quoting and de-escaping of data, before sending it to Valkey or Redis OSS. To use other programming-language clients (Python, Ruby, C\$1, etc.), follow those environments' handling rules for dealing with strings and binary data. For more information on supported clients, see [Tools to Build on AWS](https://aws.amazon.com/developer/tools/)

**Example 1: Create some indexes**  
Create an index for vectors of size 2  

```
FT.CREATE hash_idx1 ON HASH PREFIX 1 hash: SCHEMA vec AS VEC VECTOR HNSW 6 DIM 2 TYPE FLOAT32 DISTANCE_METRIC L2
OK
```
Create a 6-dimensional JSON index using the HNSW algorithm:  

```
FT.CREATE json_idx1 ON JSON PREFIX 1 json: SCHEMA $.vec AS VEC VECTOR HNSW 6 DIM 6 TYPE FLOAT32 DISTANCE_METRIC L2
OK
```

**Example 2: Populate some data**  
The following commands are formatted so they can be executed as arguments to the redis-cli terminal program. Developers using programming-language clients (such Python, Ruby, C\$1, etc.) will need to follow their environment's handling rules for dealing with strings and binary data.  
Creating some hash and json data:  

```
HSET hash:0 vec "\x00\x00\x00\x00\x00\x00\x00\x00"
HSET hash:1 vec "\x00\x00\x00\x00\x00\x00\x80\xbf"
JSON.SET json:0 . '{"vec":[1,2,3,4,5,6]}'
JSON.SET json:1 . '{"vec":[10,20,30,40,50,60]}'
JSON.SET json:2 . '{"vec":[1.1,1.2,1.3,1.4,1.5,1.6]}'
```
Note the following:  
+ The keys of the hash and JSON data have the prefixes of their index definitions.
+ The vectors are at the appropriate paths of the index definitions.
+ The hash vectors are entered as hex data while the JSON data is entered as numbers.
+ The vectors are the appropriate lengths, the two-dimensional hash vector entries have two floats worth of hex data, the six-dimensional json vector entries have six numbers.

**Example 3: Delete and re-create an index**  

```
FT.DROPINDEX json_idx1
OK

FT.CREATE json_idx1 ON JSON PREFIX 1 json: SCHEMA $.vec AS VEC VECTOR FLAT 6 DIM 6 TYPE FLOAT32 DISTANCE_METRIC L2
OK
```
Note the new JSON index uses the `FLAT` algorithm instead of the `HNSW` algorithm. Also note that it will re-index the existing JSON data:  

```
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]}]"
```

# FT.SEARCH
<a name="vector-search-commands-ft.search"></a>

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](https://docs.aws.amazon.com/memorydb/latest/devguide/vector-search-overview.html#vector-search-query-expression).

To create data for use in these examples, see the [FT.CREATE](https://docs.aws.amazon.com/memorydb/latest/devguide/vector-search-commands-ft.create.html) 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](https://docs.aws.amazon.com/memorydb/latest/devguide/vector-search-overview.html#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](https://valkey.io/topics/cli/), such as de-quoting and de-escaping of data, before sending it to Valkey or Redis OSS. To use other programming-language clients (Python, Ruby, C\$1, etc.), follow those environments' handling rules for dealing with strings and binary data. For more information on supported clients, see [Tools to Build on AWS](https://aws.amazon.com/developer/tools/)

**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]}]"
```

# FT.AGGREGATE
<a name="vector-search-commands-ft.aggregate"></a>

A superset of the FT.SEARCH command, it allows substantial additional processing of the keys selected by the query expression.

**Syntax**

```
FT.AGGREGATE index query
  [LOAD * | [count field [field ...]]]
  [TIMEOUT timeout]
  [PARAMS count name value [name value ...]]
  [FILTER expression]
  [LIMIT offset num]  
  [GROUPBY count property [property ...] [REDUCE function count arg [arg ...] [AS name] [REDUCE function count arg [arg ...] [AS name] ...]] ...]] 
  [SORTBY count [ property ASC | DESC [property ASC | DESC ...]] [MAX num]] 
  [APPLY expression AS name]
```
+ FILTER, LIMIT, GROUPBY, SORTBY and APPLY clauses can be repeated multiple times in any order and be freely intermixed. They are applied in the order specified with the output of one clause feeding the input of the next clause.
+ In the above syntax, a “property” is either a field declared in the [FT.CREATE](https://docs.aws.amazon.com/memorydb/latest/devguide/vector-search-commands-ft.create.html) command for this index OR the output of a previous APPLY clause or REDUCE function.
+ The LOAD clause is restricted to loading fields that have been declared in the index. “LOAD \$1” will load all fields declared in the index. 
+ The following reducer functions are supported: COUNT, COUNT\$1DISTINCTISH, SUM, MIN, MAX, AVG, STDDEV, QUANTILE, TOLIST, FIRST\$1VALUE, and RANDOM\$1SAMPLE. For more information, see [Aggregations](https://redis.io/docs/interact/search-and-query/search/aggregations/)
+ LIMIT <offset> <count>: Retains records starting at <offset> and continuing for up to <count>, all other records are discarded.
+ PARAMS: Two times the number of key value pairs. Param key/value pairs can be referenced from within the query expression.

**Return**

Returns an array or error reply.
+ If the operation completes successfully, it returns an array. The first element is an integer with no particular meaning (should be ignored). The remaining elements are the results output by the last stage. Each element is an array of field name and value pairs.
+ 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.

# FT.DROPINDEX
<a name="vector-search-commands-ft.dropindex"></a>

Drop an index. The index definition and associated content are deleted. Keys are unaffected.

**Syntax**

```
FT.DROPINDEX <index-name>
```

**Return**

Returns a simple string OK message or an error reply.

# FT.INFO
<a name="vector-search-commands-ft.info"></a>

**Syntax**

```
FT.INFO <index-name>
```

Output from the FT.INFO page is an array of key value pairs as described in the following table:


| Key | Value type | Description | 
| --- | --- | --- | 
| index\$1name | string | Name of the index | 
| creation\$1timestamp | integer | Unix-style timestamp of creation time | 
| key\$1type | string | HASH or JSON | 
| key\$1prefixes | array of strings | Key prefixes for this index | 
| fields | array of field information | Fields of this index | 
| space\$1usage | integer | Memory bytes used by this index | 
| fullext\$1space\$1usage | integer | Memory bytes used by non-vector fields | 
| vector\$1space\$1usage | integer | Memory bytes used by vector fields | 
| num\$1docs | integer | Number of keys currently contained in the index | 
| num\$1indexed\$1vectors | integer | Number of vectors currently contained in the index | 
| current\$1lag | integer | Recent delay of ingestion (milliSeconds) | 
| backfill\$1status | string | One of: Completed, InProgres, Paused or Failed  | 

The following table describes the information for each field:


| Key | Value type | Description | 
| --- | --- | --- | 
| identifier | string | name of field | 
| field\$1name | string | Hash member name or JSON Path | 
| type | string | one of: Numeric, Tag, Text or Vector | 
| option | string | ignore | 

If the field is of type Vector, additional information will be present depending on the algorithm. 

For the HNSW algorithm:


| Key | Value type | Description | 
| --- | --- | --- | 
| algorithm | string | HNSW | 
| data\$1type | string | FLOAT32 | 
| distance\$1metric | string | one of: L2, IP or Cosine | 
| initial\$1capacity | integer | Initial size of vector field index | 
| current\$1capacity | integer | Current size of vector field index | 
| maximum\$1edges | integer | M parameter at creation | 
| ef\$1construction | integer | EF\$1CONSTRUCTION parameter at creation | 
| ef\$1runtime | integer | EF\$1RUNTIME parameter at creation | 

For the FLAT algorithm:


| Key | Value type | Description | 
| --- | --- | --- | 
| algorithm | string | FLAT | 
| data\$1type | string | FLOAT32 | 
| distance\$1metric | string | one of: L2, IP or Cosine | 
| initial\$1capacity | integer | Initial size of vector field index | 
| current\$1capacity | integer | Current size of vector field index | 

# FT.\$1LIST
<a name="vector-search-commands-ft.list"></a>

List all indexes.

**Syntax**

```
FT._LIST 
```

**Return**

Returns an array of index names

# FT.ALIASADD
<a name="vector-search-commands-ft.aliasadd"></a>

Add an alias for an index. The new alias name can be used anywhere that an index name is required.

**Syntax**

```
FT.ALIASADD <alias> <index-name> 
```

**Return**

Returns a simple string OK message or an error reply.

# FT.ALIASDEL
<a name="vector-search-commands-ft.aliasdel"></a>

Delete an existing alias for an index.

**Syntax**

```
FT.ALIASDEL <alias>
```

**Return**

Returns a simple string OK message or an error reply.

# FT.ALIASUPDATE
<a name="vector-search-commands-ft.aliasupdate"></a>

Update an existing alias to point to a different physical index. This command only affects future references to the alias. Currently in-progress operations (FT.SEARCH, FT.AGGREGATE) are unaffected by this command.

**Syntax**

```
FT.ALIASUPDATE <alias> <index>
```

**Return**

Returns a simple string OK message or an error reply.

# FT.\$1ALIASLIST
<a name="vector-search-commands-ft.aliaslist"></a>

List the index aliases.

**Syntax**

```
FT._ALIASLIST
```

**Return**

Returns an array the size of the number of current aliases. Each element of the array is the alias-index pair.

# FT.PROFILE
<a name="vector-search-commands-ft.profile"></a>

Run a query and return profile information about that query.

**Syntax**

```
FT.PROFILE 

<index>
SEARCH | AGGREGATE 
[LIMITED]
QUERY <query ....>
```

**Return**

A two-element array. The first element is the result of the `FT.SEARCH` or `FT.AGGREGATE` command that was profiled. The second element is an array of performance and profiling information.

# FT.EXPLAIN
<a name="vector-search-commands-ft.explain"></a>

Parse a query and return information about how that query was parsed.

**Syntax**

```
FT.EXPLAIN <index> <query>
```

**Return**

A string containing the parsed results.

# FT.EXPLAINCLI
<a name="vector-search-commands-ft.explain-cli"></a>

Same as the FT.EXPLAIN command except that the results are displayed in a different format more useful with the redis-cli.

**Syntax**

```
FT.EXPLAINCLI <index> <query>
```

**Return**

A string containing the parsed results.