llama-index-vector-stores-shannonbase

A LlamaIndex VectorStore backed by MySQL 9's native VECTOR type. If your data already lives in MySQL, you can do retrieval without standing up a separate vector database.

It works against the three things that share the same VECTOR / STRING_TO_VECTOR / DISTANCE surface: ShannonBase (open-source "MySQL for AI"), self-hosted MySQL 9, and MySQL HeatWave.

This is the LlamaIndex sibling of langchain-shannonbase. Same storage engine underneath, wired to LlamaIndex's node and query model so it drops into a LlamaIndex pipeline instead of a LangChain one.

Install

pip install "llama-index-vector-stores-shannonbase[mysql]"

Leave off [mysql] if you only want the offline in-memory backend for tests.

Usage

from llama_index.core import VectorStoreIndex, StorageContext
from llama_index.core.schema import TextNode
from llama_index.vector_stores.shannonbase import ShannonBaseVectorStore

store = ShannonBaseVectorStore(
    table="documents",
    host="127.0.0.1", port=3306, user="root", password="", database="rag",
)

# with an index and your embed model of choice
storage = StorageContext.from_defaults(vector_store=store)
index = VectorStoreIndex.from_documents(documents, storage_context=storage)
retriever = index.as_retriever(similarity_top_k=3)
retriever.retrieve("what's the return policy?")

The table is created on the first write, with an embedding VECTOR(n) column sized to your embedding model, and a FULLTEXT index on the text column for hybrid search.

What's supported

• add, delete(ref_doc_id), and query
• Query modes: DEFAULT (vector), MMR (diverse results), and HYBRID (vector + MySQL FULLTEXT keyword matching, fused by reciprocal rank)
• Metadata filters: EQ, NE, GT, GTE, LT, LTE, IN, NIN (combined with AND; OR and nested filters aren't supported yet)
• cosine (default), dot, and euclidean metrics via metric=...

For very large tables there's the same approximate IVF index as the LangChain package, reachable through the underlying store (store.client).

Notes on scale

By default search is an exact DISTANCE scan (100% recall), which is fine into the low millions of vectors. On MySQL HeatWave you get its automatic HNSW vector index for free on these queries. On ShannonBase or self-hosted MySQL, build the app-side IVF index for approximate search at scale.

Backend is shared with langchain-shannonbase

The _sql, _store, _filter, and _ivf modules are copied verbatim from langchain-shannonbase so both packages behave identically at the storage layer. scripts/check_backend_sync.py fails if they drift.

License

MIT