Merge pull request #113 from NotHimmel/v1.17

docs(CN&EN): add new documentation for IvorySQL features

Author: gaoxueyu

CN/modules/ROOT/images/p20.jpg

@@ -2,16 +2,26 @@
 * xref:v1.17/1.adoc[发行说明]
 * xref:v1.17/2.adoc[关于IvorySQL]
 * IvorySQL入门
-** xref:v1.17/3.adoc[用户使用手册]
-** xref:v1.17/4.adoc[管理员指南]
-** xref:v1.17/5.adoc[运维人员指南]
-* xref:v1.17/6.adoc[安装部署]
-* xref:v1.17/7.adoc[社区贡献指南]
-* xref:v1.17/8.adoc[工具参考]
-* xref:v1.17/9.adoc[FAQ]
-* 功能列表
-** xref:v1.17/10.adoc[1、Ivorysql框架设计]
-** xref:v1.17/11.adoc[2、GUC框架]
-** xref:v1.17/12.adoc[3、适配插件]
-** xref:v1.17/13.adoc[4、双模式设计]
-** xref:v1.17/14.adoc[5、新增Oracle兼容模式的端口与Ip]
+** xref:v1.17/3.adoc[快速开始]
+** xref:v1.17/4.adoc[日常监控]
+** xref:v1.17/5.adoc[日常维护]
+* IvorySQL高级
+** xref:v1.17/6.adoc[安装指南]
+** xref:v1.17/7.adoc[开发者指南]
+** xref:v1.17/8.adoc[运维管理指南]
+* IvorySQL生态
+** xref:v1.17/9.adoc[PostGIS]
+** xref:v1.17/10.adoc[pgvector]
+* Oracle兼容功能列表
+** xref:v1.17/11.adoc[1、Ivorysql框架设计]
+** xref:v1.17/12.adoc[2、GUC框架]
+** xref:v1.17/13.adoc[3、大小写转换]
+** xref:v1.17/14.adoc[4、双模式设计]
+** xref:v1.17/15.adoc[5、兼容Oracle like]
+** xref:v1.17/16.adoc[6、兼容Oracle匿名块]
+** xref:v1.17/17.adoc[7、兼容Oracle函数与存储过程]
+** xref:v1.17/18.adoc[8、内置数据类型与内置函数]
+** xref:v1.17/19.adoc[9、新增Oracle兼容模式的端口与IP]
+* xref:v1.17/20.adoc[社区贡献指南]
+* xref:v1.17/21.adoc[工具参考]
+* xref:v1.17/22.adoc[FAQ]

CN/modules/ROOT/images/p21.jpg

@@ -1,26 +1,120 @@
 :sectnums:
 :sectnumlevels: 5
-:imagesdir: ./_images
 
-= Ivorysql框架设计
+= pgvector
 
-== 目的
-- 为了对原有的postgres改动最小的前提下，实现对oracle兼容。我们需要实现双parser、双端口、模式PLPGSQL实现PL\iSQL的框架。实现流程图如下：
+== 概述
+向量数据库是生成式人工智能(GenAI)的关键组成部分。pgvector作为PostgreSQL的重要扩展，不仅能够支持高达16000维度的向量计算，还提供了强大的向量操作和索引功能，使得PostgreSQL能够直接转化为高效的向量数据库。由于IvorySQL基于PostgreSQL研发，这使得它具备了与pgvector扩展无缝集成的能力，从而为用户提供了更广泛的数据处理和分析选项。在Oracle兼容模式下，pgvector扩展同样可用，这为Oracle用户使用向量数据库提供了极大的便利，使其能够轻松地迁移和管理数据，实现更高效的业务操作。
 
-image::p18.png[]
 
-== 功能
+== 原理介绍
 
-=== 双端口设计
+IVFFLAT和HNSW是PGVector的两个索引算法
 
-- 保持了Ivorysql 5432端口兼容原有postgres情况，因此 Ivorysql采用另一个独立的端口登录，默认为1521。从该端口登录，默认采用oracle兼容模式。如果需要从5432端口登录且还要进入兼容模式，则需要通过compatible_mode参数进行设置;
+=== IVFFLAT
 
