new contents of 1.1-vector

docs/MatrixOne/Develop/schema-design/1.1-overview.md

@@ -0,0 +1,79 @@
+# 数据库模式设计概述
+
+本篇文章简要概述了 MatrixOne 的数据库模式。本篇概述主要介绍 MatrixOne 数据库相关术语和后续的数据读写示例。
+
+## 关键术语 - 数据库模式
+
+数据库模式 (Schema)：本篇文章所提到的**数据库模式**等同于逻辑对象*数据库*，与 MySQL 一样，不做区分。
+
+## 数据库 Database
+
+MatrixOne 数据库或 MatrixOne Database，为表的集合。
+
+你可以使用 `SHOW DATABASES;` 查看 MatrixOne 所包含的默认数据库。你也可以使用 `CREATE DATABASE database_name;` 创建一个新的数据库。
+
+## 表 Table
+
+MatrixOne 所指的表或 Table，从属于 MatrixOne 的某个数据库。
+
+表包含数据行。每行数据中的每个值都属于一个特定的列。每列都只允许单一数据类型的数据值。
+
+## 索引 Index
+
+索引是一种数据结构，用于快速查找数据库表格中的数据。它可以看作是一本*目录*，包含有关表格中各行数据的指针，使得查询可以更快速地定位到满足特定条件的数据。
+
+数据库中常用的索引类型包括主键索引、次级索引等。其中，唯一索引用于保证特定列或列组合的唯一性，普通索引用于提高查询性能，全文索引则用于在文本数据中进行全文检索。
+
+索引有两种常见的类型，分别为：
+
+- Primary Key：主键索引，即标识在主键列上的索引，主键索引用于唯一标识表格中的每一行数据。
+- Secondary Index：次级索引，即在非主键上标识的索引，次级索引也称为非聚集索引（non-clustered index），用于提高查询性能和加速数据检索。
+
+## 其他对象
+
+MatrixOne 支持一些和表同级的对象：
+
+- 视图：视图是一张虚拟表，该虚拟表的结构由创建视图时的 SELECT 语句定义，MatrixOne 暂不支持物化视图。
+- 临时表：临时表是数据不持久化的表。
+
+## 向量
+
+MatrixOne 现在支持存储和查询向量，它是一种由 AI 模型（如大型语言模型）生成的数字列表，通常称为向量的维度。通过衡量两个向量之间的距离来衡量它们的相关性，较小的距离表示更高的相似性。
+
+__Note:__ 当前 MatrixOne 仅支持插入和查询向量数据。
+
+更多信息，参见[向量](vector.md)
+
+## 访问控制
+
+MatrixOne 支持基于用户或角色的访问控制。你可以通过角色或直接指向用户，从而授予用户查看、修改或删除数据对象和数据模式的权限。
+
+更多信息，参见 [MatrixOne 中的权限控制](../../Security/role-priviledge-management/about-privilege-management.md)。
+
+## 对象大小限制
+
+### 标识符长度限制
+
+|对象 | 限制|
+|---|---|
+|数据库名称|64 字符|
+|表名称|64 字符|
+|列名称|64 字符|
+|视图名称|64 字符|
+
+### 单个表内限制
+
+|对象 | 限制|
+|---|---|
+|列数 | 默认为 1017，最大可调至 4096|
+|分区数|8192|
+|单行大小 | 默认为 6MB|
+|单行内单列大小|6MB|
+
+### 数据类型限制
+
+更多关于数据类型的参考文档，参见[数据类型](../../Reference/Data-Types/data-types.md)。
+
+### 行数
+
+MatrixOne 可通过增加集群的节点数来支持任意数量的行。

docs/MatrixOne/Develop/schema-design/1.1-vector.md

