diff --git a/docs/MatrixOne/Develop/schema-design/1.1-overview.md b/docs/MatrixOne/Develop/schema-design/1.1-overview.md new file mode 100644 index 0000000000..cd91c8d974 --- /dev/null +++ b/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 可通过增加集群的节点数来支持任意数量的行。 diff --git a/docs/MatrixOne/Develop/schema-design/1.1-vector.md b/docs/MatrixOne/Develop/schema-design/1.1-vector.md new file mode 100644 index 0000000000..7a0171da8b --- /dev/null +++ b/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) diff --git a/docs/MatrixOne/Overview/architecture/1.1-matrixone-architecture-design.md b/docs/MatrixOne/Overview/architecture/1.1-matrixone-architecture-design.md new file mode 100644 index 0000000000..995bb920bb --- /dev/null +++ b/docs/MatrixOne/Overview/architecture/1.1-matrixone-architecture-design.md @@ -0,0 +1,133 @@ +# **MatrixOne 架构设计** + +## **MatrixOne 概述** + +MatrixOne 是一款面向未来的超融合异构云原生数据库,通过简化的分布式数据库引擎,跨多个数据中心、云、边缘和其他异构基础设施,同时支持事务性(OLTP)、分析性(OLAP)和流式工作(Sreaming)负载,这种多种引擎的融合,称为 HSTAP。 + +MatrixOne HSTAP 数据库对 HTAP 数据库进行了重新定义,HSTAP 旨在满足单一数据库内事务处理(TP)和分析处理(AP)的所有需求。与传统的 HTAP 相比,HSTAP 强调其内置的用于连接 TP 和 AP 表数据流处理能力,为用户提供了数据库可以像大数据平台一样灵活的使用体验。也恰恰得益于大数据的繁荣,很多用户已经熟悉了这种体验。用户使用 MatrixOne 只需要少量的集成工作,即可以获得覆盖整个 TP 和 AP 场景的一站式体验,同时可以摆脱传统大数据平台的臃肿架构及各种限制。 + +## **MatrixOne 架构层级** + +MatrixOne 实现了三个独立的层级,每个层级都有自己的对象单元和分工。不同类型的节点可以自由伸缩,不再受到其他层的制约。这三个层级是: + +![](https://community-shared-data-1308875761.cos.ap-beijing.myqcloud.com/artwork/docs/overview/architecture/architecture-1.png) + +- 计算层:以计算节点 Compute Node (简称 CN) 为单位,实现了计算和事务处理的 Serverless 化,具备自己的缓存,可以任意重启和扩缩容。 +- 事务层:以数据库节点 Transaction Node 和日志节点 Log Service 为单位,提供完整的日志服务和元数据信息,内置 Logtail 用于保存最近的数据。 +- 存储层:全量数据保存在对象存储中,以 S3 为代表,实现了低成本的无线伸缩存储方式。统一的文件操作服务 File Service 实现了不同节点对底层存储的无感知操作。 + +![](https://community-shared-data-1308875761.cos.ap-beijing.myqcloud.com/artwork/docs/overview/architecture/architecture-2.png) + +在确定了 TAE 作为唯一存储引擎之后,对融合后的 TAE 引擎进行了多项设计上的调整,才有了后来的 TAE 存储引擎。这个引擎具有如下优势: + +- 列存管理:统一的列存和压缩方式,对于 OLAP 业务具有先天的性能优势。 +- 事务处理:共享日志和 TN 节点共同完成对计算节点的事务支持。 +- 冷热分离:使用 S3 对象存储作为目标的 File Service,每个计算节点都有自己的缓存。 + +![](https://community-shared-data-1308875761.cos.ap-beijing.myqcloud.com/artwork/docs/overview/architecture/architecture-3.png) + +计算引擎基于兼容 MySQL 的根本目标,对于节点调度、执行计划和 SQL 能力有着更高的要求。高性能计算引擎既具备实验架构中计算引擎的 MPP: + +- 兼容 MySQL:具有对 MySQL 协议和语法的支持。 +- 融合引擎:基于 DAG 重新构建执行计划,可以同时执行 TP 和 AP。 +- 节点调度:未来可支持自适应节点内和节点间调度,同时满足并发和并行执行。 +- 完善的 SQL 能力:支持子查询、窗口函数、CTE、Spill 内存溢出处理等。 +- 向量能力:支持向量存储和查询,使 MatrixOne 成为各种机器学习应用的重要存储工具,包括人脸识别、推荐系统和基因组学分析等。 + +## **MatrixOne 架构设计** + +MatrixOne 架构如下如所示: + +![MatrixOne Architecture](https://community-shared-data-1308875761.cos.ap-beijing.myqcloud.com/artwork/docs/overview/matrixone_new_arch.png) + +参照上面的图示,MatrixOne 的体系结构分为五层,以下内容是从上至下对每层的介绍: + +### **集群管理层** + +这一层负责集群管理,在云原生环境中与 Kubernetes 交互动态获取资源;在本地部署时,根据配置获取资源。集群状态持续监控,根据资源信息分配每个节点的任务。提供系统维护服务以确保所有系统组件在偶尔出现节点和网络故障的情况下正常运行,并在必要时重新平衡节点上的负载。集群管理层的主要组件是: + +- Prophet 调度:提供负载均衡和节点 Keep-alive。 +- 资源管理:提供物理资源。 + +### **Serverless 层** + +Serverless 层是一系列无状态节点的总称,整体上包含三类: + +- 后台任务:最主要的功能是 Offload Worker,负责卸载成本高的压缩任务,以及将数据刷新到 S3 存储。 +- SQL 计算节点:负责执行 SQL 请求,这里分为写节点和读节点,写节点还提供读取最新数据的能力。 +- 流任务处理节点:负责执行流处理请求。 + +### **日志层** + +作为 MatrixOne 的单一数据源 (即 Single source of truth),数据一旦写入日志层,则将永久地存储在 MatrixOne 中。它建立在我们世界级的复制状态机模型的专业知识之上,以保证我们的数据具有最先进的高吞吐量、高可用性和强一致性。它本身遵循完全模块化和分解的设计,也帮助解耦存储和计算层的核心组件,与传统的 NewSQL 架构相比,我们的架构具有更高的弹性。 + +### **存储层** + +存储层将来自日志层的传入数据转换为有效的形式,以供将来对数据进行处理和存储。包括为快速访问已写入 S3 的数据进行的缓存维护等。 + +在 MatrixOne 中,**TAE(即 Transactional Analytic Engine)**存储引擎是存储层的主要公开接口,它可以同时支持行和列存储以及事务处理能力。此外,存储层还包括其他内部使用的存储功能,例如流媒体的中间存储。 + +### **存储供应层** + +作为与基础架构解耦的 DBMS,MatrixOne 可以将数据存储在 S3/HDFS、本地磁盘、本地服务器、混合云或其他各类型云,以及智能设备的共享存储中。存储供应层通过为上层提供一个统一的接口来访问这些多样化的存储资源,并且不向上层暴露存储的复杂性。 + +## **MatrixOne 系统组件** + +![MatrixOne Component](https://community-shared-data-1308875761.cos.ap-beijing.myqcloud.com/artwork/docs/overview/mo-component.png) + +在 MatrixOne 中,为实现分布式与多引擎的融合,构建了多种不同的系统组件用于完成架构相关的层级的功能: + +### **File Service** + +File Service 是 MatrixOne 负责所有存储介质读写的组件。存储介质包括内存、磁盘、对象存储等,它提供了如下特性: + +- File Service 提供了一个统一的接口,使不同介质的读写,可以使用相同的接口。 +- 接口的设计,遵循了数据不可变的理念。文件写入之后,就不允许再更新。数据的更新,通过产生新的文件来实现。 +- 这样的设计,简化了数据的缓存、迁移、校验等操作,有利于提高数据操作的并发能力。 +- 基于统一的读写接口,File Service 提供了分级的缓存,提供了灵活的缓存策略,以平衡读写速度和容量。 + +### **Log Service** + +Log Service 是 MatrixOne 中专门用于处理事务日志的组件,它具有如下功能特性: + +- 采用 Raft 协议来保证一致性,采用多副本方式确保可用性。 +- 保存并处理 MatrixOne 中所有的事务日志,在事务提交前确保 Log Service 的日志读写正常,在实例重启时,检查并回放日志内容。 +- 在完成事务的提交与落盘后,对 Log Service 内容做截断,从而控制 Log Service 的大小,截断后仍然保留在 Log Service 中的内容,称为 Logtail。 +- 如果多个 Log Service 副本同时出现宕机,那么整个 MatrixOne 将会发生宕机。 + +### **Transaction Node** + +Transaction Node(TN),是用来运行 MatrixOne 的分布式存储引擎 TAE 的载体,它提供了如下特性: + +- 管理 MatrixOne 中的元数据信息以及 Log Service 中保存的事务日志内容。 +- 接收 Computing Node(CN) 发来的分布式事务请求,对分布式事务的读写请求进行裁决,将事务裁决结果推给 CN,将事务内容推给 Log Service,确保事务的 ACID 特性。 +- 在事务中根据检查点生成快照,确保事务的快照隔离性,在事务结束后将快照信息释放。 + +### **Computing Node** + +Computing Node(CN),是 Matrixone 接收用户请求并处理 SQL 的组件,具体包括以下模块: + +- Frontend,处理客户端 SQL 协议,接受客户端发送的 SQL 报文,然后解析得到 MatrixOne 可执行的 SQL,调用其他模块执行 SQL 后将查询结果组织成报文返回给客户端。 +- Plan,解析 Frontend 处理后的 SQL,并根据 MatrixOne 的计算引擎生成逻辑执行计划发送给 Pipeline。 +- Pipeline,解析逻辑计划,将逻辑计划转成实际的执行计划,然后 Pipeline 运行执行计划。 +- Disttae,负责具体的读写任务,既包含了从 TN 同步 Logtail 和从 S3 读取数据,也会把写入的数据发送给 TN。 + +### **Stream Engine** + +Stream Engine 是 MatrixOne 内置的全新组件,旨在支持实时数据查询、处理以及增强数据存储,特别针对传入的数据流(数据点序列)。借助 Stream Engine,您能够使用 SQL 定义并构建流处理管道,将其作为实时数据后端提供服务;同时,您也能够运用 SQL 查询流中的数据,并与非流式数据集进行联接,从而更进一步地简化整个数据堆栈的处理流程。 + +### **Proxy** + +Proxy 组件是一款功能强大的工具,主要用于实现负载均衡与 SQL 路由。它具有以下功能: + +- 通过 SQL 路由,实现了不同租户之间的资源隔离,保证了不同租户的 CN 之间不会互相影响。 +- 通过 SQL 路由,允许用户在同一租户的资源组内再做二次拆分,提高了资源利用率。 +- 在二次拆分的资源组内,实现了不同 CN 之间的负载均衡,使得系统运行更加稳定和高效。 + +## **相关信息** + +本节介绍了 MatrixOne 的整体架构概览。其他信息可参见: + +* [安装单机版 MatrixOne](../../Get-Started/install-standalone-matrixone.md) + +* [最新发布信息](../whats-new.md) diff --git a/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/arithmetic.md b/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/arithmetic.md new file mode 100644 index 0000000000..1df2e01e62 --- /dev/null +++ b/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/arithmetic.md @@ -0,0 +1,89 @@ +# 算术运算符 + +MatrixOne 支持基本的算术运算符,如向量的加法、减法、乘法和除法。这些运算符执行逐元素的算术操作,并返回一个新的向量。 + +!!! note + 减法(`-`)、乘法(`*`)和除法(`/`)都与加法示例类似,不作赘述。 + +## Add + +### **函数说明** + +`+` 用于将两个向量元素相加。 + +### **函数语法** + +``` +> SELECT vector1 + vector2 AS result_vector FROM table_name; +``` + +### **示例** + +```sql +drop table if exists vec_table; +create table vec_table(a int, b vecf32(3), c vecf64(3)); +insert into vec_table values(1, "[1,2,3]", "[4,5,6]"); +mysql> select * from vec_table; ++------+-----------+-----------+ +| a | b | c | ++------+-----------+-----------+ +| 1 | [1, 2, 3] | [4, 5, 6] | ++------+-----------+-----------+ +1 row in set (0.00 sec) + +mysql> select b + "[1,2,3]" from vec_table; ++-------------+ +| b + [1,2,3] | ++-------------+ +| [2, 4, 6] | ++-------------+ +1 row in set (0.00 sec) +``` + +### **限制** + +- 两个参数向量的维度应相同。 +- 如果两个向量的数据类型分分别为 vecf32 和 vecf64,那么结果会转换为 vecf64。 +- 两个向量的数据类型必须相同,即其中一个向量的数据类型为文本格式,那么另一个参数也应该为文本格式。如果两个参数的数据类型都是 TEXT,则查询时将视其为字符串。 + +## Divide + +### **函数说明** + +`/` 用于将两个向量元素相除。 + +## **函数语法** + +``` +> SELECT vector1 / vector2 AS result_vector FROM table_name; +``` + +### **示例** + +```sql +drop table if exists vec_table; +create table vec_table(a int, b vecf32(3), c vecf64(3)); +insert into vec_table values(1, "[1,2,3]", "[4,5,6]"); +mysql> select * from vec_table; ++------+-----------+-----------+ +| a | b | c | ++------+-----------+-----------+ +| 1 | [1, 2, 3] | [4, 5, 6] | ++------+-----------+-----------+ +1 row in set (0.00 sec) + +mysql> select b/b from vec_table; ++-----------+ +| b / b | ++-----------+ +| [1, 1, 1] | ++-----------+ +1 row in set (0.00 sec) +``` + +### **限制** + +- 分母向量中的元素不允许为 0,否则产生报错。 +- 两个参数向量的维度应相同。 +- 如果两个向量的数据类型分别为 vecf32 和 vecf64,那么结果会转换为 vecf64。 +- 两个向量的数据类型必须相同,即其中一个向量的数据类型为文本格式,那么另一个参数也应该为文本格式。如果两个参数的数据类型都是 TEXT,则查询时将视其为字符串。 diff --git a/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/cosine_similarity.md b/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/cosine_similarity.md new file mode 100644 index 0000000000..b22183a4f2 --- /dev/null +++ b/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/cosine_similarity.md @@ -0,0 +1,41 @@ +# **cosine_similarity()** + +## **函数说明** + +`cosine_similarity()` 是余弦相似度,它衡量了两个向量之间夹角的余弦值,通过它们在多维空间中的接近程度来表示它们的相似性,其中 1 表示完全相似,-1 表示完全不相似。余弦相似度的计算是通过将两个向量的内积除以它们的 l2 范数的乘积来实现的。 + +![cosine_similarity](https://github.com/matrixorigin/artwork/blob/main/docs/reference/vector/cosine_similarity.png?raw=true) + +## **函数语法** + +``` +> SELECT cosine_similarity(vector1, vector2) AS similarity FROM table_name; +``` + +## **示例** + +```sql +drop table if exists vec_table; +create table vec_table(a int, b vecf32(3), c vecf64(3)); +insert into vec_table values(1, "[1,2,3]", "[4,5,6]"); +mysql> select * from vec_table; ++------+-----------+-----------+ +| a | b | c | ++------+-----------+-----------+ +| 1 | [1, 2, 3] | [4, 5, 6] | ++------+-----------+-----------+ +1 row in set (0.00 sec) + +mysql> select cosine_similarity(b,"[1,2,3]") from vec_table; ++-------------------------------+ +| cosine_similarity(b, [1,2,3]) | ++-------------------------------+ +| 1 | ++-------------------------------+ +1 row in set (0.00 sec) +``` + +## **限制** + +- 两个参数向量必须具有相同的维度。 +- 余弦相似度的值位于 -1 和 1 之间。 diff --git a/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/inner_product.md b/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/inner_product.md new file mode 100644 index 0000000000..6e292db79f --- /dev/null +++ b/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/inner_product.md @@ -0,0 +1,40 @@ +# **inner_product()** + +## **函数说明** + +`INNER PRODUCT` 函数用于计算两个向量之间的内积/点积,它是两个向量的对应元素相乘然后相加的结果。 + +![inner_product](https://github.com/matrixorigin/artwork/blob/main/docs/reference/vector/inner_product.png?raw=true) + +## **函数语法** + +``` +> SELECT inner_product(vector1, vector2) AS result FROM table_name; +``` + +## **示例** + +```sql +drop table if exists vec_table; +create table vec_table(a int, b vecf32(3), c vecf64(3)); +insert into vec_table values(1, "[1,2,3]", "[4,5,6]"); +mysql> select * from vec_table; ++------+-----------+-----------+ +| a | b | c | ++------+-----------+-----------+ +| 1 | [1, 2, 3] | [4, 5, 6] | ++------+-----------+-----------+ +1 row in set (0.00 sec) + +mysql> select inner_product(b,"[1,2,3]") from vec_table; ++---------------------------+ +| inner_product(b, [1,2,3]) | ++---------------------------+ +| 14 | ++---------------------------+ +1 row in set (0.00 sec) +``` + +## **限制** + +两个参数向量必须具有相同的维度。 diff --git a/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/l1_norm.md b/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/l1_norm.md new file mode 100644 index 0000000000..f859c364f9 --- /dev/null +++ b/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/l1_norm.md @@ -0,0 +1,44 @@ +# **l1_norm()** + +## **函数说明** + +`l1_norm` 函数用于计算 `l1`/曼哈顿/TaxiCab 范数。`l1` 范数通过对向量元素的绝对值求和得到。 + +![l1_normy](https://github.com/matrixorigin/artwork/blob/main/docs/reference/vector/l1_norm.png?raw=true) + +你可以使用 `l1` 范数来计算 `l1` 距离。 + +``` +l1_distance(a,b) = l1_norm(a-b) +``` + +这样的计算方式同样适用于从 `l2_Norm` 计算 `l2` 距离。 + +## **函数语法** + +``` +> SELECT l1_norm(vector) AS result FROM table_name; +``` + +## **示例** + +```sql +drop table if exists vec_table; +create table vec_table(a int, b vecf32(3), c vecf64(3)); +insert into vec_table values(1, "[1,2,3]", "[4,5,6]"); +mysql> select * from vec_table; ++------+-----------+-----------+ +| a | b | c | ++------+-----------+-----------+ +| 1 | [1, 2, 3] | [4, 5, 6] | ++------+-----------+-----------+ +1 row in set (0.00 sec) + +mysql> select l1_norm(b) from vec_table; ++------------+ +| l1_norm(b) | ++------------+ +| 6 | ++------------+ +1 row in set (0.00 sec) +``` diff --git a/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/l2_norm.md b/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/l2_norm.md new file mode 100644 index 0000000000..f46aa1c0e3 --- /dev/null +++ b/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/l2_norm.md @@ -0,0 +1,36 @@ +# **l2_norm()** + +## **函数说明** + +`l2_norm` 函数用于计算 `l2`/欧几里得范数。`l2` 范数通过对向量元素的平方和进行平方根运算得到。 + +![l2_normy](https://github.com/matrixorigin/artwork/blob/main/docs/reference/vector/l2_norm.png?raw=true) + +## **函数语法** + +``` +> SELECT l2_norm(vector) AS result FROM table_name; +``` + +## **示例** + +```sql +drop table if exists vec_table; +create table vec_table(a int, b vecf32(3), c vecf64(3)); +insert into vec_table values(1, "[1,2,3]", "[4,5,6]"); +mysql> select * from vec_table; ++------+-----------+-----------+ +| a | b | c | ++------+-----------+-----------+ +| 1 | [1, 2, 3] | [4, 5, 6] | ++------+-----------+-----------+ +1 row in set (0.00 sec) + +mysql> select l2_norm(b) from vec_table; ++--------------------+ +| l2_norm(b) | ++--------------------+ +| 3.7416573867739413 | ++--------------------+ +1 row in set (0.01 sec) +``` diff --git a/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/misc.md b/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/misc.md new file mode 100644 index 0000000000..4d98ba831a --- /dev/null +++ b/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/misc.md @@ -0,0 +1,168 @@ +# 数学类函数 + +向量支持以下数学类函数: + +## SQRT + +### **函数说明** + +`sqrt` 函数用于计算向量中每个元素的平方根。 + +### **函数语法** + +``` +> SELECT sqrt(vector_column) FROM table_name; +``` + +#### 返回类型 + +返回一个新的 vecf64 类型的向量,其中包含原始向量中每个元素的平方根。 + +### **示例** + +```sql +drop table if exists vec_table; +create table vec_table(a int, b vecf32(3), c vecf64(3)); +insert into vec_table values(1, "[1,2,3]", "[4,5,6]"); +mysql> select * from vec_table; ++------+-----------+-----------+ +| a | b | c | ++------+-----------+-----------+ +| 1 | [1, 2, 3] | [4, 5, 6] | ++------+-----------+-----------+ +1 row in set (0.00 sec) + +mysql> select sqrt(b) from vec_table; ++---------------------------------------------+ +| sqrt(b) | ++---------------------------------------------+ +| [1, 1.4142135623730951, 1.7320508075688772] | ++---------------------------------------------+ +1 row in set (0.00 sec) +``` + +### **限制** + +- 向量的元素不能为负数。 + +## ABS + +### **函数说明** + +`abs` 函数用于计算向量的绝对值。 + +### **函数语法** + +``` +> SELECT ABS(vector_column) FROM table_name; +``` + +#### 返回类型 + +返回一个相同类型的新向量,其中包含原始向量中每个元素的绝对值。 + +### **示例** + +```sql +drop table if exists vec_table; +create table vec_table(a int, b vecf32(3), c vecf64(3)); +insert into vec_table values(1, "[1,2,3]", "[4,5,6]"); +mysql> select * from vec_table; ++------+-----------+-----------+ +| a | b | c | ++------+-----------+-----------+ +| 1 | [1, 2, 3] | [4, 5, 6] | ++------+-----------+-----------+ +1 row in set (0.00 sec) + +mysql> select abs(b) from vec_table; ++-----------+ +| abs(b) | ++-----------+ +| [1, 2, 3] | ++-----------+ +1 row in set (0.01 sec) +``` + +## CAST + +### **函数说明** + +cast 函数用于显式将一个向量从一个向量类型转换为另一个向量类型。 + +### **函数语法** + +``` +> SELECT CAST(vector AS vector_type) FROM table_name; +``` + +#### 参数 + +- `vector`:输入向量。 +- `vector_type`:新的向量类型。 + +#### 返回类型 + +新的 `vector_type` 向量。 + +### **示例** + +```sql +drop table if exists vec_table; +create table vec_table(a int, b vecf32(3), c vecf64(3)); +insert into vec_table values(1, "[1,2,3]", "[4,5,6]"); +mysql> select * from vec_table; ++------+-----------+-----------+ +| a | b | c | ++------+-----------+-----------+ +| 1 | [1, 2, 3] | [4, 5, 6] | ++------+-----------+-----------+ +1 row in set (0.00 sec) + +mysql> select abs(cast("[-1,-2,3]" as vecf32(3))); ++-----------------------------------+ +| abs(cast([-1,-2,3] as vecf32(3))) | ++-----------------------------------+ +| [1, 2, 3] | ++-----------------------------------+ +1 row in set (0.00 sec) +``` + +## SUMMATION + +### **函数说明** + +`summation` 函数返回向量中所有元素的总和。 + +### **函数语法** + +``` +> SELECT SUMMATION(vector_column) FROM table_name; +``` + +#### 返回类型 + +返回一个 FLOAT64 值,即向量中所有元素的总和。 + +### **示例** + +```sql +drop table if exists vec_table; +create table vec_table(a int, b vecf32(3), c vecf64(3)); +insert into vec_table values(1, "[1,2,3]", "[4,5,6]"); +mysql> select * from vec_table; ++------+-----------+-----------+ +| a | b | c | ++------+-----------+-----------+ +| 1 | [1, 2, 3] | [4, 5, 6] | ++------+-----------+-----------+ +1 row in set (0.00 sec) + +mysql> select summation(b) from vec_table; ++--------------+ +| summation(b) | ++--------------+ +| 6 | ++--------------+ +1 row in set (0.00 sec) +``` diff --git a/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/vector_dims.md b/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/vector_dims.md new file mode 100644 index 0000000000..82976ba6c5 --- /dev/null +++ b/docs/MatrixOne/Reference/Functions-and-Operators/1.1-Vector/vector_dims.md @@ -0,0 +1,34 @@ +# **vector_dims()** + +## **函数说明** + +`vector_dims` 函数用于确定向量的维度。 + +## **函数语法** + +``` +> SELECT vector_dims(vector) AS dimension_count FROM table_name; +``` + +## **示例** + +```sql +drop table if exists vec_table; +create table vec_table(a int, b vecf32(3), c vecf64(3)); +insert into vec_table values(1, "[1,2,3]", "[4,5,6]"); +mysql> select * from vec_table; ++------+-----------+-----------+ +| a | b | c | ++------+-----------+-----------+ +| 1 | [1, 2, 3] | [4, 5, 6] | ++------+-----------+-----------+ +1 row in set (0.00 sec) + +mysql> select vector_dims(b) from vec_table; ++----------------+ +| vector_dims(b) | ++----------------+ +| 3 | ++----------------+ +1 row in set (0.01 sec) +```