-=== parser模块设计
+IVFFLAT的工作原理是将相似的向量聚类为区域，并建立一个倒排索引，将每个区域映射到其向量。这使得查询可以集中在数据的一个子集上，从而实现快速搜索。通过调整列表和探针参数，ivfflat 可以平衡数据集的速度和准确性，使 PostgreSQL 有能力对复杂数据进行快速的语义相似性搜索。通过简单的查询，应用程序可以在数百万个高维向量中找到与查询向量最近的邻居。对于自然语言处理、信息检索等，ivfflat 是一个比较好的解决方案
+在建立 ivfflat 索引时，你需要决定索引中包含多少个 list。每个 list 代表一个 "中心"；这些中心通过 k-means 算法计算而来。一旦确定了所有中心，ivfflat 就会确定每个向量最靠近哪个中心，并将其添加到索引中。当需要查询向量数据时，你可以决定要检查多少个中心，这由 ivfflat.probes 参数决定。这就是 ANN 性能/召回率的结果：访问的中心越多，结果就越精确，但这是以牺牲性能为代价的。
 
-- 为了将Oracle语法与postgres语法间的相互干扰降到最低，因此新增parser模块，用于处理Oracle相关的语法;
+=== HNSW
 
-=== 新增PL\iSQL过程语言
+HNSW (Hierarchical Navigating Small World) 是一种基于图的索引算法，它由多层的邻近图组成，因此称为分层的 NSW 方法。它会为一张图按规则建成多层导航图，并让越上层的图越稀疏，结点间的距离越远；越下层的图越稠密，结点间的距离越近。HNSW 算法是一种经典的空间换时间的算法，它的搜索质量和搜索速度都比较高，但是它的内存开销也比较大，因为不仅需要将所有的向量都存储在内存中。还需要维护一个图的结构，也同样需要存储。
 
-- 同样为了减少Oracle兼容与postgres语法不同而导致测试用例冲突得情况，因此单独设计了一套Oracle专用的测试用例。该套测试用例由postgres原有测试框架拷贝修改而来;
+== 安装
 
+=== 源码安装
 
+** 设置PG_CONFIG环境变量
+```
+export PG_CONFIG=/usr/local/ivorysql/ivorysql-1.17/bin/pg_config
+```
+
+** 拉取pg_vector源码
+```
+git clone --branch v0.6.2 https://github.com/pgvector/pgvector.git
+```
+
+** 安装 pgvector
+```
+cd pgvector
+
+sudo --preserve-env=PG_CONFIG make
+sudo --preserve-env=PG_CONFIG make install
+```
+
+** 创建pgvector扩展
+```
+[ivorysql@localhost ivorysql-1.17]$ psql
+psql
+Type "help" for help.
+
+ivorysql=# create extension vector;
+CREATE EXTENSION
+```
+至此，pgvector扩展安装已完成。
+更多用例，请参考 https://github.com/pgvector/pgvector?tab=readme-ov-file#getting-started[pgvector文档]
+
+== Oracle兼容性
+
+在IvorySQL Oracle兼容模式下，pgvector扩展同样可以正确运行
+[TIP]
+建议用户使用1521端口进行测试， psql -p 1521
+
+=== 数据类型
+
+```
+ivorysql=# CREATE TABLE items5 (id bigserial PRIMARY KEY, name varchar2(20), num number(20), embedding bit(3));
+CREATE TABLE
+ivorysql=# INSERT INTO items5 (name, num, embedding) VALUES ('1st oracle data',0, '000'), ('2nd oracle data', 111, '111');
+INSERT 0 2
+ivorysql=# SELECT * FROM items5 ORDER BY bit_count(embedding # '101') LIMIT 5;
+ id |      name       | num | embedding
+----+-----------------+-----+-----------
+  2 | 2nd oracle data | 111 | 111
+  1 | 1st oracle data | 0   | 000
+```
+
+=== 匿名块
+
+```
+ivorysql=# declare
+i vector(3) := '[1,2,3]';
+begin
+raise notice '%', i;
+end;
+ivorysql-# /
+NOTICE:  [1,2,3]
+DO
+```
+
+=== 存储过程（PROCEDURE）
+```
+ivorysql=# CREATE OR REPLACE PROCEDURE ora_procedure()
+AS
+p vector(3) := '[4,5,6]';
+begin
+raise notice '%', p;
+end;
+/
+CREATE PROCEDURE
+ivorysql=# call ora_procedure();
+NOTICE:  [4,5,6]
+CALL
+```
+
+==== 函数（FUNCTION）
+```
+ivorysql=# CREATE OR REPLACE FUNCTION AddVector(a vector(3), b vector(3))
+RETURN vector(3)
+IS
+BEGIN
+RETURN a + b;
+END;
+/
+CREATE FUNCTION
+ivorysql=# SELECT AddVector('[1,2,3]','[4,5,6]') FROM DUAL;
+ addvector
+----------------
+ [5,7,9]
+(1 row)
+```

