docs: add docs for vector search and vector functions (#237)

* add docs for vector

Author: niebayes

dir.yaml

@@ -248,6 +248,9 @@
         - title_en: Streaming Window Functions
           title_cn: 流式窗口函数
           path: sql-reference/streaming-window
+        - title_en: Vector Functions
+          title_cn: 向量函数
+          path: sql-reference/vector-functions
         #- title_en: String
         #  title_cn: 字符串函数
         #  path: sql-reference/string
@@ -285,6 +288,17 @@
 #      title_cn: 介绍
 #      path: edge2cloud/introduction
 
+- title_en: Vector Search
+  title_cn: 向量检索
+  collapsed: true
+  children:
+    - title_en: Vector Search Overview
+      title_cn: 向量检索概述
+      path: vector-search/overview
+    - title_en: Quick Start
+      title_cn: 快速上手
+      path: vector-search/quick-start
+
 - title_en: Key Value Data Model
   title_cn: Key-Value 存储
   collapsed: true

en_US/sql-reference/data-type.md

@@ -32,3 +32,8 @@
 |  -------------                    |----------------------------------------------------------------------------------   |
 | STRING                            | Utf8                                                                                |
 
+## Vector Type
+|  Name                             | Description                                                                         |
+|  -------------                    |----------------------------------------------------------------------------------   |
+| VECTOR                            | VECTOR(dim)，`dim` 代表向量的维度，取值范围为 [1, 16383]                                 |
+

en_US/sql-reference/vector-functions.md

@@ -0,0 +1,152 @@
+# 向量函数
+
+Datalayers 现在提供向量距离函数、向量数学计算函数。更多向量函数正在开发中。
+
+## 向量距离函数
+
+向量距离函数用于计算两个相同维度的向量之间的距离。目前提供以下向量距离函数：
+
+- `l2_distance`：L2 距离函数。
+- `cosine_distance`：余弦距离函数。
+- `dot_distance`：负内积距离函数。
+
+### L2 距离函数
+
+L2 距离，又称欧式距离，其计算公式为：
+
+$$
+\text{l2\_distance}(\mathbf{x}, \mathbf{y}) = \sqrt{\sum_{i=1}^n (x_i - y_i)^2}
+$$
+
+语法：
+
+```sql
+l2_distance(x, y)
+```
+
+示例：
+
+```sql
+# 计算两个向量之间的 L2 距离
+SELECT l2_distance([1.0, 1.0, 1.0], [1.0, 1.0, 2.5]);
+
+# 计算向量列 `embed` 与目标向量之间的 L2 距离
+SELECT l2_distance(embed, [1.0, 2.0, 3.0]) FROM t;
+
+# 根据向量列 `embed` 与目标向量之间的 L2 距离，对数据进行排序，并输出距离最近的一行数据
+SELECT * FROM t ORDER BY l2_distance(embed, [1.0, 2.0, 3.0]) LIMIT 1;
+```
+
+### 余弦距离函数
+
+计算公式为：
+
+$$
+\text{cosine\_distance}(\mathbf{x}, \mathbf{y}) = 1 - \frac{\mathbf{x} \cdot \mathbf{y}}{\|\mathbf{x}\|_2 \cdot \|\mathbf{y}\|_2} = 1 - \frac{\sum_{i=1}^n x_i y_i}{\sqrt{\sum_{i=1}^n x_i^2} \cdot \sqrt{\sum_{i=1}^n y_i^2}}
+$$
+
+语法：
+
+```sql
+cosine_distance(x, y)
+```
+
+示例：参考 L2 距离函数的示例。
+
+### 负内积距离函数
+
+向量的内积（Dot Product，又称 Inner Product），定义为两个向量逐个元素的乘积之和。负内积，则为内积的负。之所以使用负内积，
+是因为我们希望使得所有向量距离函数，均满足距离越小、向量相似度越大的关系。
+
+计算公式为：
+
+$$
+\text{dot\_distance}(\mathbf{x}, \mathbf{y}) = -\mathbf{x} \cdot \mathbf{y} = -\sum_{i=1}^n x_i y_i
+$$
+
+语法：
+
+```sql
+l2_distance(x, y)
+```
+
+示例：参考 L2 距离函数的示例。
+
+## 向量数学计算函数
+
+向量数学计算函数用于向量的一些数学性质。目前提供以下函数：
+
+- `dim`：维度函数，求解一个向量的维度，即向量中元素的数量。
+- `l2_norm`：L2 模函数，求解一个向量的 L2 模（或称 L2 范数）。
+- `l2_normalize`：L2 归一化函数，使用 L2 模对向量执行归一化。
+
+### 维度函数
+
+语法：
+
+```sql
+dim(x)
+```
+
+示例：
+
+```sql
+# 计算一个向量的维度，输出应为 3
+SELECT dim([1.0, 2.0, 3.0]);
+
+# 计算一个向量列中每个向量的维度
+SELECT dim(embed) FROM t;
+```
+
+### L2 模函数
+
+L2 模函数通常用于执行向量归一化，即将一个向量转换为模为 1 的单位向量，便于后续执行向量计算。一个向量的 L2 模的计算公式为：
+
+$$
+\text{l2\_norm}(\mathbf{x}) = \|\mathbf{x}\|_2 = \sqrt{\sum_{i=1}^n x_i^2}
+$$
+
+语法：
+
+```sql
+l2_norm(x)
+```
+
+示例：
+
+```sql
+# 计算一个向量的 L2 模
+SELECT l2_norm([1.0, 2.0, 3.0]);
+
+# 计算一个向量列中每个向量的 L2 模
+SELECT l2_norm(embed) FROM t;
+```
+
+### L2 归一化函数
+
+该函数使用 L2 模将向量转换为标准向量，即模长为 1 的单位向量。使用 L2 模的向量归一化公式为：
+
+$$
+\text{normalized\_vector} = \frac{\mathbf{x}}{\|\mathbf{x}\|_2} = \left[ \frac{x_1}{\sqrt{\sum x_i^2}}, \frac{x_2}{\sqrt{\sum x_i^2}}, ..., \frac{x_n}{\sqrt{\sum x_i^2}} \right]
+$$
+
+语法：
+
+```sql
+l2_normalize(x)
+```
+
+示例：
+
+```sql
+# 对一个向量执行归一化
+SELECT l2_normalize([1.0, 2.0, 3.0]);
+
+# 对一个向量列中的每个向量执行归一化
+SELECT l2_normalize(embed) FROM t;
+```
+
+## 注意事项
+
+- 向量函数只能作用与向量字面量或者向量类型的列。其中包含整型元素或浮点型元素的列表，都被视为合法的向量字面量。例如 `[1, 2, 3]` 与 `[1.0, 2.0, 3.0]` 等均合法。
+- 向量距离函数要求参与计算的两个参数（向量字面量或向量列）的维度相等。

en_US/vector/overview.md renamed to en_US/vector-search/overview.md

@@ -32,3 +32,8 @@
 |  -------------                    |----------------------------------------------------------------------------------   |
 | STRING                            | Utf8                                                                                |
 
+## Vector Type
+|  Name                             | Description                                                                         |
+|  -------------                    |----------------------------------------------------------------------------------   |
+| VECTOR                            | VECTOR(dim)，`dim` 代表向量的维度，取值范围为 [1, 16383]                                 |
+

zh_CN/vector/overview.md renamed to en_US/vector-search/quick-start.md

@@ -0,0 +1,152 @@
+# 向量函数
+
+Datalayers 现在提供向量距离函数、向量数学计算函数。更多向量函数正在开发中。
+
+## 向量距离函数
+
+向量距离函数用于计算两个相同维度的向量之间的距离。目前提供以下向量距离函数：
+
+- `l2_distance`：L2 距离函数。
+- `cosine_distance`：余弦距离函数。
+- `dot_distance`：负内积距离函数。
+
+### L2 距离函数
+
+L2 距离，又称欧式距离，其计算公式为：
+
+$$
+\text{l2\_distance}(\mathbf{x}, \mathbf{y}) = \sqrt{\sum_{i=1}^n (x_i - y_i)^2}
+$$
+
+语法：
+
+```sql
+l2_distance(x, y)
+```
+
+示例：
+
+```sql
+# 计算两个向量之间的 L2 距离
+SELECT l2_distance([1.0, 1.0, 1.0], [1.0, 1.0, 2.5]);
+
+# 计算向量列 `embed` 与目标向量之间的 L2 距离
+SELECT l2_distance(embed, [1.0, 2.0, 3.0]) FROM t;
+
+# 根据向量列 `embed` 与目标向量之间的 L2 距离，对数据进行排序，并输出距离最近的一行数据
+SELECT * FROM t ORDER BY l2_distance(embed, [1.0, 2.0, 3.0]) LIMIT 1;
+```
+
+### 余弦距离函数
+
+计算公式为：
+
+$$
+\text{cosine\_distance}(\mathbf{x}, \mathbf{y}) = 1 - \frac{\mathbf{x} \cdot \mathbf{y}}{\|\mathbf{x}\|_2 \cdot \|\mathbf{y}\|_2} = 1 - \frac{\sum_{i=1}^n x_i y_i}{\sqrt{\sum_{i=1}^n x_i^2} \cdot \sqrt{\sum_{i=1}^n y_i^2}}
+$$
+
+语法：
+
+```sql
+cosine_distance(x, y)
+```
+
+示例：参考 L2 距离函数的示例。
+
+### 负内积距离函数
+
+向量的内积（Dot Product，又称 Inner Product），定义为两个向量逐个元素的乘积之和。负内积，则为内积的负。之所以使用负内积，
+是因为我们希望使得所有向量距离函数，均满足距离越小、向量相似度越大的关系。
+
+计算公式为：
+
+$$
+\text{dot\_distance}(\mathbf{x}, \mathbf{y}) = -\mathbf{x} \cdot \mathbf{y} = -\sum_{i=1}^n x_i y_i
+$$
+
+语法：
+
+```sql
+l2_distance(x, y)
+```
+
+示例：参考 L2 距离函数的示例。
+
+## 向量数学计算函数
+
+向量数学计算函数用于向量的一些数学性质。目前提供以下函数：
+
+- `dim`：维度函数，求解一个向量的维度，即向量中元素的数量。
+- `l2_norm`：L2 模函数，求解一个向量的 L2 模（或称 L2 范数）。
+- `l2_normalize`：L2 归一化函数，使用 L2 模对向量执行归一化。
+
+### 维度函数
+
+语法：
+
+```sql
+dim(x)
+```
+
+示例：
+
+```sql
+# 计算一个向量的维度，输出应为 3
+SELECT dim([1.0, 2.0, 3.0]);
+
+# 计算一个向量列中每个向量的维度
+SELECT dim(embed) FROM t;
+```
+
+### L2 模函数
+
+L2 模函数通常用于执行向量归一化，即将一个向量转换为模为 1 的单位向量，便于后续执行向量计算。一个向量的 L2 模的计算公式为：
+
+$$
+\text{l2\_norm}(\mathbf{x}) = \|\mathbf{x}\|_2 = \sqrt{\sum_{i=1}^n x_i^2}
+$$
+
+语法：
+
+```sql
+l2_norm(x)
+```
+
+示例：
+
+```sql
+# 计算一个向量的 L2 模
+SELECT l2_norm([1.0, 2.0, 3.0]);
+
+# 计算一个向量列中每个向量的 L2 模
+SELECT l2_norm(embed) FROM t;
+```
+
+### L2 归一化函数
+
+该函数使用 L2 模将向量转换为标准向量，即模长为 1 的单位向量。使用 L2 模的向量归一化公式为：
+
+$$
+\text{normalized\_vector} = \frac{\mathbf{x}}{\|\mathbf{x}\|_2} = \left[ \frac{x_1}{\sqrt{\sum x_i^2}}, \frac{x_2}{\sqrt{\sum x_i^2}}, ..., \frac{x_n}{\sqrt{\sum x_i^2}} \right]
+$$
+
+语法：
+
+```sql
+l2_normalize(x)
+```
+
+示例：
+
+```sql
+# 对一个向量执行归一化
+SELECT l2_normalize([1.0, 2.0, 3.0]);
+
+# 对一个向量列中的每个向量执行归一化
+SELECT l2_normalize(embed) FROM t;
+```
+
+## 注意事项
+
+- 向量函数只能作用与向量字面量或者向量类型的列。其中包含整型元素或浮点型元素的列表，都被视为合法的向量字面量。例如 `[1, 2, 3]` 与 `[1.0, 2.0, 3.0]` 等均合法。
+- 向量距离函数要求参与计算的两个参数（向量字面量或向量列）的维度相等。

zh_CN/assets/vector-search-arch.png

@@ -0,0 +1,47 @@
+# 向量检索概述
+
+向量检索是一种在非结构化数据中进行快速近似搜索的技术。常见的非结构化数据，例如文档、图像、音频、视频等数据，作为向量嵌入（Vector Embedding）存储在数据库中。用户使用向量检索技术，在数据库中查找与给定的目标向量最相似的数条向量，以及这些向量所对应的元信息，最终交给上层应用执行业务操作。
+
+![向量检索框架](../assets/vector-search-arch.png)
+
+以电商搜索引擎业务为例，业务方使用嵌入模型（Embedding Model）将商品的名字、标签、描述、图片等统一转换为向量嵌入，存储到 Datalayers 等原生提供向量存储、向量检索的数据库中。用户在软件中搜索商品时，搜索词或图片被同一个嵌入模型转换为向量嵌入。软件后端将其作为目标向量，在数据库中进行检索。最终查找出与搜索词或图片最近似的一系列商品。
+
+与传统的全文搜索不同，向量检索并不使用关键词进行精确或模糊匹配，而是用向量距离近似度量语义相似度，从而实现高效的近似检索。
+
+## 为什么选择 Datalayers 向量检索
+
+- 原生向量类型：原生提供向量类型，支持高压缩率向量存储、高性能向量检索。
+- 混合检索：支持向量检索、以及向量检索与标量检索的混合检索。
+- 简单易用：原生 SQL 支持，兼容 MySQL 方言。
+- 多模态：提供时序、关系、流计算、日志等引擎，快速集成向量检索至任何业务场景。
+- 存算分离：计算和存储节点解耦，均可无限水平扩展，支持海量向量数据的存储和搜索。
+- 分布式：采用分布式架构，提供完备的容灾、备份、恢复策略。
+- 数据安全：支持高性能、强隐私的数据加密。
+
+## 核心概念
+
+### 向量
+
+数学意义上的向量是一个浮点数数组，形似 `[1.0, 2.0, 3.0]`。在向量检索领域，一个向量是一个物体在高维空间的嵌入表征（Embedding）。例如在一个由若干个图片构成的高维空间中，每个向量代表一张图片。
+
+为了得到一个物体在某个高维空间的嵌入表征，我们使用嵌入模型（Embedding Model）对物体进行转换，得到一个高维向量。
+常用的嵌入模型类型包括图像嵌入模型、文本嵌入模型等，分别可以将图像、文本转换为高维向量。
+
+### 向量距离
+
+向量距离是两个向量在高维空间的距离。在向量检索应用中，它用来近似度量两个向量的语义相似度。例如给定三张图片，分别表示“游泳”、“太阳”、“水”。
+从语义上来说，“游泳”与“水”在语义上更接近，因此它们所对应的向量的距离更小。
+
+## 应用场景
+
+### 增强生成
+
+增强生成（Retrieval-Augmented Generation，RAG）是一个用来优化大语言模型（LLM）输出效果的框架。RAG 将知识输入到嵌入模型中，得到知识的向量表征，再将它们存储到向量数据库中。在大语言模型根据用户输入的提示词（Prompt）生成提示时，RAG 将提示词转换为向量表征，在向量数据库中执行近似搜索，得到与提示词语义相近的文档。这些文档可以用来提升模型输出的效果，使得响应更准确。
+
+### 语义搜索
+
+通过使用合适的嵌入模型，任意非结构化数据均可以转换为统一的向量表征。因此向量搜索原生支持跨语言、跨模态（文本、图像、音频等）的搜索，支持基于语义的匹配。
+
+### 推荐系统
+
+推荐系统一方面将内容、商品等转换为向量表征，存储到向量数据库中。另一方面，在用户搜索内容或商品时，推荐系统将用户的历史行为、偏好、标签、好友关系、关注列表等信息转换为向量表征，在向量数据库中查找与之相似的一系列内容或商品，从而提供用户可能更感兴趣的内容或商品。