AI-Powered Search with TiDB Vector Search

Keyword search only matches exact words, so it misses the query that means the same thing but says it differently. Most teams fix this by bolting on a dedicated vector database next to the one they already run, which means two systems to keep in sync, two consistency models, and a pipeline that can silently drift out of date. 티DB Vector Search removes that second system. It stores embeddings as a native SQL data type inside the same distributed, HTAP database that already holds your transactional and analytical data.

What Is TiDB Vector Search?

TiDB Vector Search lets you query by the meaning of your data instead of by exact keyword match. It stores vector embeddings, numeric representations of text, images, audio, or video, in a native VECTOR column, then finds the nearest matches by measuring the distance between vectors. Because it lives inside TiDB, the same distributed SQL database used for transactional and analytical workloads, there is no separate vector store to provision or keep synchronized.

TiDB Vector Search supports two related patterns:

• Semantic search: find records whose meaning is close to a query, even when the wording differs.
• Similarity search: find items that resemble a given item, useful for recommendations and content discovery.

A TiDB vector column stores up to 16,383 dimensions, which covers the embedding sizes produced by most current models.

How TiDB Vector Search Works

Building a semantic search feature on TiDB follows three steps:

1. Embedding generation. Convert your source data (text, images, or other content) into vectors using an embedding model.
2. Vector storage. Store the resulting vectors in a TiDB table alongside your existing structured data.
3. Similarity search. Query with a distance function such as vec_cosine_distance to find the nearest vectors to a given query embedding, using an HNSW (Hierarchical Navigable Small World) index for fast approximate nearest-neighbor lookups at scale.

How TiDB Solves the Data-Silo Problem

A dedicated vector database can answer “which items are similar,” but it cannot join that answer against your live transactional data without crossing a system boundary, which means an extra network hop, an extra consistency question, and an extra service to operate. TiDB closes that gap with its HTAP architecture: TiKV handles row-based transactional storage, TiFlash handles columnar analytical storage, and vector columns live in the same tables as everything else. A single SQL query can filter on a WHERE clause, join across tables, and rank by vector distance, all inside one ACID transaction boundary. See the HTAP architecture diagram for how TiKV and TiFlash divide the work.

AI-native companies already run this pattern in production. Kimi, the agent platform built by Moonshot AI, runs its persistent agent infrastructure on TiDB Cloud specifically because a single unified data stack means agents never have to reason across separate database boundaries. The same principle applies to vector search: storing embeddings next to the transactional records they describe means an application can filter, join, and rank in one query instead of stitching results together from two systems after the fact.

Setting Up TiDB Vector Search

Vector search is available on TiDB Cloud Starter, TiDB Cloud Essential, TiDB Cloud Dedicated, and TiDB Self-Managed (self-managed deployments need TiDB v8.4.0 or later; v8.5.0 or later is recommended). To get started:

1. Sign up: Create a TiDB Cloud account.
2. Create a cluster: Follow the quickstart guide to set up a TiDB Cloud Starter cluster. Vector search is available by default, with no separate enablement step or region restriction.
3. Connect: From the Clusters page, select your cluster, click Connect, and choose General to get your connection parameters.

Example: Semantic Search with TiDB

Here is a working example using OpenAI embeddings and the peewee ORM.

Prerequisites

• Python 3.8 or later
• A TiDB Cloud Starter cluster with vector search enabled

Setting up the environment

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install openai peewee pymysql tidb_vector

Example code

import os
from openai import OpenAI
from peewee import Model, MySQLDatabase, TextField
from tidb_vector.peewee import VectorField

# Initialize OpenAI client
client = OpenAI(api_key=os.environ.get('OPENAI_API_KEY'))
embedding_model = "text-embedding-3-small"
embedding_dimensions = 1536

# Connect to TiDB
db = MySQLDatabase(
    'test',
    user=os.environ.get('TIDB_USERNAME'),
    password=os.environ.get('TIDB_PASSWORD'),
    host=os.environ.get('TIDB_HOST'),
    port=4000,
    ssl_verify_cert=True,
    ssl_verify_identity=True
)

# Sample documents
documents = [
    "TiDB is an open-source distributed SQL database that supports Hybrid Transactional and Analytical Processing (HTAP) workloads.",
    "TiFlash is the columnar storage engine that makes TiDB an HTAP database.",
    "TiKV is a distributed, transactional key-value store with ACID compliance."
]

# Define model
class DocModel(Model):
    text = TextField()
    embedding = VectorField(dimensions=embedding_dimensions)

    class Meta:
        database = db
        table_name = "doc_test"

# Set up the table
db.connect()
db.create_tables([DocModel])

# Generate embeddings and insert
embeddings = [r.embedding for r in client.embeddings.create(input=documents, model=embedding_model).data]
data_source = [{"text": doc, "embedding": emb} for doc, emb in zip(documents, embeddings)]
DocModel.insert_many(data_source).execute()

# Query example
question = "What is TiKV?"
question_embedding = client.embeddings.create(input=question, model=embedding_model).data[0].embedding
related_docs = (
    DocModel
    .select(DocModel.text, DocModel.embedding.cosine_distance(question_embedding).alias("distance"))
    .order_by(SQL("distance"))
    .limit(3)
)

for doc in related_docs:
    print(doc.distance, doc.text)

db.close()

If you would rather not call an embedding API by hand, TiDB also supports native auto-embedding and direct integrations with LangChain and LlamaIndex, so you can insert plain text and let TiDB generate the embeddings for you.

자주 묻는 질문

What data types can TiDB Vector Search handle?

• Text, images, audio, video, and any other data type that can be converted into an embedding
• Vectors up to 16,383 dimensions per column
• Standard SQL data types alongside vector columns in the same table

Does TiDB Vector Search replace a dedicated vector database?

• For most applications, yes: TiDB stores vectors, transactional data, and analytical data in one system
• No separate service, sync pipeline, or second consistency model to maintain
• Vector similarity, filtering, and joins run in a single SQL query

What embedding models does TiDB support?

• Any model that outputs a fixed-length vector, including OpenAI, Cohere, and Jina AI
• Native auto-embedding for common providers, so you can skip manual API calls
• Framework integrations with LangChain and LlamaIndex

How many dimensions can a TiDB vector store?

• Up to 16,383 dimensions per vector column
• Covers the output size of most current embedding models
• HNSW indexing keeps nearest-neighbor queries fast at that dimensionality

Build Semantic Search Without a Second Database

TiDB Vector Search gives you semantic and similarity search inside the same distributed SQL database that already runs your transactional and analytical workloads, so you query embeddings and structured data together instead of stitching results across systems. Sign up for TiDB Cloud Starter and try vector search with your own data today.