Update Vector Set docs to match current behavior by tiagonapoli · Pull Request #2002 · microsoft/garnet

tiagonapoli · 2026-07-30T21:44:18Z

What

The Vector Set command documentation had drifted from the implementation. This updates website/docs/commands/vector-sets.md and one line of website/docs/commands/api-compatibility.md to match current behavior.

No product code is changed — documentation only.

How this was verified

Every statement below was checked against a locally built server on main (96d31943f) started with --enable-vector-set-preview, driven over raw RESP — not inferred from reading code.

Corrections

Quantization

Q8 and BIN became functional in #1882 ("Add quantization tasks and calls into DiskANN"), but the docs still described them as rejected.

Documented	Actual
`Q8` / `BIN` "❌ Rejected — `ERR Unsupported quantization type`"	Both supported. That error string no longer exists anywhere in the codebase.
Default `Q8` "currently fails"	Works.
Quantizer list is `NOQUANT \| XPREQ8`	Also `Q8`, `BIN`, `XNOQUANT_U8`, `XNOQUANT_I8`, `XBIN_U8`, `XBIN_I8`; `XPREQ8` is a deprecated alias for `XNOQUANT_U8`.
`X*` quantizers "require `XB8` input"	They also accept `FP32` / `VALUES`, subject to byte-range validation.
`REDUCE` "not allowed with `XPREQ8`"	Rejected for all `XNOQUANT_` / `XBIN_`; works with `NOQUANT` / `Q8` / `BIN`.

Also added the VINFO quant-type string each token reports, and a note that Q8/BIN quantization is applied asynchronously (background table build, then backfill) — which is why results on small or newly created indexes are identical to NOQUANT.

Commands

Documented	Actual
`VEMB ... RAW` "parsed but not yet implemented — invoking it currently throws"	Implemented. Documented the 3-element reply (4 for `Q8`) and that the norm/range entries are placeholders.
`VSIM` "currently only supports RESP2"	RESP3 works. Returns a map keyed by element ID when `WITHSCORES`/`WITHATTRIBS` are set, with scores as RESP3 doubles.
`VDIM` returns "the dimension before any `REDUCE`"	Returns the reduced dimension when `REDUCE` is configured.
`VINFO` `reduced-dimensions` "same as `input-vector-dimensions` if no projection"	Returns `0`. Both worked examples updated.
`TYPE key` "currently reports `string`"	Reports `vectorset`.
Filter compile errors "yield an empty result set rather than a server-side error"	Returns `ERR Compiling filter failed`.

api-compatibility.md: dropped the now-inaccurate "(no RAW)" qualifier on VEMB.

Known issues documented (not fixed here)

Two real behaviors are now called out in the docs so users stop being surprised by them. Both are pre-existing and unrelated to any change in this PR — happy to split them into separate issues.

VCARD / VISMEMBER / VLINKS / VRANDMEMBER / VSETATTR close the connection. The docs claimed they "return +OK regardless of arguments". They actually validate arguments and keys correctly — :0 / nil for a missing key, WRONGTYPE for another type — but when invoked against an existing Vector Set key they reach the default: arm in libs/server/Storage/Functions/MainStore/PrivateMethods.cs and throw ERR Garnet Exception: Unsupported operation on input, terminating the client connection.
VADD on an existing element ID duplicates instead of updating. It returns :1 (not :0), VINFO size grows by one, and VSIM can return the same element more than once. VEMB reads back the most recently written vector. Reproduces on every quantizer. The docs now recommend VREM before re-adding until this is fixed.

Testing

Documentation-only change; no tests added. Verified by exercising the documented commands and replies against a live server as described above.

