VSIM

Since 1.1.0Vector sets

Syntax

VSIM key (ELE | FP32 | VALUES num) vector [WITHSCORES] [WITHATTRIBS] [COUNT num] [EF n] [FILTER expr] [FILTER-EF n] [NOTHREAD] [TRUTH]
  • Flags: readonly
  • ACL categories: @read, @slow, @vector
  • Arity: -2

Returns the elements of the vector set at key most similar to a vector, most similar first.

Options

OptionEffect
ELE elementUse an element's vector.
VALUES n x1 ... xn, FP32 blobUse this vector.
COUNT nReturn at most n elements (10 by default).
WITHSCORESGive each element's similarity, from 0 to 1: 1 is identical.
WITHATTRIBSGive each element's attributes.
EF n, FILTER-EF n, NOTHREAD, TRUTHAccepted. Every search compares every vector, so results are exact.
FILTER exprScore only the elements whose attributes pass expr.

FILTER takes an expression over an element's JSON attributes, each named with a leading dot: comparisons (.size > 2, .color == "red"), and, or, not, arithmetic, **, and in for a value in an array ("a" in .tags, .year in [2024, 2025]). An element without an attribute the expression reads does not pass. Before 1.2, FILTER was accepted and ignored, and every element was returned.

Reply

  • An array of elements; with WITHSCORES or WITHATTRIBS, each followed by its score or attributes.
  • ERR element not found in vector set for an ELE that does not exist.
  • ERR syntax error in FILTER expression for a FILTER that is not an expression.

Examples

> VSIM points VALUES 3 1 0 0 WITHSCORES COUNT 2
1) "a"
2) "1.000000"
3) "b"
4) "0.996942"
> VSIM points ELE c WITHATTRIBS COUNT 1
1) "c"
2) "{\"color\":\"red\",\"size\":3}"
> VSIM points VALUES 3 1 0 0 FILTER '.color == "red"'
1) "c"

Scores

With the default COSINE distance, WITHSCORES gives (1 + cosine) / 2, as Redis does: identical vectors score 1, vectors at right angles 0.5, and opposite ones 0. Before 1.2, it gave the cosine itself, from -1 to 1 (kividb#171); the order of the results was the same. A threshold an application set on the old scores needs changing. Sets made with DISTANCE L2 or INNERPRODUCT keep their scores.