CN/modules/ROOT/images/p22.jpg

@@ -1,34 +1,26 @@
 :sectnums:
 :sectnumlevels: 5
-
 :imagesdir: ./_images
 
-== 新增GUC变量
+= Ivorysql框架设计
+
+== 目的
+- 为了对原有的postgres改动最小的前提下，实现对oracle兼容。我们需要实现双parser、双端口、模式PLPGSQL实现PL\iSQL的框架。实现流程图如下：
+
+image::p18.png[]
+
+== 功能
 
-为了兼容Oracle，需要在原有的GUC变量基础之上增加一些用于控制数据库执行结果的变量，以达到和Oracle行为一致的目的。
+=== 双端口设计
 
-为了以后更好的添加兼容的guc参数，以及为了更少的改动pg内核源码，我们需要设计一个框架将guc添加到一个统一的地方。
+- 保持了Ivorysql 5432端口兼容原有postgres情况，因此 Ivorysql采用另一个独立的端口登录，默认为1521。从该端口登录，默认采用oracle兼容模式。如果需要从5432端口登录且还要进入兼容模式，则需要通过compatible_mode参数进行设置;
 
+=== parser模块设计
 
-=== 实现
+- 为了将Oracle语法与postgres语法间的相互干扰降到最低，因此新增parser模块，用于处理Oracle相关的语法;
 
-添加兼容版本的guc参数时，我们需统一在 *ivy_guc.c* 文件中添加。其中 `Ivy_ConfigureNamesBool`、`Ivy_ConfigureNamesInt`、`Ivy_ConfigureNamesString`、`Ivy_ConfigureNamesReal` 和 `Ivy_ConfigureNamesEnum` 分别表示5种不同类型的guc参数，添加guc参数时，将guc的值添加到对应数组中即可。
+=== 新增PL\iSQL过程语言
 
+- 同样为了减少Oracle兼容与postgres语法不同而导致测试用例冲突得情况，因此单独设计了一套Oracle专用的测试用例。该套测试用例由postgres原有测试框架拷贝修改而来;
 
-=== 新增变量（目前）
 
-[cols="^1,^2"]
-|====
-| 变量名 | 描述
-| ivorysql.compatible_mode | 表示当前兼容哪种数据库（pg/oracle），可以通过show命令查看，set命令更改该变量，reset命令重置为连接时的数据库模式，reset all会影响该变量
-| ivorysql.database_mode | 表示当前数据库的模式（pg/oracle），可以通过show命令查看，set/reset/reset all命令不影响该变量
-| ivorysql.datetime_ignore_nls_mask | 表示日期格式是否会受NLS参数影响，默认为0，可以通过set命令设置，reset 命令重置，reset all命令会重置该变量
-| ivorysql.enable_emptystring_to_NULL | 取值为（on/off）,该变量为on时，会将插入的空字符串转成NULL值存储
-| ivorysql.listen_address | 表示兼容模式监听的地址，在初始化数据库时，从ivorysql.conf文件中读取该配置，在配置文件中修改该值，需要重启数据库生效，可以通过show命令查看
-| ivorysql.port | 表示兼容模式下连接的端口号，在初始化数据库时，从ivorysql.conf文件中读取该配置，在配置文件中修改该值，需要重启数据库生效，可以通过show命令查看
-| nls_date_format | 表示默认的日期格式，可以通过show命令查看，默认为‘YYYY-MM-DD’，可以通过set命令设置，可以通过reset命令重置回默认值，reset all 命令会重置该变量
-| nls_length_semantic | 兼容Oracle的同名参数，控制一个字符所占内存的大小
-| nls_timestamp_format | 兼容Oracle的同名参数，控制带时间的日期格式
-| nls_timestamp_tz_format | 兼容Oracle的同名参数，控制带时区的日期格式
-| shared_preload_libraries | 在初始话数据库时，从ivorysql.conf文件中读取，可以通过show命令查看，在配置文件中修改该值，重启数据库生效。
-|====

