Adding vector search to an application usually means adopting a new client library and a new query language on top of the SQL your team already knows. TiDB takes a different approach. Vector storage and search use familiar MySQL syntax, extended with a native VECTOR data type and a small set of distance functions. If you can write a MySQL query, you only need to learn those additions to store and search vectors in TiDB.
How TiDB Solves the Second-Query-Language Problem
A dedicated vector database usually ships its own client library and query syntax, separate from the SQL interface your application already speaks. TiDB avoids that split by extending its SQL parser and type system with a native VECTOR data type and distance functions such as VEC_COSINE_DISTANCE. Vectors travel over the standard MySQL protocol as ordinary string literals, so existing MySQL drivers connect without changes. ORMs get vector support through lightweight integration packages rather than a separate vector database SDK.
The vector type and functions are TiDB extensions, not part of MySQL itself. Everything around them is SQL your team already writes: CREATE TABLE, INSERT, SELECT, ORDER BY, and LIMIT.
Dify, the open-source LLM app development platform, consolidated nearly half a million database containers into a single TiDB Cloud deployment. It now runs vector search, knowledge graphs, and operational data in one system.
Setting Up TiDB for Vector Search
Vector search is available on TiDB Cloud Starter, TiDB Cloud Essential, TiDB Cloud Dedicated, and TiDB Self-Managed. On Dedicated and Self-Managed, the cluster must run TiDB v8.4.0 or later, and v8.5.0 or later is recommended.
The quickest path is TiDB Cloud Starter. Create a cluster, connect with any MySQL client or driver, and start creating vector columns right away. No separate client library is required.
Creating and Querying Vector Data in TiDB
Create a table with a vector column the same way you would create any other table, specifying a dimension that matches your embedding model:
CREATE TABLE vector_table (
id INT PRIMARY KEY,
doc TEXT,
embedding VECTOR(1536)
);Insert rows the same way you would insert any other row, passing the embedding as a vector literal:
-- Vectors are truncated for readability.
-- Supply all 1536 values, or the insert fails on a dimension mismatch.
INSERT INTO vector_table (id, doc, embedding) VALUES
(1, 'TiDB is a distributed SQL database.', '[0.01, 0.02, 0.03, ...]'),
(2, 'TiFlash is the columnar storage engine.', '[0.04, 0.02, 0.01, ...]'),
(3, 'TiKV is the row-based storage engine.', '[0.02, 0.05, 0.01, ...]');Query by similarity by ordering on VEC_COSINE_DISTANCE and limiting the result count:
SELECT id, doc, VEC_COSINE_DISTANCE(embedding, '[0.01, 0.02, 0.03, ...]') AS distance
FROM vector_table
ORDER BY VEC_COSINE_DISTANCE(embedding, '[0.01, 0.02, 0.03, ...]')
LIMIT 3;Without an index, this query compares the query vector against every row. Results are exact, but the query slows down as the table grows. For larger tables, add an HNSW index on the vector column:
CREATE TABLE vector_table_indexed (
id INT PRIMARY KEY,
doc TEXT,
embedding VECTOR(1536),
VECTOR INDEX idx_embedding ((VEC_COSINE_DISTANCE(embedding)))
);The vector index runs on TiFlash, TiDB’s columnar engine. Defining the index in CREATE TABLE, as above, creates the TiFlash replica automatically. To add an index to an existing table that has no TiFlash replica, create the replica first with ALTER TABLE vector_table SET TIFLASH REPLICA 1; and then run CREATE VECTOR INDEX.
The optimizer uses the index only when the query orders by the same distance function the index was built with, in ascending order, with a LIMIT clause. Vector indexes currently support cosine and L2 distance. A WHERE filter applied before the distance sort prevents index use, so run the vector search in a subquery and filter its results instead.
Index results are approximate. TiDB’s documentation reports recall generally above 90%, which suits most retrieval workloads but can differ from the exact results of an unindexed query.
Apart from the VECTOR type, the VEC_ functions, and the VECTOR INDEX clause, every statement here is SQL a MySQL developer already writes.
FAQ
Do I need a separate vector database to use TiDB’s VECTOR type?
- No: vector columns live in the same tables as your relational data
- Vectors and relational rows share one SQL interface and one transactional boundary
- No sync pipeline between a vector store and your primary database
What SQL functions does TiDB provide for vector search?
- VEC_COSINE_DISTANCE and VEC_L2_DISTANCE, both supported by vector indexes
- VEC_NEGATIVE_INNER_PRODUCT and VEC_L1_DISTANCE for other similarity metrics
- Utility functions such as VEC_DIMS and VEC_L2_NORM
- Standard ORDER BY and LIMIT for nearest-neighbor queries
Can I use my existing MySQL ORM or driver with TiDB’s vector columns?
- Drivers: yes, vectors travel as string literals over the standard MySQL protocol
- Python ORMs need a small integration package: tidb-vector for SQLAlchemy and peewee, django-tidb[vector] for Django
- LangChain and LlamaIndex have official TiDB vector integrations
- No separate vector-database SDK is required
What embedding dimension should I use?
- Match the dimension your embedding model produces, for example 1536 for OpenAI’s text-embedding-3-small
- TiDB vector columns support up to 16,383 dimensions
- Declare the dimension explicitly, as in VECTOR(1536), because vector indexes require a fixed dimension
Query Vectors Without Learning a New System
TiDB stores vectors as a native SQL data type. You create, insert, and query vector data with the CREATE TABLE, INSERT, and SELECT syntax your team already knows, plus a VECTOR type and a few distance functions. Sign up for TiDB Cloud Starter and try the examples in this guide against your own data.
