diff --git a/content/commands/type/index.md b/content/commands/type/index.md index 2c4e7999cd..dcdc9a53f3 100644 --- a/content/commands/type/index.md +++ b/content/commands/type/index.md @@ -47,7 +47,7 @@ title: TYPE --- Returns the string representation of the type of the value stored at `key`. The different types that can be returned are: `string`, `list`, `set`, `zset`, -`hash` and `stream`. +`hash`, `stream`, and `vectorset`. ## Examples diff --git a/content/develop/data-types/vector-sets/_index.md b/content/develop/data-types/vector-sets/_index.md index cf223ce794..bda2e97b7e 100644 --- a/content/develop/data-types/vector-sets/_index.md +++ b/content/develop/data-types/vector-sets/_index.md @@ -38,3 +38,165 @@ The following commands are available for vector sets: - [VREM]({{< relref "/commands/vrem" >}}) - remove an element from a vector set. - [VSETATTR]({{< relref "/commands/vsetattr" >}}) - set or replace attributes on a vector set element. - [VSIM]({{< relref "/commands/vsim" >}}) - retrieve elements similar to a given vector or element with optional filtering. + +## Examples + +The following examples give an overview of how to use vector sets. For clarity, +we will use a set of two-dimensional vectors that represent points in the +Cartesian coordinate plane. However, in real use cases, the vectors will typically +represent *text embeddings* and have hundreds of dimensions. See +[Redis for AI]({{< relref "/develop/ai" >}}) for more information about using text +embeddings. + +The points we will use are A: (1.0, 1.0), B: (-1.0, -1.0), C: (-1.0, 1.0), D: (1.0. -1.0), and +E: (1.0, 0), shown in the diagram below. + +{{Example points on the coordinate plane.}} + +### Basic operations + +Start by adding the point vectors to a set called `points` using +[`VADD`]({{< relref "/commands/vadd" >}}). This also creates the vector set object. +The [`TYPE`]({{< relref "/commands/type" >}}) command returns a type of `vectorset` +for this object. + +``` +> VADD points VALUES 2 1.0 1.0 pt:A +(integer) 1 +> VADD points VALUES 2 -1.0 -1.0 pt:B +(integer) 1 +> VADD points VALUES 2 -1.0 1.0 pt:C +(integer) 1 +> VADD points VALUES 2 1.0 -1.0 pt:D +(integer) 1 +> VADD points VALUES 2 1.0 0 pt:E +(integer) 1 +> TYPE points +vectorset +``` + +Get the number of elements in the set (also known as the *cardinality* of the set) +using [`VCARD`]({{< relref "/commands/vcard" >}}) and the number of dimensions of +the vectors using [`VDIM`]({{< relref "/commands/vdim" >}}): + +``` +> VCARD points +(integer) 5 +> VDIM points +(integer) 2 +``` + +Get the coordinate values from the elements using [`VEMB`]({{< relref "/commands/vemb" >}}). +Note that the values will not typically be the exact values you supplied when you added +the vector because +[quantization]({{< relref "/develop/data-types/vector-sets/performance#quantization-effects" >}}) +is applied to improve performance. + +``` +> VEMB points pt:A +1) "0.9999999403953552" +2) "0.9999999403953552" +9> VEMB points pt:B +1) "-0.9999999403953552" +2) "-0.9999999403953552" +> VEMB points pt:C +1) "-0.9999999403953552" +2) "0.9999999403953552" +> VEMB points pt:D +1) "0.9999999403953552" +2) "-0.9999999403953552" +> VEMB points pt:E +1) "1" +2) "0" +``` + +Set and retrieve an element's JSON attribute data using +[`VSETATTR`]({{< relref "/commands/vsetattr" >}}) +and [`VGETATTR`]({{< relref "/commands/vgetattr" >}}). You can also pass an empty string +to `VSETATTR` to delete the attribute data: + +``` +> VSETATTR points pt:A "{\"name\": \"Point A\", \"description\": \"First point added\"}" +(integer) 1 +> VGETATTR points pt:A +"{\"name\": \"Point A\", \"description\": \"First point added\"}" +> VSETATTR points pt:A "" +(integer) 1 +> VGETATTR points pt:A +(nil) +``` + +Remove an unwanted element with [`VREM`]({{< relref "/commands/vrem" >}}) + +``` +> VADD points VALUES 2 0 0 pt:F +(integer) 1 +127.0.0.1:6379> VCARD points +(integer) 6 +127.0.0.1:6379> VREM points pt:F +(integer) 1 +127.0.0.1:6379> VCARD points +(integer) 5 +``` + +### Vector similarity search + +Use [`VSIM`]({{< relref "/commands/vsim" >}}) to rank the points in order of their vector distance from a sample point: + +``` +> VSIM points values 2 0.9 0.1 +1) "pt:E" +2) "pt:A" +3) "pt:D" +4) "pt:C" +5) "pt:B" +``` + +Find the four elements that are closest to point A and show their distance "scores": + +``` +> VSIM points ELE pt:A WITHSCORES COUNT 4 +1) "pt:A" +2) "1" +3) "pt:E" +4) "0.8535534143447876" +5) "pt:C" +6) "0.5" +7) "pt:D" +8) "0.5" +``` + +Add some JSON attributes and use +[filter expressions]({{< relref "/develop/data-types/vector-sets/filtered-search" >}}) +to include them in the search: + +``` +> VSETATTR points pt:A "{\"size\":\"large\",\"price\": 18.99}" +(integer) 1 +> VSETATTR points pt:B "{\"size\":\"large\",\"price\": 35.99}" +(integer) 1 +> VSETATTR points pt:C "{\"size\":\"large\",\"price\": 25.99}" +(integer) 1 +> VSETATTR points pt:D "{\"size\":\"small\",\"price\": 21.00}" +(integer) 1 +> VSETATTR points pt:E "{\"size\":\"small\",\"price\": 17.75}" +(integer) 1 + +# Return elements in order of distance from point A whose +# `size` attribute is `large`. +> VSIM points ELE pt:A FILTER '.size == "large"' +1) "pt:A" +2) "pt:C" +3) "pt:B" + +# Return elements in order of distance from point A whose size is +# `large` and whose price is greater than 20.00. +> VSIM points ELE pt:A FILTER '.size == "large" && .price > 20.00' +1) "pt:C" +2) "pt:B" +``` + +## More information + +See the other pages in this section to learn more about the features +and performance parameters of vector sets. diff --git a/static/images/vecsets/VecSetExamplePoints.drawio.svg b/static/images/vecsets/VecSetExamplePoints.drawio.svg new file mode 100644 index 0000000000..4b4483f4ea --- /dev/null +++ b/static/images/vecsets/VecSetExamplePoints.drawio.svg @@ -0,0 +1,4 @@ + + + +
1
-1
1
-1
A
B
C
D
E
 \ No newline at end of file