SPTAG: Microsoft's ANN Library for Tree and Graph Vector Search

What SPTAG solves, and who it is aimed at

SPTAG answers one question: given a query vector, which stored vectors are nearest under L2 or cosine distance? The README states the library assumes samples are represented as vectors and compared by those two metrics. That is the whole contract. It is not a database, not a service mesh, and not a metadata store.

The intended user is an engineer who has vectors already and needs an index plus a serving path. The README names two deployment shapes: an index builder and a searcher as basic modules, and a distributed option that searches over multiple machines. Microsoft Research and Microsoft Bing released it, and the README shows the lineage: SPFresh at SOSP 2023, VBASE at OSDI 2023. If you are evaluating this for a production recommendation or image retrieval system, that research backing is the reason it exists. If you want a hosted vector database with a REST API, this is not that.

Trees seed the graph: the SPTAG-KDT and SPTAG-BKT mechanism

SPTAG ships two index families. SPTAG-KDT pairs a kd-tree with a relative neighborhood graph. SPTAG-BKT pairs a balanced k-means tree with the same kind of graph. The README is explicit about the trade-off: the kd-tree variant is cheaper to build, the balanced k-means variant is more accurate on very high-dimensional data. That is a real design decision, not marketing. The README explains why: balanced k-means trees replace kd-trees to avoid inaccurate distance bound estimation when dimensionality is high.

The search flow is two-stage. A query first walks the space partition trees to collect several seed points, then those seeds start a search inside the relative neighborhood graph. Tree search and graph search are conducted iteratively rather than once each. This is the NGS approach the README cites as inspiration. The practical consequence is that build time and query time are coupled through the tree: a cheap tree gives you worse seeds and the graph has to work harder to recover recall.

Building SPTAG from source with CMake

The repository has no published GitHub releases, so the documented path is a source build. The README lists three requirements: swig 4.0.2 or newer, cmake 3.12.0 or newer, and boost 1.67.0 or newer. Because the repository uses Git LFS, the README suggests skipping the large file download during clone:

set GIT_LFS_SKIP_SMUDGE=1
git clone --recurse-submodules https://github.com/microsoft/SPTAG

On Linux the README then walks through three third-party components before SPTAG itself. SPDK is compiled first, then isal-l_crypto, then RocksDB, which is configured with RTTI, jemalloc and snappy enabled. Only after those does the SPTAG build run:

mkdir build
cd build && cmake -DSPDK=OFF -DROCKSDB=OFF .. && make

Note the flags: the documented SPTAG build turns SPDK and RocksDB off. The output is a Release folder containing all build targets. The README says to run SPTAGTest (or Test.exe) from that folder to confirm the tests pass. On Windows the equivalent is cmake -A x64 -DSPDK=OFF -DROCKSDB=OFF .. followed by compiling ALL_BUILD in Visual Studio 2019 or later, and there is a separate WindowsInstallation document for binaries.

Docker is the shortest route if you do not want to assemble the toolchain yourself:

docker build -t sptag .

The Dockerfile starts from Ubuntu 20.04, installs gcc-8 and g++-8, pulls in the boost libraries, tbb, swig and cmake, installs numpy through pip, and sets PYTHONPATH to /app/Release. The README states the resulting container holds binaries in /app/Release/. For a first real use, the README points to docs/GettingStart.md for detailed usage and to docs/Tutorial.ipynb for an end-to-end Python wrapper tutorial that builds a vector search online service. Parameter tuning lives in docs/Parameters.md. The README gives no build time for SPDK and RocksDB.

Where the setup goes wrong

The most obvious limitation is the third-party chain. A plain SPTAG build is not self-contained: SPDK, isal-l_crypto and RocksDB are compiled separately, and the README pins specific compiler versions inside those steps (gcc-9 for SPDK, gcc-7 for RocksDB, gcc-8 in the Dockerfile). Those are three different compiler versions across one dependency tree. Any environment with a single system compiler will need adjustment, and the README does not document a workaround.

The second limitation is that the documented cmake invocation sets both SPDK and RocksDB to OFF after the README has you compile them. The README does not say what those components add or how to build SPTAG with them enabled; it only shows the disabled form. That gap is worth resolving before you plan around those features.

The third is packaging. setup.py defaults the version to 0.0.0.dev when SPTAG_RELEASE is unset, and the docstring describes the release path as an explicit environment variable plus a wheel build per platform. With no published releases, there is no stable version number to pin.

SPTAG next to DiskANN and SPANN

DiskANN is a fair comparison because both are graph-based ANN systems. The difference is in what sits above the graph. DiskANN's public identity is a single graph index designed to run on a machine with SSD-backed storage. SPTAG's README describes a hybrid: space partition trees for seeding, a relative neighborhood graph for refinement, and two tree choices with a stated accuracy-versus-build-cost trade-off. If your vectors are high-dimensional and build budget is the constraint, the SPTAG-KDT and SPTAG-BKT split gives you a knob DiskANN's single index does not present in the same way.

SPANN is not cited in the README; its research references are SPFresh, on incremental in-place update for billion-scale vector search, and VBASE, on unifying vector similarity search and relational queries.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-11-02. That is a current codebase, but the repository has no published releases, so there is no tagged version to upgrade between. Upgrades therefore mean tracking main and rebuilding. Given the third-party chain, that is not a cheap operation: a change in the SPDK, isal-l_crypto or RocksDB steps can invalidate a working toolchain, and the README documents compiler versions per component rather than a single supported configuration.

The licence is MIT, which is permissive and imposes no copyleft obligation on your own code. It does not resolve the licences of the bundled third parties. SPDK, isal-l_crypto, RocksDB and boost each carry their own terms, and the README does not summarise them. If you redistribute a container built from the provided Dockerfile, check those separately. This is not legal advice.

Editorial conclusion

Adopt SPTAG if you need an ANN index you can build from source in C++, with a Python wrapper for prototyping and distributed serving listed as a highlight. Do not adopt it if you want a single pip install, a stable released package, or an index format you can swap between libraries. Before committing, verify that your toolchain has swig 4.0.2 or newer, cmake 3.12.0 or newer and boost 1.67.0 or newer, and decide up front whether you need the SPDK and RocksDB components at all, because the plain CMake path disables both with -DSPDK=OFF -DROCKSDB=OFF.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. microsoft/SPTAG on GitHub
4. README