Skip to content

docs: add ModeVectorSet to hosted OpenAPI - #48

Merged
Code0987 merged 1 commit into
mainfrom
docs/hosted-openapi-vecset
Sep 6, 2026
Merged

docs: add ModeVectorSet to hosted OpenAPI#48
Code0987 merged 1 commit into
mainfrom
docs/hosted-openapi-vecset

Conversation

@Code0987

@Code0987 Code0987 commented Sep 6, 2026

Copy link
Copy Markdown
Owner

Summary

Fill the gap in the existing hosted docs (Swagger UI at https://code0987.github.io/supercache/ and http://<admin>/docs).

Cache OpenAPI listed ModeVectorSet in the mode table but had no VAdd / VRem / VSim / VCard / VDim / VEmb pages.

  • Add those six RPCs + schemas on the Cache gRPC tab
  • sc examples (sc -keyspace vectorset vadd …)
  • Caps: dim 2–256, 512 members, metric cosine/l2/ip
  • Matching section in docs/API.md
  • KV examples use cacheonly instead of demo
  • Spec version 0.13.0

Source of truth is api/openapi/ (embedded on the node). docs/api/ is the static copy. Pages deploys from api/openapi + pkg/admin/docsui on merge to main.

Release

  • This PR should not cut a release

Test plan

  • go test ./api/openapi ./pkg/admin
  • After merge: GitHub Pages Docs workflow + /docs Vector tab on a node

Notes for reviewers

Docs only. No data-path change.

Cache Swagger was listing VAdd/VSim in the mode table with no RPC
pages. Add the six VectorSet operations, schemas, sc examples, and
the matching API.md section. Point examples at cacheonly/vectorset.
@github-actions

github-actions Bot commented Sep 6, 2026

Copy link
Copy Markdown

SuperCache bench vs main

Both sides ran once on this same GitHub runner (main, then this PR). Not a merge gate.

Baseline: 830420d (2026-09-06T12:46:05Z) → this run: 830420d (2026-09-06T12:45:19Z)

scbench smoke

cell ops/s (main → PR) Δ ops/s p50 p99
get/hit n=1 c=1 uniform 8591 → 8658 +0.8% 116µs → 116µs 194µs → 199µs
get/hit n=1 c=10 uniform 32926 → 33899 +3.0% 274µs → 265µs 840µs → 818µs
get/hit n=3 c=10 uniform 38639 → 38330 -0.8% 227µs → 229µs 904µs → 912µs
miss/miss-cacheonly n=1 c=1 uniform 8488 → 8503 +0.2% 116µs → 117µs 218µs → 213µs
miss/miss-cacheonly n=1 c=10 uniform 34779 → 34761 -0.0% 260µs → 259µs 840µs → 848µs
set/put n=1 c=1 uniform 8299 → 8120 -2.2% 118µs → 119µs 213µs → 292µs
set/put n=1 c=10 uniform 32190 → 32254 +0.2% 278µs → 278µs 878µs → 877µs

Δ ops/s: green-ish is higher throughput. Latency: lower is better.

go test -bench (ns/op)

benchmark ns/op (main → PR) Δ allocs/op
BenchmarkEngineDelete 778 → 803 +3.2% 6 → 6
BenchmarkEngineGetHit 1211 → 1541 +27.3% worse 15 → 15
BenchmarkEngineGetHitParallel 1244 → 1371 +10.2% 15 → 15
BenchmarkEngineGetMissCacheOnly 913 → 906 -0.8% 14 → 14
BenchmarkEngineGetMissCacheOnlyParallel 686 → 655 -4.5% 14 → 14
BenchmarkEngineGetMissLoadThrough 1722 → 1622 -5.8% 24 → 24
BenchmarkEngineGetMissLoadThroughParallel 1973 → 1904 -3.5% 23 → 23
BenchmarkEnginePut 1667 → 1651 -1.0% 18 → 18
BenchmarkEnginePutParallel 1499 → 1440 -3.9% 18 → 18
BenchmarkStoreBitSet 112 → 113 +0.9% 1 → 1
BenchmarkStoreCGetHit 72 → 73 +0.2% 0 → 0
BenchmarkStoreCIncr 102 → 102 +0.4% 1 → 1
BenchmarkStoreCMSIncr 120 → 126 +4.7% 0 → 0
BenchmarkStoreCMSIncrN 120 → 121 +0.8% 0 → 0
BenchmarkStoreGeoAdd 9572 → 9577 +0.1% 2 → 2
BenchmarkStoreGeoPosHit 88 → 88 -0.0% 0 → 0
BenchmarkStoreGeoPosMiss 87 → 91 +4.3% 0 → 0
BenchmarkStoreGetHit 295 → 296 +0.5% 2 → 2
BenchmarkStoreGetHitParallel 348 → 379 +8.9% 2 → 2
BenchmarkStoreHGetHit 95 → 91 -4.3% 1 → 1
BenchmarkStoreHGetMiss 85 → 85 +0.6% 0 → 0
BenchmarkStoreHLLAdd 100 → 100 +0.2% 0 → 0
BenchmarkStoreHSet 10606 → 10600 -0.1% 3 → 3
BenchmarkStoreJsonSet 26294 → 26757 +1.8% 207 → 207
BenchmarkStorePut 304 → 311 +2.3% 2 → 2
BenchmarkStorePutParallel 357 → 358 +0.3% 2 → 2
BenchmarkStoreSetAdd 9289 → 9259 -0.3% 2 → 2
BenchmarkStoreSetContainsHit 87 → 88 +0.7% 0 → 0
BenchmarkStoreSetContainsMiss 84 → 84 +0.0% 0 → 0
BenchmarkStoreTopKAdd 1009 → 1105 +9.5% 20 → 20
BenchmarkStoreVAdd 109151 → 110927 +1.6% 512 → 513
BenchmarkStoreVSim 89605 → 104168 +16.3% 530 → 530
BenchmarkStoreZAdd 10002 → 9715 -2.9% 2 → 2
BenchmarkStoreZScoreHit 94 → 86 -8.0% 0 → 0
BenchmarkStoreZScoreMiss 86 → 87 +1.2% 0 → 0

Posted by CI bench job. Not a merge gate.

@Code0987
Code0987 merged commit d9d8ffc into main Sep 6, 2026
2 checks passed
@Code0987
Code0987 deleted the docs/hosted-openapi-vecset branch September 6, 2026 12:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant