TiDB vector search doc (#18502)

pingcap · Oct 22, 2024 · 65ad55d · 65ad55d
1 parent 4ffae15
commit 65ad55d
Show file tree

Hide file tree

Showing 22 changed files with 3,424 additions and 3 deletions.
diff --git a/TOC.md b/TOC.md
@@ -77,6 +77,24 @@
       - [Follower Read](/develop/dev-guide-use-follower-read.md)
       - [Stale Read](/develop/dev-guide-use-stale-read.md)
     - [HTAP 查询](/develop/dev-guide-hybrid-oltp-and-olap-queries.md)
+  - 向量搜索
+    - [概述](/vector-search-overview.md)
+    - 快速入门
+      - [使用 SQL 开始向量搜索](/vector-search-get-started-using-sql.md)
+      - [使用 Python 开始向量搜索](/vector-search-get-started-using-python.md)
+    - 集成
+      - [集成概览](/vector-search-integration-overview.md)
+      - AI 框架
+        - [LlamaIndex](/vector-search-integrate-with-llamaindex.md)
+        - [Langchain](/vector-search-integrate-with-langchain.md)
+      - 嵌入模型/服务
+        - [Jina AI](/vector-search-integrate-with-jinaai-embedding.md)
+      - ORM 库
+        - [SQLAlchemy](/vector-search-integrate-with-sqlalchemy.md)
+        - [peewee](/vector-search-integrate-with-peewee.md)
+        - [Django](/vector-search-integrate-with-django-orm.md)
+    - [优化搜索性能](/vector-search-improve-performance.md)
+    - [使用限制](/vector-search-limitations.md)
   - 事务
     - [概览](/develop/dev-guide-transaction-overview.md)
     - [乐观事务和悲观事务](/develop/dev-guide-optimistic-and-pessimistic-transaction.md)
@@ -876,6 +894,7 @@
       - [日期和时间类型](/data-type-date-and-time.md)
       - [字符串类型](/data-type-string.md)
       - [JSON 类型](/data-type-json.md)
+      - [向量数据类型](/vector-search-data-types.md)
     - 函数与操作符
       - [函数与操作符概述](/functions-and-operators/functions-and-operators-overview.md)
       - [表达式求值的类型转换](/functions-and-operators/type-conversion-in-expression-evaluation.md)
@@ -889,6 +908,7 @@
       - [加密和压缩函数](/functions-and-operators/encryption-and-compression-functions.md)
       - [锁函数](/functions-and-operators/locking-functions.md)
       - [信息函数](/functions-and-operators/information-functions.md)
+      - [向量函数和操作符](/vector-search-functions-and-operators.md)
       - JSON 函数
         - [概览](/functions-and-operators/json-functions.md)
         - [创建 JSON 的函数](/functions-and-operators/json-functions/json-functions-create.md)
@@ -909,6 +929,7 @@
       - [TiDB 特有的函数](/functions-and-operators/tidb-functions.md)
       - [Oracle 与 TiDB 函数和语法差异对照](/oracle-functions-to-tidb.md)
     - [聚簇索引](/clustered-indexes.md)
+    - [向量索引](/vector-search-index.md)
     - [约束](/constraints.md)
     - [生成列](/generated-columns.md)
     - [SQL 模式](/sql-mode.md)

diff --git a/br/backup-and-restore-overview.md b/br/backup-and-restore-overview.md
@@ -120,6 +120,7 @@ TiDB 支持将数据备份到 Amazon S3、Google Cloud Storage (GCS)、Azure Blo
 | 全局临时表 | | 确保使用 BR v5.3.0 及以上版本进行备份和恢复，否则会导致全局临时表的表定义错误。 |
 | TiDB Lightning 物理导入模式| |上游数据库使用 TiDB Lightning 物理导入模式导入的数据，无法作为数据日志备份下来。推荐在数据导入后执行一次全量备份，细节参考[上游数据库使用 TiDB Lightning 物理导入模式导入数据的恢复](/faq/backup-and-restore-faq.md#上游数据库使用-tidb-lightning-物理导入模式导入数据时为什么无法使用日志备份功能)。|
 | TiCDC | | BR v8.2.0 及以上版本：如果在恢复的目标集群有 [CheckpointTS](/ticdc/ticdc-architecture.md#checkpointts) 早于 BackupTS 的 Changefeed，BR 会拒绝执行恢复。BR v8.2.0 之前的版本：如果在恢复的目标集群有任何活跃的 TiCDC Changefeed，BR 会拒绝执行恢复。 |
+| 向量搜索 | | 确保使用 BR v8.4.0 及以上版本进行备份与恢复。不支持将带有[向量数据类型](/vector-search-data-types.md)的表恢复至 v8.4.0 之前的 TiDB 集群。 |
 
 ### 版本间兼容性
 

diff --git a/dm/dm-overview.md b/dm/dm-overview.md
@@ -60,6 +60,10 @@ tiup install dm dmctl
 
     - DM 不支持 MySQL 8.0 的新特性 binlog 事务压缩 [Transaction_payload_event](https://dev.mysql.com/doc/refman/8.0/en/binary-log-transaction-compression.html)。使用 binlog 事务压缩有导致上下游数据不一致的风险。
 
++ 向量类型数据同步
+
+    - DM 不支持迁移或同步 MySQL 9.0 的向量数据类型到 TiDB。
+
 ## Contributing
 
 欢迎参与 DM 开源项目并万分感谢您的贡献，可以查看 [CONTRIBUTING.md](https://github.com/pingcap/tiflow/blob/master/dm/CONTRIBUTING.md) 了解更多信息。

diff --git a/media/vector-search/embedding-search.png b/media/vector-search/embedding-search.png
diff --git a/ticdc/ticdc-compatibility.md b/ticdc/ticdc-compatibility.md
@@ -65,3 +65,11 @@ TiCDC 从 v5.3.0 开始支持[全局临时表](/temporary-tables.md#全局临时
 你需要使用 TiCDC v5.3.0 及以上版本同步全局临时表到下游。低于该版本，会导致表定义错误。
 
 如果 TiCDC 的上游集群包含全局临时表，下游集群也必须是 TiDB 5.3.0 及以上版本，否则同步报错。
+
+### 向量数据类型兼容性说明
+
+从 v8.4.0 开始，TiCDC 支持同步包含[向量数据类型](/vector-search-data-types.md)的表到下游（实验特性）。
+
+当下游为 Kafka 或者存储服务（如：Amazon S3、GCS、Azure Blob Storage 和 NFS）时，TiCDC 会将向量数据类型转为字符串类型进行写入。
+
+当下游为不支持向量类型的 MySQL 兼容数据库时，涉及向量类型的 DDL 事件无法成功写入。在这种情况下，请在 `sink-url` 中添加配置参数 `has-vector-type=true`，然后 TiCDC 会将向量数据类型转为 `LONGTEXT` 类型进行写入。
diff --git a/tiflash-upgrade-guide.md b/tiflash-upgrade-guide.md
@@ -119,6 +119,10 @@ TiFlash 在 v6.2.0 将数据格式升级到 V3 版本，因此，从 v5.x 或 v6
 
 从 v7.4 开始，为了减少数据整理时产生的读、写放大，PageStorage V3 数据整理时逻辑进行了优化，导致底层部分存储文件名发生改动。因此，升级 TiFlash 到 v7.4 或以上版本后，不支持原地降级到之前的版本。
 
+## 从 v7.x 升级至 v8.4 或以上版本
+
+从 v8.4 开始，为了支持[向量搜索功能](/vector-search-index.md)，TiFlash 底层存储格式发生改动。因此，升级 TiFlash 到 v8.4 或以上版本后，不支持原地降级到之前的版本。
+
 **测试环境及特殊回退需求下的对策**
 
 如果在测试环境下或者其他有特殊回退需求的场景下，可以强制缩容 TiFlash 节点，并重新同步数据。操作步骤详见[缩容 TiFlash 节点](/scale-tidb-using-tiup.md#缩容-tiflash-节点)。
diff --git a/tiflash/tiflash-configuration.md b/tiflash/tiflash-configuration.md
@@ -68,9 +68,11 @@ delta_index_cache_size = 0
     ## DTFile 储存文件格式
     ## * format_version = 2 v6.0.0 以前版本的默认文件格式
     ## * format_version = 3 v6.0.0 及 v6.1.x 版本的默认文件格式，具有更完善的检验功能
-    ## * format_version = 4 v7.3.0 及以前版本的默认文件格式，优化了写放大问题，同时减少了后台线程消耗。
-    ## * format_version = 5 v7.4.0 及以后版本的默认文件格式（从 v7.3.0 开始引入），该格式可以合并小文件从而减少了物理文件数量。
-    # format_version = 5
+    ## * format_version = 4 v6.2.0 ~ v7.3.0 的默认文件格式，优化了写放大问题，同时减少了后台线程消耗。
+    ## * format_version = 5 v7.4.0 ~ v8.3.0 的默认文件格式（从 v7.3.0 开始引入），该格式可以合并小文件从而减少了物理文件数量。
+    ## * format_version = 6 从 v8.4.0 开始引入，部分支持了向量索引的构建与存储。
+    ## * format_version = 7 v8.4.0 及以后版本的默认文件格式 (从 v8.4.0 开始引入)，该格式用于支持向量索引的构建与存储。
+    # format_version = 7
 
     [storage.main]
     ## 用于存储主要的数据，该目录列表中的数据占总数据的 90% 以上。

diff --git a/vector-search-data-types.md b/vector-search-data-types.md
@@ -0,0 +1,245 @@
+---
+title: 向量数据类型
+summary: 本文介绍 TiDB 的向量数据类型。
+---
+
+# 向量数据类型 (Vector)
+
+向量指的是一组浮点数序列，例如 `[0.3, 0.5, -0.1, ...]`。针对 AI 应用中大量使用到的嵌入向量 (vector embedding) 数据，TiDB 专门提供了向量数据类型，以便高效地存储和访问这些数据。
+
+> **警告：**
+>
+> 该功能目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。
+
+目前支持的向量数据类型包括：
+
+- `VECTOR`：存储一组单精度浮点数 (Float) 向量，向量维度可以是任意的。
+- `VECTOR(D)`：存储一组单精度浮点数 (Float) 向量，向量维度固定为 `D`。
+
+与使用 [`JSON`](/data-type-json.md) 类型相比，使用向量类型具有以下优势：
+
+- 支持向量索引。可以通过构建[向量搜索索引](/vector-search-index.md)加速查询。
+- 可指定维度。指定一个固定维度后，不符合维度的数据将被阻止写入到表中。
+- 存储格式更优。向量数据类型针对向量数据进行了特别优化，在空间利用和性能效率上都优于 `JSON` 类型。
+
+## 语法
+
+可以使用以下格式的字符串来表示一个数据类型为向量的值：
+
+```sql
+'[<float>, <float>, ...]'
+```
+
+示例：
+
+```sql
+CREATE TABLE vector_table (
+    id INT PRIMARY KEY,
+    embedding VECTOR(3)
+);
+
+INSERT INTO vector_table VALUES (1, '[0.3, 0.5, -0.1]');
+
+INSERT INTO vector_table VALUES (2, NULL);
+```
+
+插入不符合语法的字符串作为向量数据时，TiDB 会报错：
+
+```sql
+[tidb]> INSERT INTO vector_table VALUES (3, '[5, ]');
+ERROR 1105 (HY000): Invalid vector text: [5, ]
+```
+
+下面的示例中 `embedding` 向量列的维度在建表时已经定义为 `3`，因此当插入其他维度的向量数据时，TiDB 会报错：
+
+```sql
+[tidb]> INSERT INTO vector_table VALUES (4, '[0.3, 0.5]');
+ERROR 1105 (HY000): vector has 2 dimensions, does not fit VECTOR(3)
+```
+
+关于向量数据类型支持的所有函数和操作符，可参阅[向量函数与操作符](/vector-search-functions-and-operators.md)。
+
+关于向量搜索索引的更多信息，可参阅[向量搜索索引](/vector-search-index.md)。
+
+## 混合存储不同维度的向量
+
+省略 `VECTOR` 类型中的维度参数后，就可以在同一列中存储不同维度的向量：
+
+```sql
+CREATE TABLE vector_table (
+    id INT PRIMARY KEY,
+    embedding VECTOR
+);
+
+INSERT INTO vector_table VALUES (1, '[0.3, 0.5, -0.1]'); -- 插入一个 3 维向量
+INSERT INTO vector_table VALUES (2, '[0.3, 0.5]');       -- 插入一个 2 维向量
+```
+
+需要注意的是，存储了不同维度向量的列不支持构建[向量搜索索引](/vector-search-index.md)，因为只有维度相同的向量之间才能计算向量距离。
+
+## 比较
+
+向量数据支持[比较运算符](/vector-search-functions-and-operators.md#扩展的内置函数和运算符)，例如 `=`、`!=`、`<`、`>`、`<=` 和 `>=` 等。关于向量数据类型支持的所有函数和操作符，可参阅[向量函数与操作符](/vector-search-functions-and-operators.md)。
+
+比较向量数据类型时，TiDB 会以向量中的各个元素为单位进行依次比较，如：
+
+- `[1] < [12]`
+- `[1,2,3] < [1,2,5]`
+- `[1,2,3] = [1,2,3]`
+- `[2,2,3] > [1,2,3]`
+
+当两个向量的维度不同时，TiDB 采用字典序 (Lexicographical Order) 进行比较，具体规则如下：
+
+- 两个向量中的各个元素逐一进行数值比较。
+- 当遇到第一个不同的元素时，它们之间的数值比较结果即为两个向量之间的比较结果。
+- 如果一个向量是另一个向量的前缀，那么维度小的向量**小于**维度大的向量。例如，`[1,2,3] < [1,2,3,0]`。
+- 长度相同且各个元素相同的两个向量**相等**。
+- 空向量**小于**任何非空向量。例如，`[] < [1]`。
+- 两个空向量**相等**。
+
+在进行向量比较时，请使用[显式转换](#类型转换-cast)将向量数据从字符串转换为向量类型，以避免 TiDB 直接基于字符串进行比较：
+
+```sql
+-- 因为给出的数据实际上是字符串，因此 TiDB 会按字符串进行比较
+[tidb]> SELECT '[12.0]' < '[4.0]';
++--------------------+
+| '[12.0]' < '[4.0]' |
++--------------------+
+|                  1 |
++--------------------+
+1 row in set (0.01 sec)
+
+-- 显式转换为向量类型，从而按照向量的比较规则进行正确的比较
+[tidb]> SELECT VEC_FROM_TEXT('[12.0]') < VEC_FROM_TEXT('[4.0]');
++--------------------------------------------------+
+| VEC_FROM_TEXT('[12.0]') < VEC_FROM_TEXT('[4.0]') |
++--------------------------------------------------+
+|                                                0 |
++--------------------------------------------------+
+1 row in set (0.01 sec)
+```
+
+## 运算
+
+向量数据类型支持算术运算 `+` 和 `-`，对应的是两个向量以元素为单位进行的加法和减法。不支持对不同维度向量进行算术运算，执行这类运算会遇到报错。
+
+以下是一些示例：
+
+```sql
+[tidb]> SELECT VEC_FROM_TEXT('[4]') + VEC_FROM_TEXT('[5]');
++---------------------------------------------+
+| VEC_FROM_TEXT('[4]') + VEC_FROM_TEXT('[5]') |
++---------------------------------------------+
+| [9]                                         |
++---------------------------------------------+
+1 row in set (0.01 sec)
+
+[tidb]> SELECT VEC_FROM_TEXT('[2,3,4]') - VEC_FROM_TEXT('[1,2,3]');
++-----------------------------------------------------+
+| VEC_FROM_TEXT('[2,3,4]') - VEC_FROM_TEXT('[1,2,3]') |
++-----------------------------------------------------+
+| [1,1,1]                                             |
++-----------------------------------------------------+
+1 row in set (0.01 sec)
+
+[tidb]> SELECT VEC_FROM_TEXT('[4]') + VEC_FROM_TEXT('[1,2,3]');
+ERROR 1105 (HY000): vectors have different dimensions: 1 and 3
+```
+
+## 类型转换 (Cast)
+
+### 向量与字符串之间的转换
+
+可以使用以下函数在向量和字符串之间进行转换：
+
+- `CAST(... AS VECTOR)`：将字符串类型转换为向量类型
+- `CAST(... AS CHAR)`：将向量类型转换为字符串类型
+- `VEC_FROM_TEXT`：将字符串类型转换为向量类型
+- `VEC_AS_TEXT`：将向量类型转换为字符串类型
+
+出于易用性考虑，如果你使用的函数只支持向量数据类型（例如，向量相关距离函数），那么你也可以直接传入符合格式要求的字符串数据，TiDB 会进行隐式转换：
+
+```sql
+-- VEC_DIMS 只接受向量类型，因此你可以直接传入字符串类型，TiDB 会隐式转换为向量类型：
+[tidb]> SELECT VEC_DIMS('[0.3, 0.5, -0.1]');
++------------------------------+
+| VEC_DIMS('[0.3, 0.5, -0.1]') |
++------------------------------+
+|                            3 |
++------------------------------+
+1 row in set (0.01 sec)
+
+-- 也可以使用 VEC_FROM_TEXT 显式地将字符串转换为向量类型后传递给 VEC_DIMS 函数：
+[tidb]> SELECT VEC_DIMS(VEC_FROM_TEXT('[0.3, 0.5, -0.1]'));
++---------------------------------------------+
+| VEC_DIMS(VEC_FROM_TEXT('[0.3, 0.5, -0.1]')) |
++---------------------------------------------+
+|                                           3 |
++---------------------------------------------+
+1 row in set (0.01 sec)
+
+-- 也可以使用 CAST(... AS VECTOR) 进行显式转换：
+[tidb]> SELECT VEC_DIMS(CAST('[0.3, 0.5, -0.1]' AS VECTOR));
++----------------------------------------------+
+| VEC_DIMS(CAST('[0.3, 0.5, -0.1]' AS VECTOR)) |
++----------------------------------------------+
+|                                            3 |
++----------------------------------------------+
+1 row in set (0.01 sec)
+```
+
+当你使用的运算符或函数接受多种数据类型时，TiDB 不会进行隐式转换，请先显式地将字符串类型转换为向量类型后，再传递给这些运算符或函数。例如，进行比较运算前，需要显式地将字符串转换为向量类型，否则 TiDB 将会按照字符串类型进行比较，而非按照向量类型进行比较：
+
+```sql
+-- 传入的类型是字符串，因此 TiDB 会按字符串进行比较：
+[tidb]> SELECT '[12.0]' < '[4.0]';
++--------------------+
+| '[12.0]' < '[4.0]' |
++--------------------+
+|                  1 |
++--------------------+
+1 row in set (0.01 sec)
+
+-- 转换为向量类型，以便使用向量类型的比较规则：
+[tidb]> SELECT VEC_FROM_TEXT('[12.0]') < VEC_FROM_TEXT('[4.0]');
++--------------------------------------------------+
+| VEC_FROM_TEXT('[12.0]') < VEC_FROM_TEXT('[4.0]') |
++--------------------------------------------------+
+|                                                0 |
++--------------------------------------------------+
+1 row in set (0.01 sec)
+```
+
+向量也可以显式地转换为字符串。以使用 `VEC_AS_TEXT()` 函数为例：
+
+```sql
+-- 字符串首先被隐式地转换成向量，然后被显式地转为字符串，因而返回了一个规范化的字符串格式：
+[tidb]> SELECT VEC_AS_TEXT('[0.3,     0.5,  -0.1]');
++--------------------------------------+
+| VEC_AS_TEXT('[0.3,     0.5,  -0.1]') |
++--------------------------------------+
+| [0.3,0.5,-0.1]                       |
++--------------------------------------+
+1 row in set (0.01 sec)
+```
+
+如需了解其他转换函数，请参阅[向量函数和操作符](/vector-search-functions-and-operators.md)。
+
+### 向量与其他数据类型之间的转换
+
+目前 TiDB 无法直接在向量和其他数据类型（如 `JSON`）之间进行转换，但你可以在执行的 SQL 语句中使用字符串作为中间类型进行转换。
+
+需要注意的是，对于存储在表中的向量数据类型列，无法通过 `ALTER TABLE ... MODIFY COLUMN ...` 转换为其他数据类型。
+
+## 使用限制
+
+有关向量类型的限制，请参阅[向量搜索限制](/vector-search-limitations.md)以及[向量搜索索引的使用限制](/vector-search-index.md#使用限制)。
+
+## MySQL 兼容性
+
+向量数据类型只在 TiDB 中支持，MySQL 不支持。
+
+## 另请参阅
+
+- [向量函数和操作符](/vector-search-functions-and-operators.md)
+- [向量搜索索引](/vector-search-index.md)