How kwon-evan/mariadb-vector works
Project type and purpose
• This is an open-source Python library (“MariaDB Vector”) that extends SQLAlchemy/SQLModel to support MariaDB’s VECTOR column type and vector‐based operations (distance calculations and searches).
• It acts as a plugin/adapter layer between a user’s Python ORM models and a MariaDB database with vector support.
File structure
• Top level: configuration (pyproject.toml, pdm.lock), GitHub workflows, README, license.
• src/mariadb_vector: the library itself, containing:
• functions.py – helpers for building SQL expressions (vec_from_seq, vec_distance, etc.)
• vector.py – a custom SQLAlchemy Column type wrapper around MariaDB’s VECTOR.
README for additional insights
• The README shows typical usage:
• A SQLModel table with a VECTOR column via Field(sa_column=Column(Vector(n))).
• Insert records with embedding lists.
• Query by ordering on vec_distance_* functions.
• Dependencies: SQLModel (built on SQLAlchemy), MariaDB connector/engine.
Elements
• Clear labels: “User App”, “MariaDB-Vector Library: Vector Type”, “MariaDB-Vector Library: Distance Functions”, “SQLModel/SQLAlchemy”, “MariaDB DB”
– App → Library (import/use)
– App → SQLModel/SQLAlchemy
– SQLModel/SQLAlchemy → MariaDB (SQL execution)
– MariaDB → SQLModel/SQLAlchemy (results) → App
– Rectangles for code components (App, Library modules, ORM)
1. USER LAYER (top)
• Python code: define Item model, call session.add, session.exec
2. ORMs & EXTENSION LAYER (middle)
• SQLModel/SQLAlchemy core
• MariaDB-Vector plugin
– Vector Type (handles Column metadata)
– Vector Functions (expr generators)
3. DATABASE LAYER (bottom)
• MariaDB Server with VECTOR column
• Underlying storage & vector search engine
• PDM/pip (dependency install)
• GitHub Actions (format.yml, release.yml)