The Vector Set command documentation had drifted from the implementation. Every change below was verified against a locally built server on main (96d3194) started with `--enable-vector-set-preview`. Quantization (#1882 enabled Q8/BIN): - `Q8` and `BIN` are supported, not rejected. The `ERR Unsupported quantization type` error they were documented to return no longer exists anywhere in the codebase. - The default quantizer (`Q8` when none is specified) works. - Documented the full token list, including the `XNOQUANT_*` / `XBIN_*` extensions and the `XPREQ8` deprecated alias, along with the `VINFO quant-type` string each one reports. - Documented that `Q8`/`BIN` quantization is applied asynchronously (background table build + backfill), so results on small or young indexes match `NOQUANT`. - The `X*` quantizers accept `FP32`/`VALUES` input, not only `XB8`, subject to byte-range validation. - `REDUCE` is rejected with the `X*` quantizers but works with `NOQUANT`/`Q8`/`BIN`. Commands: - `VEMB ... RAW` is implemented; documented its 3-element reply (4 for `Q8`) and that the norm/range values are placeholders. Also dropped the "(no `RAW`)" caveat in api-compatibility.md. - `VSIM` supports RESP3, returning a map keyed by element ID when `WITHSCORES`/`WITHATTRIBS` are set, with scores as RESP3 doubles. - `VDIM` returns the reduced dimension when `REDUCE` is configured, not the pre-`REDUCE` input dimension. - `VINFO` `reduced-dimensions` is `0` when no projection is configured, not a copy of `input-vector-dimensions`. Updated both examples. - `TYPE` reports `vectorset`, not `string`. - A filter that fails to compile returns `ERR Compiling filter failed` rather than an empty result set. Known-issue callouts added: - `VCARD`/`VISMEMBER`/`VLINKS`/`VRANDMEMBER`/`VSETATTR` do not return `+OK` as documented. They validate arguments and keys correctly (`:0`/nil for missing keys, `WRONGTYPE` for other types) but throw `ERR Garnet Exception: Unsupported operation on input` and close the connection when invoked against an existing Vector Set key. - `VADD` on an element ID that already exists duplicates it rather than replacing it: it returns `:1`, `size` grows, and `VSIM` can return the element more than once. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Updates Garnet’s Vector Set (preview) documentation to reflect the current server behavior (quantizers, replies, and edge-case behaviors), without changing product code.

Changes:

Refreshes VADD/quantization docs (supported quantizers, default behavior, REDUCE compatibility, async Q8/BIN behavior).
Updates command docs for VEMB (RAW), VSIM (RESP3 behavior), VDIM, VINFO, TYPE, and filter compile error behavior; documents known preview issues.
Removes the outdated “(no RAW)” qualifier for VEMB in the API compatibility matrix.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
website/docs/commands/vector-sets.md	Major Vector Set documentation refresh to match current preview behavior, including quantization, replies, and documented known issues.
website/docs/commands/api-compatibility.md	Adjusts VECTOR SET `VEMB` entry to no longer claim `RAW` is unavailable.

Comments suppressed due to low confidence (1)

website/docs/commands/vector-sets.md:125

The “Vector Input Forms” table under VADD documents XB8 but does not mention the newer XU8/XI8 tokens that are also accepted. Adding them (and noting that XB8 is a deprecated alias for XU8) would keep the docs aligned with the current parser behavior.

         [CAS]
         [NOQUANT | Q8 | BIN | XNOQUANT_U8 | XNOQUANT_I8 | XBIN_U8 | XBIN_I8]
         [EF n] [SETATTR attr] [M n]

+- RESP2: integer reply. Currently always `:1` on a successful insert (see the warning below).
 - RESP3: boolean `true` / `false`.


@@ -120,7 +120,9 @@ Insert a vector with the given element ID into a Vector Set, creating the index

 ```bash
 VADD key [REDUCE dim] (FP32 vector | XB8 vector | VALUES n v1 ... vN) element


tiagonapoli · 2026-07-30T23:13:34Z

  `ERR M must be an integer between 4 and 4096`, `ERR EF must be an integer between 1 and 1000000`,
  `ERR vector exceeds maximum of 65536 dimensions`, `ERR Vector Set key cannot be empty`.

+:::warning


remove this comment

tiagonapoli · 2026-07-30T23:14:43Z


-Treat these as no-ops in preview builds — do not rely on their return value.
+:::warning
+Argument validation and key lookup are wired up, so these commands behave sensibly when the key is missing or


I don't know if this is really needed

Copilot AI review requested due to automatic review settings July 30, 2026 21:44

Copilot started reviewing on behalf of tiagonapoli July 30, 2026 21:45 View session

Copilot AI reviewed Jul 30, 2026

View reviewed changes

tiagonapoli commented Jul 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Update Vector Set docs to match current behavior - #2002

Update Vector Set docs to match current behavior#2002
tiagonapoli wants to merge 1 commit into
mainfrom
tiagonapoli/update-vector-set-docs

tiagonapoli commented Jul 30, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

tiagonapoli Jul 30, 2026

Uh oh!

tiagonapoli Jul 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		- RESP2: integer reply. Currently always `:1` on a successful insert (see the warning below).
		- RESP3: boolean `true` / `false`.

		@@ -120,7 +120,9 @@ Insert a vector with the given element ID into a Vector Set, creating the index

		```bash
		VADD key [REDUCE dim] (FP32 vector \| XB8 vector \| VALUES n v1 ... vN) element

Uh oh!

Conversation

tiagonapoli commented Jul 30, 2026

What

How this was verified

Corrections

Quantization

Commands

Known issues documented (not fixed here)

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

tiagonapoli Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

tiagonapoli Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants