# VSIM.SEARCH

> Find the keys whose vectors are nearest to a query vector, optionally only among tagged keys.

URL: https://docs.hotkv.com/commands/vsim-search/

```
VSIM.SEARCH index k value [value ...] [FILTER tag [tag ...]] [EF ef]
```

- Group: Vector search
- Complexity: O(log N) on average, N being the vectors in the index
- HotKV Cloud: all plans
- On-Premise: no license needed

`VSIM.SEARCH` returns up to `k` keys from the vector index `index` whose
vectors are closest to the query vector, nearest first, each with its
distance. Give exactly as many values as the index has dimensions, right
after `k`. The search is approximate: on large indexes a true neighbor can
occasionally be missed; raise `EF` (or the index's `EF_SEARCH`) to make that
rarer.

## Options

| Option | Effect |
| --- | --- |
| `FILTER tag [tag ...]` | Only consider keys that carry all of these tags (see [TAG.SET](https://docs.hotkv.com/commands/tag-set/index.md)). |
| `EF ef` | Search effort for this call, at least 1. Higher is more accurate and slower. Defaults to the index's `EF_SEARCH`. |

`FILTER` takes every argument after it up to `EF` or the end. Tags are read
from the node that runs the search, so in cluster mode a filtered search only
sees tags set on that node.

## Distances

Lower always means closer. What the number means depends on the index metric:

| Metric | Distance |
| --- | --- |
| `COSINE` | 1 minus the cosine similarity: 0 for the same direction, up to 2. |
| `L2` | The squared Euclidean distance. |
| `IP` | The negative inner product. |

## Return value

A flat array: key, distance, key, distance, and so on, nearest first. Keys
and distances are bulk strings (distances with up to 8 significant digits).
The shape is the same in RESP2 and RESP3. The array is empty when the index
has no matching vectors.

Error replies:

- `ERR index 'name' not found`
- `ERR invalid k (must be >= 1)`
- `ERR expected 3 dimensions after k` (with the index's count) when values are missing.
- `ERR invalid float at dimension 0` for a value that is not a finite number.
- `ERR EF requires a value` and `ERR invalid EF value`

Arguments after the vector other than `FILTER` and `EF` are ignored.

## Examples

```
127.0.0.1:6379> VSIM.CREATEINDEX points 3 METRIC L2
OK
127.0.0.1:6379> VSIM.SET points p:1 1 0 0
(integer) 1
127.0.0.1:6379> VSIM.SET points p:2 1 1 0
(integer) 1
127.0.0.1:6379> VSIM.SET points p:3 0 2 2
(integer) 1
127.0.0.1:6379> VSIM.SEARCH points 2 1 0 0
1) "p:1"
2) "0"
3) "p:2"
4) "1"
127.0.0.1:6379> SET p:3 "..."
OK
127.0.0.1:6379> TAG.SET p:3 featured
(integer) 1
127.0.0.1:6379> VSIM.SEARCH points 2 1 0 0 FILTER featured
1) "p:3"
2) "9"
```

## Compatibility

HotKV-only command. It is not related to the `VSIM` command of Redis 8
vector sets.

## See also

[VSIM.SET](https://docs.hotkv.com/commands/vsim-set/index.md), [VSIM.CREATEINDEX](https://docs.hotkv.com/commands/vsim-createindex/index.md), [TAG.SET](https://docs.hotkv.com/commands/tag-set/index.md),
[TAG.INTER](https://docs.hotkv.com/commands/tag-inter/index.md)