zvec-r-bindings

R bindings for the zvec vector database.

Quick start

remotes::install_github("keneo/zvec-r-bindings/rszvec")

library(rszvec)
rszvec_install()   # one-time

col <- rszvec_open("/tmp/my_collection", dim = 4)

rszvec_add(col, "doc_1", c(0.1, 0.2, 0.3, 0.4))
rszvec_add(col, "doc_2", c(0.2, 0.3, 0.4, 0.1))

rszvec_search(col, c(0.4, 0.3, 0.3, 0.1), n = 5)
#      id score
# 1 doc_2  0.30
# 2 doc_1  0.23

Contents

R Package	Who it's for	What you get	Example
rzvec	R users who want the full zvec API	Thin, idiomatic R wrappers over every zvec Python class and method	example
rszvec	R users who want minimal ceremony	5-function API; results come back as plain data.frames	example

Platform support

Determined by the zvec Python package, which ships binary wheels for:

Platform	x86_64	arm64
Linux	✅	✅
macOS	—	✅
Windows	—	—

Python 3.10, 3.11, and 3.12 are supported. Python 3.9 and earlier are not.

Docker smoke test

The docker/ folder contains the Docker image definition and R scripts that run inside it, for validating the packages on Linux ARM64.

File	Purpose
docker/Dockerfile	Base image with R deps and Python venv baked in (layer-cached)
docker/test.R	Full smoke test: installs packages from GitHub, runs end-to-end
docker/test-all.R	Installs rzvec/rszvec from mounted repo, runs all 82 tests
docker/ci-test.R	No-install variant used by CI after packages are pre-installed
run-tests-in-docker.sh	Builds the image (layer cache decides what to rebuild), then runs test-all.R
run-tests-local.sh	Runs both test suites directly (no Docker; uses local renv + venv)

Run tests in Docker (Linux, clean environment):

./run-tests-in-docker.sh            # uses layer cache — only rebuilds changed layers
./run-tests-in-docker.sh --rebuild   # full rebuild, ignores Docker cache

Run tests locally (faster, uses your installed packages):

./run-tests-local.sh

Build the base image manually:

docker build -t play-zvec-test -f docker/Dockerfile .

Run the full smoke test (installs from GitHub each time):

docker run --rm play-zvec-test Rscript /dev/stdin < docker/test.R

Or mount the repo to avoid a GitHub download:

docker run --rm -v $(pwd):/repo play-zvec-test Rscript /repo/docker/test.R

Acknowledgments

• zvec - The underlying vector database
• Alibaba Proxima - The core vector search engine

License

MIT