@@ -0,0 +1,183 @@
+# 向量
+
+## 什么是向量
+
+在数据库中，向量通常是一组数字，它们以特定的方式排列，以表示某种数据或特征。这些向量可以是一维数组、多维数组或具有更高维度的数据结构。在机器学习和数据分析领域中，向量用于表示数据点、特征或模型参数。
+
+## 向量的优点
+
+数据库拥有向量能力意味着数据库系统具备存储、查询和分析向量数据的能力。这些向量通常与复杂的数据分析、机器学习和数据挖掘任务相关。以下是数据库拥有向量能力的一些优点：
+
+- **支持多种应用领域：**向量能力使数据库适用于多种应用领域，包括人脸识别、推荐系统和基因组学分析等。
+
+- **高性能分析：**数据库可以通过针对向量数据的高性能查询和分析操作来加速复杂的数据分析任务。这对于大规模数据集和实时数据处理至关重要。
+
+- **相似性搜索：**向量能力允许数据库执行相似性搜索操作，例如查找最接近给定向量的数据库中的向量。这在推荐系统和搜索引擎等应用中非常有用。
+
+- **维度灵活性：**向量能力通常支持不同维度的向量，使数据库可以处理各种数据类型和特征。
+
+- **机器学习集成：**数据库支持向量存储和查询，可以与机器学习模型集成，使模型的训练和推断更加高效和便捷。
+
+## 开始前准备
+
+在阅读本页面之前，你需要准备以下事项：
+
+- 了解并已经完成构建 MatrixOne 集群。
+- 了解什么是[数据库模式](overview.md)。
+
+## 如何使用向量
+
+使用向量的语法与常规建表、插入数据、查询数据相同：
+
+### 创建向量列
+
+你可以按照下面的 SQL 语句创建了两个向量列，一个是 Float32 类型，另一个是 Float64 类型，并且可以将两个向量列的维度都设置为 3。
+
+```
+create table t1(a int, b vecf32(3), c vecf64(3));
+```
+
+### 插入向量
+
+MatrixOne 支持以两种格式插入向量。
+
+**文本格式**
+
+```
+insert into t1 values(1, "[1,2,3]", "[4,5,6]");
+```
+
+**二进制格式**
+
+如果你想使用 Python NumPy 数组，可以通过对数组进行十六进制编码，而不是将其转换为逗号分隔的文本格式，直接将该 NumPy 数组插入 MatrixOne。在插入维度较高的向量时，这种方式速度更快。
+
+```sql
+insert into t1 (a, b) values
+(2, decode("7e98b23e9e10383b2f41133f", "hex"));
+
+-- "7e98b23e9e10383b2f41133f" 表示[]float32{0.34881967, 0.0028086076, 0.5752134}的小端十六进制编码
+
+-- "hex" 表示十六进制编码
+```
+
+### 查询向量
+
+向量列同样可以以两种格式读取。
+
+**文本格式**
+
+```sql
+mysql> select a, b from t1;
++------+---------------------------------------+
+| a    | b                                     |
++------+---------------------------------------+
+|    1 | [1, 2, 3]                             |
+|    2 | [0.34881967, 0.0028086076, 0.5752134] |
++------+---------------------------------------+
+2 rows in set (0.00 sec)
+```
+
+**二进制格式**
+
+如果你需要将向量结果集直接读取到 NumPy 数组中，以最小的转换成本，二进制格式非常有用。
+
+```sql
+mysql> select encode(b, "hex") from t1;
++--------------------------+
+| encode(b, hex)           |
++--------------------------+
+| 0000803f0000004000004040 |
+| 7e98b23e9e10383b2f41133f |
++--------------------------+
+2 rows in set (0.00 sec)
+```
+
+## 示例 - Top K 查询
+
+Top K 查询是一种数据库查询操作，用于检索数据库中排名前 K 的数据项或记录。Top K 查询可以应用于各种应用场景，包括推荐系统、搜索引擎、数据分析和排序。
+
+首先，我们创建了一个名为 `t1` 的表，其中包含了向量数据 `b`，并插入了一些示例数据。然后，我们使用给定的 SQL 语句执行基于 `l1_distance`、`l2_distance`、余弦相似度和余弦距离的 Top K 查询，将结果限制为前 5 个匹配项。
+
+```sql
+-- 包含向量数据'b'的示例表't1'
+CREATE TABLE t1 (
+    id int,
+    b vecf64(3)
+);
+
+-- 插入一些示例数据
+INSERT INTO t1 (b) VALUES ('[1,2,3]'), ('[4,5,6]'), ('[2,1,1]'), ('[7,8,9]'), ('[0,0,0]'), ('[3,1,2]');
+
+-- 使用l1_distance进行Top K查询
+SELECT * FROM t1 ORDER BY l1_norm(b - '[3,1,2]') LIMIT 5;
+mysql> SELECT * FROM t1 ORDER BY l1_norm(b - '[3,1,2]') LIMIT 5;
++------+-----------+
+| id   | b         |
++------+-----------+
+| NULL | [3, 1, 2] |
+| NULL | [2, 1, 1] |
+| NULL | [1, 2, 3] |
+| NULL | [0, 0, 0] |
+| NULL | [4, 5, 6] |
++------+-----------+
+5 rows in set (0.00 sec)
+
+-- 使用l2_distance进行Top K查询
+mysql> SELECT * FROM t1 ORDER BY l2_norm(b - '[3,1,2]') LIMIT 5;
++------+-----------+
+| id   | b         |
++------+-----------+
+| NULL | [3, 1, 2] |
+| NULL | [2, 1, 1] |
+| NULL | [1, 2, 3] |
+| NULL | [0, 0, 0] |
+| NULL | [4, 5, 6] |
++------+-----------+
+5 rows in set (0.00 sec)
+
+-- 使用余弦相似度进行Top K查询
+mysql> SELECT * FROM t1 ORDER BY cosine_similarity(b, '[3,1,2]') LIMIT 5;
++------+-----------+
+| id   | b         |
++------+-----------+
+| NULL | [1, 2, 3] |
+| NULL | [0, 0, 0] |
+| NULL | [4, 5, 6] |
+| NULL | [7, 8, 9] |
+| NULL | [2, 1, 1] |
++------+-----------+
+5 rows in set (0.00 sec)
+
+-- 使用余弦距离进行Top K查询
+mysql> SELECT * FROM t1 ORDER BY 1 - cosine_similarity(b, '[3,1,2]') LIMIT 5;
++------+-----------+
+| id   | b         |
++------+-----------+
+| NULL | [3, 1, 2] |
+| NULL | [0, 0, 0] |
+| NULL | [2, 1, 1] |
+| NULL | [7, 8, 9] |
+| NULL | [4, 5, 6] |
++------+-----------+
+5 rows in set (0.00 sec)
+```
+
+这些查询演示了如何使用不同的距离度量和相似度度量来检索与给定向量 `[3,1,2]` 最相似的前 5 个向量。在这里，`l1_distance` 和 `l2_distance` 分别表示 L1 距离和 L2 距离，`cosine_similarity` 表示余弦相似度，`cosine_distance` 表示余弦距离。通过这些查询，你可以根据不同的度量标准找到与目标向量最匹配的数据。
+
+## 限制
+
+- 目前，MatrixOne 向量类型支持 float32 和 float64 类型。
+- 向量不能作为主键或唯一键。
+- 向量的最大维度为 65536。
+
+## 参考文档
+
+更多关于向量函数的文档，参见：
+
+- [inner_product()](../../Reference/Functions-and-Operators/1.1-Vector/inner_product.md)
+- [l1_norm()](../../Reference/Functions-and-Operators/1.1-Vector/l1_norm.md)
+- [l2_norm()](../../Reference/Functions-and-Operators/1.1-Vector/l2_norm.md)
+- [cosine_similarity()](../../Reference/Functions-and-Operators/1.1-Vector/cosine_similarity.md)
+- [vector_dims()](../../Reference/Functions-and-Operators/1.1-Vector/vector_dims.md)
+- [Arithemetic Operators](../../Reference/Functions-and-Operators/1.1-Vector/arithmetic.md)
+- [Misc Functions](../../Reference/Functions-and-Operators/1.1-Vector/misc.md)