openclaw/skills/tidb-sql/references/vector.md

title
TiDB Vector SQL (Types, Functions, Indexes)

TiDB Vector SQL (Types, Functions, Indexes)

Feature gate

• Vector data types and functions require TiDB v8.4.0+ (v8.5.0+ recommended for self-managed/dedicated deployments).
• Confirm with SELECT VERSION();.

Data types

• VECTOR: variable dimension (cannot build a vector index on it)
• VECTOR(D): fixed dimension D (required for vector index)

Example:

CREATE TABLE embedded_documents (
  id INT PRIMARY KEY,
  document TEXT,
  embedding VECTOR(3)
);

Insert vector literals as strings:

INSERT INTO embedded_documents VALUES (1, 'dog', '[1,2,1]');

Distance functions (common)

• VEC_COSINE_DISTANCE(v1, v2)
• VEC_L2_DISTANCE(v1, v2)
• (Also exists: VEC_L1_DISTANCE, VEC_NEGATIVE_INNER_PRODUCT)

Example query (exact scan):

SELECT id, document, VEC_COSINE_DISTANCE(embedding, '[1,2,3]') AS distance
FROM embedded_documents
ORDER BY distance
LIMIT 10;

Cast / parsing helpers

• VEC_FROM_TEXT('[...]') - string -> vector
• VEC_AS_TEXT(vec) - vector -> string
• CAST('[...]' AS VECTOR) - string -> vector

Tip: If you compare vector constants, cast explicitly to avoid string-based comparisons.

Vector index (HNSW) essentials

Prerequisites / constraints:

• Requires TiFlash nodes (and TiFlash replica for the table).
• Cannot be PRIMARY KEY or UNIQUE.
• Single vector column only (no composite vector+other-column index).
• Must use the same distance function in both index definition and query ordering.

Create index at table creation time:

CREATE TABLE foo (
  id INT PRIMARY KEY,
  embedding VECTOR(3),
  VECTOR INDEX idx_embedding ((VEC_COSINE_DISTANCE(embedding)))
);

Create index on an existing table:

CREATE VECTOR INDEX idx_embedding ON foo ((VEC_COSINE_DISTANCE(embedding))) USING HNSW;
-- or:
ALTER TABLE foo ADD VECTOR INDEX idx_embedding ((VEC_COSINE_DISTANCE(embedding))) USING HNSW;

Query pattern to use the ANN index:

• Use ORDER BY VEC_COSINE_DISTANCE(...) ASC LIMIT <K> (Top-K must be present)
• Desc order or mismatched distance function prevents index usage

Validate index usage:

EXPLAIN SELECT * FROM foo
ORDER BY VEC_COSINE_DISTANCE(embedding, '[1,2,3]')
LIMIT 10;
SHOW WARNINGS;