{ "schema_version": 2, "id": "commands/vsim", "title": "VSIM", "url": "https://redis.io/docs/latest/commands/vsim/", "summary": "Return elements by vector similarity.", "since": "8.0.0", "tags": [ "docs", "develop", "stack", "oss", "rs", "rc", "oss", "kubernetes", "clients" ], "last_updated": "2026-09-18T09:47:58+01:00", "page_type": "content", "content_hash": "7f542a1a4c170e34e2dbbb669e32ac3e122580557ea2f23e863719a47d884a27", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "Return elements similar to a given vector or element. Use this command to perform approximate or exact similarity searches within a vector set.\n\nYou can query using either a vector (via `FP32` or `VALUES num`) or by referencing another element (using `ELE`). Optional parameters let you control the search behavior, such as score output, result count, and filtering options.\n\n[code example]\n\nYou can include similarity scores, attributes (if any), and limit the number of results:\n\n[code example]\n\nSet the `EF` (exploration factor) to improve recall at the cost of performance. Use the `TRUTH` option to perform an exact linear scan, useful for benchmarking. The `NOTHREAD` option runs the search in the main thread and may increase server latency." }, { "id": "required-arguments", "title": "Required arguments", "role": "content", "text": "
\nkey\n\nis the name of the key that holds the vector set data.\n
\n\n
\nELE | FP32 | VALUES num\n\nspecifies how the input vector is provided. Use `ELE` to refer to an existing element, `FP32` for binary float format (little-endian encoding required), or `VALUES num` for a list of stringified float values.\n
\n\n
\nvector or element\n\nis either the vector data (for `FP32` or `VALUES`) or the name of the element (for `ELE`) to use as the similarity reference.\n
" }, { "id": "optional-arguments", "title": "Optional arguments", "role": "parameters", "text": "
\nWITHSCORES\n\nreturns the similarity score (from 1 to 0) alongside each result. A score of 1 is identical; 0 is the opposite.\n
\n\n
\nWITHATTRIBS\n\nreturns, for each element, the JSON attribute associated with the element or NULL when no attributes are present.\n
\n\n
\nCOUNT num\n\nlimits the number of returned results to `num`.\n
\n\n
\nEPSILON delta\n\nis a floating point number between 0 and 1. It is used to retrieve elements that have a distance that is no further than the specified `delta`. In vector sets, returned elements have a similarity score (when compared to the query vector) that is between 1 and 0, where 1 means identical and 0 means opposite vectors. For example, if the `EPSILON` option is specified with an argument of `0.2`, it means only elements that have a similarity of 0.8 or better (a distance < 0.2) are returned. This is useful when you specify a large `COUNT`, but you don't want elements that are too far away from the query vector.\n
\n\n
\nEF search-exploration-factor\n\ncontrols the search effort. Higher values explore more nodes, improving recall at the cost of speed. Typical values range from 50 to 1000.\n
\n\n
\nFILTER expression\n\napplies a filter expression to restrict matching elements. See [Filtered search](https://redis.io/docs/latest/develop/data-types/vector-sets/filtered-search) for syntax details.\n
\n\n
\nFILTER-EF max-filtering-effort\n\nlimits the number of filtering attempts for the `FILTER` expression. See [Filtered search](https://redis.io/docs/latest/develop/data-types/vector-sets/filtered-search) for more information.\n
\n\n
\nTRUTH\n\nforces an exact linear scan of all elements, bypassing the HNSW graph. Use for benchmarking or to calculate recall. This is significantly slower (O(N)).\n
\n\n
\nNOTHREAD\n\nexecutes the search in the main thread instead of a background thread. Useful for small vector sets or benchmarks. This may block the server during execution.\n
" }, { "id": "redis-software-and-redis-cloud-compatibility", "title": "Redis Software and Redis Cloud compatibility", "role": "content", "text": "| Redis
Software | Redis
Cloud | Notes |\n|:----------------------|:-----------------|:------|\n| ✅ Standard
❌ Active-Active | ✅ Standard
❌ Active-Active | |" }, { "id": "return-information", "title": "Return information", "role": "returns", "text": "**RESP2:**\n\nOne of the following:\n* [Simple error reply](../../develop/reference/protocol-spec/#simple-errors) for an unknown element.\n* [Array reply](../../develop/reference/protocol-spec#arrays) (empty array) for an unknown key.\n* [Array reply](../../develop/reference/protocol-spec#arrays) with matching elements.\n* With the `WITHSCORES` option, an [array reply](../../develop/reference/protocol-spec#arrays) with matching [bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec#bulk-strings) elements juxtaposed with [bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec#bulk-strings) as floating-point scores.\n* With the `WITHSCORES` and `WITHATTRIBS` options, an [array reply](../../develop/reference/protocol-spec#arrays) with matching [bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec#bulk-strings) elements, and two additional elements: (1) a [bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec#bulk-strings) as floating-point score and (2) a [bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec#bulk-strings) representing the JSON attribute associated with the element or [nil (null bulk string)](https://redis.io/docs/latest/develop/reference/protocol-spec#bulk-strings) for the elements missing an attribute.\n\n**RESP3:**\n\nOne of the following:\n* [Simple error reply](../../develop/reference/protocol-spec/#simple-errors) for unknown element.\n* [Array reply](../../develop/reference/protocol-spec#arrays) (empty array) for unknown key.\n* [Array reply](../../develop/reference/protocol-spec#arrays) with matching elements.\n* With the `WITHSCORES` option, a [map reply](../../develop/reference/protocol-spec#maps) with matching [bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec#bulk-strings) elements (keys) and [double](../../develop/reference/protocol-spec#doubles) scores (values).\n* With the `WITHSCORES` and `WITHATTRIBS` options, a [Map reply](../../develop/reference/protocol-spec#maps) with matching [bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec#bulk-strings) elements (keys), and an additional array (values) with the following elements: (1) a [double reply](https://redis.io/docs/latest/develop/reference/protocol-spec#bulk-strings) for the score and (2) a [bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec#bulk-strings) representing the JSON attribute associated with the element or [null](https://redis.io/docs/latest/develop/reference/protocol-spec#nulls) for the elements missing an attribute." }, { "id": "related-topics", "title": "Related topics", "role": "related", "text": "- [Vector sets](https://redis.io/docs/latest/develop/data-types/vector-sets)\n- [Filtered search](https://redis.io/docs/latest/develop/data-types/vector-sets/filtered-search)" } ], "examples": [ { "id": "overview-ex0", "language": "shell", "code": "VSIM word_embeddings ELE apple\n1) \"apple\"\n2) \"apples\"\n3) \"pear\"\n4) \"fruit\"\n5) \"berry\"\n6) \"pears\"\n7) \"strawberry\"\n8) \"peach\"\n9) \"potato\"\n10) \"grape\"", "section_id": "overview" }, { "id": "overview-ex1", "language": "shell", "code": "VSIM word_embeddings ELE apple WITHSCORES WITHATTRIBS COUNT 3\n1) \"apple\"\n2) \"0.9998867657923256\"\n3) \"{\\\"len\\\": 5}\"\n4) \"apples\"\n5) \"0.859852746129036\"\n6) \"{\\\"len\\\": 6}\"\n7) \"pear\"\n8) \"0.8226882070302963\"\n9) \"{\\\"len\\\": 4}\"", "section_id": "overview" } ] }