TiDB Vector Python Client

0.0.15 verified Fri May 01 auth: no python

A Python client for TiDB Vector, enabling vector similarity search and storage with TiDB's vector support. Current version 0.0.15, actively developed with weekly releases.

pip install tidb-vector

Common errors

error ModuleNotFoundError: No module named 'tidb_vector' ↓

cause Package not installed.

fix

Run 'pip install tidb-vector'

error pymysql.err.OperationalError: (1045, "Access denied for user '...'@'...' (using password: NO)") ↓

cause Missing or incorrect password when connecting to TiDB.

fix

Set the TIDB_PASSWORD environment variable or provide password in connection string.

error sqlalchemy.exc.ProgrammingError: (pymysql.err.ProgrammingError) (1146, "Table '...' doesn't exist") ↓

cause Table does not exist; TiDBVectorClient creates it automatically only if 'auto_create_table' is True.

fix

Set auto_create_table=True when creating TiDBVectorClient, or create the table manually before querying.

Warnings

breaking TiDB Vector requires TiDB version >= 7.1.0 with vector support enabled. Earlier versions or standard MySQL will fail. ↓

fix Ensure TiDB cluster version is 7.1.0 or higher and the vector feature is enabled.

gotcha The 'distance_strategy' parameter must match the column definition; changing it after table creation does not alter the stored index. ↓

fix Drop and recreate the table if you need to change distance strategy.

deprecated The 'vector_table' parameter was renamed to 'table_name' in version 0.0.13. Using 'vector_table' may still work but is deprecated. ↓

fix Use 'table_name' instead of 'vector_table'.

Imports

TiDBVectorClient

wrong

from tidb_vector import TiDBVectorClient

correct

from tidb_vector.integrations import TiDBVectorClient

Common mistake: TiDBVectorClient is in integrations submodule

TiDBVectorStore

wrong

from tidb_vector import TiDBVectorStore

correct

from tidb_vector.integrations import TiDBVectorStore

LangChain integration is also in integrations

Quickstart

Initialize TiDBVectorClient, insert vectors, and perform similarity search.

import os
from tidb_vector.integrations import TiDBVectorClient

# TiDB connection parameters (use env vars for auth)
host = os.environ.get('TIDB_HOST', '127.0.0.1')
port = int(os.environ.get('TIDB_PORT', '4000'))
user = os.environ.get('TIDB_USER', 'root')
password = os.environ.get('TIDB_PASSWORD', '')
database = os.environ.get('TIDB_DATABASE', 'test')

# Create vector table and client
connection_string = f'mysql+pymysql://{user}:{password}@{host}:{port}/{database}'
client = TiDBVectorClient(
    table_name='vector_demo',
    connection_string=connection_string,
    vector_dimension=3,
    distance_strategy='cosine'
)

# Insert vectors
ids = ['id1', 'id2', 'id3']
vectors = [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0], [7.0, 8.0, 9.0]]
metadata = [
    {'text': 'first'},
    {'text': 'second'},
    {'text': 'third'}
]
client.insert(ids=ids, vectors=vectors, metadata=metadata)

# Similarity search
results = client.query(query_vector=[1.0, 2.0, 3.0], top_k=2)
for r in results:
    print(r.id, r.distance, r.metadata)