CN/modules/ROOT/nav.adoc

@@ -1,27 +1,34 @@
-
 :sectnums:
 :sectnumlevels: 5
 
-= 适配插件
-
-== 目的
+:imagesdir: ./_images
 
-- 本版本与pgddl、pgvector、pgroonga、postgis等插件进行了适配，以满足用户对于用户使用多样化数据库插件的需求。
+== 新增GUC变量
 
+为了兼容Oracle，需要在原有的GUC变量基础之上增加一些用于控制数据库执行结果的变量，以达到和Oracle行为一致的目的。
 
-== 说明
+为了以后更好的添加兼容的guc参数，以及为了更少的改动pg内核源码，我们需要设计一个框架将guc添加到一个统一的地方。
 
-- 通过RPM包安装的用户已经涵盖了如上插件，用户可以根据自身需求连接数据库后执行create extension语句即可。对于其他插件，用户可自行下载源码并于IvorySQL结合使用进行探索。
 
-== 使用
-详细使用说明请参照插件对应项目网址：
-|====
-|pgddl | https://github.com/lacanoid/pgddl 
-|pgvector | https://github.com/pgvector/pgvector
-|pgroonga | https://github.com/pgroonga/pgroonga
-|postgis | https://postgis.net
-|====
+=== 实现
 
+添加兼容版本的guc参数时，我们需统一在 *ivy_guc.c* 文件中添加。其中 `Ivy_ConfigureNamesBool`、`Ivy_ConfigureNamesInt`、`Ivy_ConfigureNamesString`、`Ivy_ConfigureNamesReal` 和 `Ivy_ConfigureNamesEnum` 分别表示5种不同类型的guc参数，添加guc参数时，将guc的值添加到对应数组中即可。
 
 
+=== 新增变量（目前）
 
+[cols="^1,^2"]
+|====
+| 变量名 | 描述
+| ivorysql.compatible_mode | 表示当前兼容哪种数据库（pg/oracle），可以通过show命令查看，set命令更改该变量，reset命令重置为连接时的数据库模式，reset all会影响该变量
+| ivorysql.database_mode | 表示当前数据库的模式（pg/oracle），可以通过show命令查看，set/reset/reset all命令不影响该变量
+| ivorysql.datetime_ignore_nls_mask | 表示日期格式是否会受NLS参数影响，默认为0，可以通过set命令设置，reset 命令重置，reset all命令会重置该变量
+| ivorysql.enable_emptystring_to_NULL | 取值为（on/off）,该变量为on时，会将插入的空字符串转成NULL值存储
+| ivorysql.listen_address | 表示兼容模式监听的地址，在初始化数据库时，从ivorysql.conf文件中读取该配置，在配置文件中修改该值，需要重启数据库生效，可以通过show命令查看
+| ivorysql.port | 表示兼容模式下连接的端口号，在初始化数据库时，从ivorysql.conf文件中读取该配置，在配置文件中修改该值，需要重启数据库生效，可以通过show命令查看
+| nls_date_format | 表示默认的日期格式，可以通过show命令查看，默认为‘YYYY-MM-DD’，可以通过set命令设置，可以通过reset命令重置回默认值，reset all 命令会重置该变量
+| nls_length_semantic | 兼容Oracle的同名参数，控制一个字符所占内存的大小
+| nls_timestamp_format | 兼容Oracle的同名参数，控制带时间的日期格式
+| nls_timestamp_tz_format | 兼容Oracle的同名参数，控制带时区的日期格式
+| shared_preload_libraries | 在初始话数据库时，从ivorysql.conf文件中读取，可以通过show命令查看，在配置文件中修改该值，重启数据库生效。
+|====