{"id":17896,"date":"2026-10-02T13:18:29","date_gmt":"2026-10-02T20:18:29","guid":{"rendered":"https:\/\/www.pingcap.com\/?post_type=article&p=17896"},"modified":"2026-10-02T13:35:02","modified_gmt":"2026-10-02T20:35:02","slug":"unleashing-the-power-of-mysql-with-vector-columns-in-tidb","status":"publish","type":"article","link":"https:\/\/www.pingcap.com\/ko\/article\/unleashing-the-power-of-mysql-with-vector-columns-in-tidb\/","title":{"rendered":"How to Add Vector Search to a MySQL Application with TiDB"},"content":{"rendered":"\n

Adding vector search to an application that runs on MySQL usually means standing up a separate vector database next to it, then keeping the two in sync for one new feature. TiDB<\/a> offers a simpler path. It’s a MySQL-compatible distributed SQL database with a native VECTOR data type and HNSW index. Move your MySQL workload to TiDB and your embeddings live in the same tables as your relational data, queried with the same SQL.<\/p>\n\n\n\n

<\/span>What Is a Vector Column in TiDB?<\/span><\/h2>\n\n\n\n

A vector column in TiDB is a table column declared with the VECTOR data type and a fixed dimension, stored in the same table as your other relational columns. Set the dimension to match your embedding model’s output size so TiDB can validate inserts and build an index on the column. A 1536-dimension column, the size produced by several common embedding models, looks like this:<\/p>\n\n\n\n

CREATE TABLE documents (\n    id INT PRIMARY KEY,\n    content TEXT,\n    embedding VECTOR(1536)\n);<\/code><\/pre>\n\n\n\n
There is no separate vector table type and no separate vector database to run. The vector column sits in a regular TiDB table alongside your other columns.<\/p>\n\n\n\n
<\/span>Why Not Use a Separate Vector Database?<\/span><\/h2>\n\n\n\n
Running a dedicated vector database alongside MySQL means two systems to operate, two consistency models, and a sync job to keep them aligned. With TiDB, vectors are a data type in the same database as your relational data. You get vector support through SQL functions and a vector index, and you query it with the same drivers and connection you already use.<\/p>\n\n\n\n
TiDB is MySQL-compatible, which matters here because your existing drivers, ORMs, and most of your application queries work against it with few or no changes. Moving to TiDB is still a migration, so plan for it the way you would any database move. Once you’re on TiDB, adding vector search is a schema change rather than a new service.<\/p>\n\n\n\n
Dify<\/a>, the open-source LLM app development platform, took this approach in production. Its team consolidated nearly half a million database containers into a single TiDB Cloud deployment that stores documents, vectors, chat histories, and relational data together, queried through SQL.<\/p>\n\n\n\n
<\/span>Creating a Vector Column and Index in TiDB<\/span><\/h2>\n\n\n\n
Vector indexes in TiDB use HNSW and are built on TiFlash replicas. If you define the index when you create the table, TiDB creates the TiFlash replica for you:<\/p>\n\n\n\n
CREATE TABLE documents_indexed (\n    id INT PRIMARY KEY,\n    content TEXT,\n    embedding VECTOR(1536),\n    VECTOR INDEX idx_embedding ((VEC_COSINE_DISTANCE(embedding)))\n);<\/code><\/pre>\n\n\n\n
To add vector search to a table you already have, add the column, create a TiFlash replica, then add the index:<\/p>\n\n\n\n
ALTER TABLE documents ADD COLUMN embedding VECTOR(1536);\nALTER TABLE documents SET TIFLASH REPLICA 1;\nALTER TABLE documents ADD VECTOR INDEX idx_embedding ((VEC_COSINE_DISTANCE(embedding))) USING HNSW;<\/code><\/pre>\n\n\n\n
On TiDB Self-Managed, the cluster needs TiFlash nodes deployed before you can build a vector index.<\/p>\n\n\n\n
Query for the nearest neighbors with ORDER BY<\/code> on the distance function and a LIMIT<\/code>:<\/p>\n\n\n\n
SELECT id, content, VEC_COSINE_DISTANCE(embedding, '[0.01, 0.02, 0.03, ...]') AS distance\nFROM documents_indexed\nORDER BY distance\nLIMIT 5;<\/code><\/pre>\n\n\n\n
The index is only used for this pattern: ascending order on the same distance function the index was built with, plus a LIMIT<\/code>. Ordering by a different distance function, or descending, falls back to a full scan. Filters in the same WHERE<\/code> clause can also stop the index from being used. The vector search index docs<\/a> cover how to combine filters with indexed search and how to check index usage with EXPLAIN<\/code>.<\/p>\n\n\n\n
<\/span>FAQ<\/span><\/h2>\n\n\n\n
Can I add a vector column to an existing table in TiDB?<\/strong><\/h3>\n\n\n\n
Yes. Add it with ALTER TABLE<\/code> the same way you would add any other column.<\/p>\n\n\n\n