mariadb-vector

Implements vector search and RAG patterns using MariaDB native VECTOR columns and indexes.

28|115|Updated Jan 28, 2025
One-click install
npx skills add https://github.com/mariadb-corporation/mariadb-docs --skill mariadb-vector-mariadb-corporation
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: mariadb-vector
Source: https://github.com/mariadb-corporation/mariadb-docs/tree/main/agent-skills/topical/mariadb-vector
Command: npx skills add https://github.com/mariadb-corporation/mariadb-docs --skill mariadb-vector-mariadb-corporation

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Developers building semantic search or RAG applications with MariaDB often receive incorrect guidance (such as installing a pgvector-style extension) or write vector queries that silently fall back to full table scans. This Skill provides verified best practices for MariaDB's built-in vector support so queries use the HNSW index correctly. ## Core Features & Use Cases - Correct Vector Schema Design: Create tables with VECTOR(n) NOT NULL columns and VECTOR INDEX with explicit M and DISTANCE options tuned to your embedding model. - Optimized Query Patterns: Write nearest-neighbor queries with ORDER BY VEC_DISTANCE_*() plus LIMIT so the optimizer engages the vector index, and wrap threshold filters in subqueries. - End-to-End RAG Workflow: Chunk documents, embed them, store binary float32 vectors via the mariadb Python connector, and retrieve top-K context for LLM prompts, with integrations for LangChain, LlamaIndex, and Spring AI. - Use Case: You are building a documentation chatbot. Use this Skill to design the chunks table, insert embeddings as packed float32 bytes, and run a cosine-distance top-5 retrieval query that actually uses the index. ## Quick Start Ask the AI to create a MariaDB table with a 1536-dimension vector column and write a Python script that stores OpenAI embeddings and retrieves the five nearest chunks for a question.

Frequently Asked Questions about mariadb-vector

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a vector index in MariaDB?▼

Declare VECTOR INDEX (embedding) directly in CREATE TABLE, optionally with M and DISTANCE=euclidean or cosine options. The vector column must be NOT NULL, and MariaDB supports one vector index per table. No extension or plugin installation is needed since version 11.7.

How to write a nearest neighbor search query in MariaDB?▼

Use SELECT with ORDER BY VEC_DISTANCE_EUCLIDEAN(embedding, ?) or VEC_DISTANCE_COSINE and always include LIMIT. The MariaDB optimizer only uses the VECTOR INDEX when both the ORDER BY distance call and LIMIT are present; otherwise it performs a full table scan.

Does MariaDB require an extension like pgvector for vector search?▼

No. MariaDB has native built-in vector support since version 11.7, including the VECTOR type, VECTOR INDEX, and all VEC_* functions. Unlike PostgreSQL's pgvector, there is nothing to install, enable, or load.

Why is my MariaDB vector query doing a full table scan?▼

Full scans happen when LIMIT is missing, the distance function does not match the index's DISTANCE option, or the distance call is wrapped in an expression like 1.0 - VEC_DISTANCE_COSINE(...). Compute similarity scores in an outer SELECT instead.

Can I use MariaDB vector search with LangChain or LlamaIndex?▼

Yes. MariaDB Vector integrates with LangChain (pip install langchain-mariadb), LangChain.js, LangChain4j, LlamaIndex, and Spring AI. These frameworks handle VEC_FromText, VEC_DISTANCE, and LIMIT clauses automatically once you configure a connection string.

What are the limitations of MariaDB vector indexes?▼

MariaDB supports only one vector index per table, indexed columns must be NOT NULL, and there is no dot product distance function. Threshold queries with WHERE VEC_DISTANCE(...) < value always full-scan, so wrap an indexed top-K subquery and filter outside.