devilfish-dbms

Version:

a database that based on key-value map and is successful in deal with saved in disk and high-performance in select that act as a memory-based database

603 lines (368 loc) • 18.3 kB

Markdown

# Devilfish DBMS 用户手册 & API 使用说明 Devilfish DBMS 是一款高性能的数据库管理系统，专为高维数据处理、分析与可视化设计，支持丰富的 SQL 扩展、机器学习、张量操作、数据导入导出等功能。支持 HTTP API 及命令行两种操作方式。 # 启动方式 ```bash # Download and install nvm: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash # in lieu of restarting the shell \. "$HOME/.nvm/nvm.sh" # Download and install Node.js: nvm install 22 # Verify the Node.js version: node -v # Should print "v22.17.1". nvm current # Should print "v22.17.1". # Verify npm version: npm -v # Should print "10.9.2". npm install -g cnpm --registry=https://registry.npmmirror.com git clone https://gitee.com/mumu2009/devilfish-dbms.git cd devilfish-dbms cnpm install node api.js ``` #### 注意，high-vx.x-cluster的启动方式有部分不同，详见./high-v3.0-cluster/readme.md --- ## 一、系统特性 - 高维数据存储与查询 - 分区表支持（基于哈希分区） - 多种索引与聚类算法（复合索引、金字塔索引、递归球面编织、KMeans等） - SQL 扩展与批量操作 - 机器学习模型（线性回归、朴素贝叶斯、多项式拟合等） - 张量创建与运算 - 数据可视化与 Web 可视化文件生成 - 数据压缩与解压缩（黎曼球面映射压缩） - 扩展模块与脚本支持 - 数据导入导出能力（CSV等） - 模糊函数与泰勒展开 - 交集点插入与几何运算 ##### 在本数据库中每个表最大只能一次性初始化2^29个字符，也就是说所有的sql语句的长度不能超过2^29=536870912=524.288MB个字符，在执行脚本时为整个脚本的长度不应超过这一限制 --- ## 二、API 启动与基础信息 - 默认监听端口：`3125` - 支持外网访问（监听 `0.0.0.0`） - 支持 CORS 跨域 - 支持 JSON 及 URL 编码表单请求 ### 1. `/execute` 路由 - **方法**：POST - **参数**：JSON 格式，需包含 `command` 字段 - **返回**：执行日志文本 #### 示例请求 ```json POST /execute { "command": "create database test" } ``` #### 返回示例 ``` Database created Command executed successfully ``` --- ## 三、命令总览 #### 注意，下文中的指令除单列一行进行说明外，功能一般同mysql的同名命令。标有'*'的功能表示下个版本开放，标有'**'的功能则会在之后的版本中开放（不包含下一个版本）所有的功能后均没有分号，以换行为下一条指令的标志 ### 1. 数据库管理 - `create database <database_name>` - `use <database_name>` - `drop database <database_name>` - `show databases` - `clone database <source_database> to <target_database>` - `mount database from ./path` - `demount database` ### 2. 表管理 - `create table <table_name> (<column1>,<column2>, ...) partition by <partition_key> partitions = <num_partitions>` 注意，这里'()'内不能有空格，支持指定分区数量，默认有10个基于hash(partition_key)的分区同时，由于硬盘存储的限制，目前必须有id字段（如果为硬盘表），同时id项不能为0，建议id项放在末尾如果想要更改重新加载后的必须有的字段，可以搜索并修改loaddataasync和_loadsignalDatabase方法中的partitionKey的值 - `add dimension <column_name> to <table_name>` 这里表示在一个表上添加一个维度（字段） - `remove dimension <column_name> from <table_name>` 这里表示在一个表上删除一个维度（字段） - `drop table <table_name>` - `show tables` - `clone table <source_table> to <target_table>` ### 3. 数据操作 #### 基础操作 - `insert into <table_name> values {<key1>:<value1>, ...}` - `insert batch into <table_name> values [{...}, {...}]` 批量插入，每一个{}中的内容同上一个insert into 指令中的values值，在数据量较大时有优势，数据量小时有劣势每一次插入的最大值最好不要超过72MB 否则无法保证数据库的稳定性 #### 更新操作 - `update <table_name> set <column>=<new_value> where <condition>` 注意condition不能省略 - `update batch <table_name> set [{key:<primary_key_value>, newData:{<field1>:<value1>, ...}}, ...]` 批量更新多行记录 - `update batch column <table_name> set {<field1>=<value1>, <field2>=<value2>} where <condition>` 批量更新指定条件下的列 #### 删除操作 - `delete from <table_name> where <condition>` 注意condition不能省略，支持主键精确匹配O(1)操作 #### 查询操作 - `select * from <table_name> where <condition>` - `select <column1>,<column2>,... from <table_name> where <condition>` #### 条件语法支持支持复杂的WHERE条件： - 基础比较：`=`, `>`, `<`, `>=`, `<=`, `<>` - 逻辑运算：`AND`, `OR`, `NOT` - 子查询：`{column:target_column, subquery:SELECT statement}` ### 4. 索引与高维空间 **注意：所有的索引在同一时间只能有一个，所有的索引都可以动态增/删/改，但是速度较慢，建议在多次插入时直接删除索引并重建** #### 复合索引 - `create composite index on <table_name> dimensions <dimension1>,<dimension2>,...` 复合索引，基于表上的维度 - `query composite index on <table_name> with dimensions {dim1:[min,max], dim2:[min,max], ...}` 根据索引composite index，查找dim范围内的信息 - `destroy composite index on <table_name>` #### 金字塔索引 - `create pyramid index on <table_name> with max_capacity=<max_capacity> and k=<k>` 金字塔索引(树状索引)，基于表，max_capacity决定了叶层中每个叶上的点个数，建议max_capacity>k - `query pyramid index on <table_name> with point=[x,y,...]` 根据索引pyramid index查找距离某一点最近的k个点 - `destroy pyramid index` #### 递归球面编织索引 - `create recursive sphere weaving on <table_name>` 递归球面编织为集合索引，将高维点折射到低维 - `query recursive sphere weaving on <table_name> with point=[x,y,...] with k=<k>` - `query recursive sphere weaving on <table_name> with point=[x,y,...]` 根据索引recursive sphere weaving查找距离某一点最近的k个点（默认5个） - `destroy recursive sphere weaving` ### 5. 数据可视化 - `visualize <table_name> with <dimensions>` 加载完成后，可以在API的'/'下查看(get)，该选项dimensions应为三个分量，但注意，只有前两个分量有用，根据这两个分量数据点将被映射到球面上 ### 6. 脚本与扩展 #### 扩展管理 - `load extension <extension_path>` - `extension <extension_name> <command> [args...]` - `remove extension <extension_name>` - `show extensions` #### 脚本执行 - `execute script <script_path>` 这里的script为一个命名为*.sql的文件，文件中是由sql语句组成的组合例： ```sql sql1 sql2 sql3 ``` ### 7. 数据生成与噪声 #### 注意：这些功能需要先加载 ai-direction 扩展模块： ``` load extension main-ai-direction.js ``` #### 数据点生成 - `generate points on <table_name> with distribution <distribution_type> and parameters {<param1>:<value1>, ...}` 支持的分布类型： - uniform: 均匀分布，参数格式：`{numPoints:100, x:{min:0,max:10}, y:{min:0,max:10}}` - normal: 正态分布，参数格式：`{numPoints:100, x:{mean:0,stdDev:1}, y:{mean:0,stdDev:1}}` - sphere: 球面分布，参数格式：`{numPoints:100, radius:1}` - `extension ai-direction generate <table_name> <distribution_type> <count> <param1> <param2>` 生成指定分布的数据点并插入表中 - distribution_type: normal/gaussian（正态分布）或 uniform（均匀分布） - count: 生成的点数 - 正态分布参数：mean（均值）, stdDev（标准差） - 均匀分布参数：min（最小值）, max（最大值） - `extension ai-direction addnoise <table_name> <noise_type> <column> <param1> <param2>` 为表中指定列添加噪声 - noise_type: gaussian（高斯噪声） - column: 目标列名 - 高斯噪声参数：mean（均值）, stdDev（标准差） ### 8. 数据压缩与解压缩 #### 压缩对性能损失较大，最好不要启用压缩功能，默认该选项为disable - `enable compression for <table_name>` - `disable compression for <table_name>` **系统采用黎曼球面映射压缩算法，支持有损压缩，适用于高维数据降维存储** ### 9. 数据导入与导出 - `import csv <table_name> from <file_path>` 从CSV文件导入数据，支持自动类型推断和数据清理 ### 10. 几何运算与数学分析 #### 模糊函数与泰勒展开 - `get fuzzy function <table_name> on <dimension1> and <dimension2>` 获取基于两个维度的模糊函数 - `taylor expand <table_name> on <dimension1> and <dimension2> at (<x0>,<y0>) order <order>` 在指定点进行泰勒展开 #### 交集点插入 - `insert intersection into <table_name> dimensions <dimension1>,<dimension2>,... function <function_expression> radius <radius> resolution <resolution>` 计算函数与球面的交集点并插入表中 ### 11. 聚类分析 - `kmeans cluster <table_name> on <dimension1>,<dimension2>,... with k <k>` 对指定维度执行K-means聚类，支持多维数据聚类，结果将添加cluster_label字段 ### 12. SQL 扩展与统计分析 #### 注意：这些功能需要先加载 sql-direction 扩展模块： ``` load extension main-sql-direction.js ``` #### 逻辑运算 - `extension sql-direction or <table_name> <query1> <query2>` 对两个查询结果执行 OR 操作，返回并集 - `extension sql-direction and <table_name> <query1> <query2>` 对两个查询结果执行 AND 操作，返回交集 #### 表连接 - `extension sql-direction join <table_name1> <table_name2> <join_key>` 基于指定键对两个表执行内连接 #### 排序与限制 - `extension sql-direction order <table_name> <column> [asc|desc]` 按指定列对结果进行升序或降序排序（默认升序） - `extension sql-direction limit <table_name> <limit_number>` 限制返回结果的数量 #### 数据选择与复制 - `extension sql-direction select <table_name> <new_table_name> <query>` 将查询结果插入到新表中 #### 统计函数 - `extension sql-direction average <table_name> <column>` 计算指定列的平均值 - `extension sql-direction amount <table_name>` 返回表中记录的总数 - `extension sql-direction variance <table_name> <column>` 计算指定列的方差 - `extension sql-direction min <table_name> <column>` 返回指定列的最小值 - `extension sql-direction max <table_name> <column>` 返回指定列的最大值 - `extension sql-direction sum <table_name> <column>` 计算指定列的总和 - `extension sql-direction median <table_name> <column>` 计算指定列的中位数 #### 分组与聚合 - `extension sql-direction group <table_name> <group_column> <aggregate_column> <aggregate_function>` 按指定列分组并应用聚合函数（sum, avg, min, max, count） - `extension sql-direction having <table_name> <group_column> <aggregate_column> <aggregate_function> <condition>` 对分组结果应用 HAVING 条件过滤 #### 子查询与存在性检查 - `extension sql-direction exists <table_name> <sub_query>` 检查子查询是否返回结果 #### 数据格式化 - `extension sql-direction round <table_name> <column> <precision>` 将指定列的数值四舍五入到指定精度 - `extension sql-direction format <table_name> <column> <format_string>` 使用格式字符串格式化指定列（支持 {} 和 {value} 占位符） ### 13. 机器学习扩展 #### 注意：这些功能需要先加载 ai-direction 扩展模块： ``` load extension main-ai-direction.js ``` #### 线性回归 - `extension ai-direction createlinear <table_name> <features> <target>` 创建线性回归模型 - features: 特征列名，多个用逗号分隔 - target: 目标列名 - `extension ai-direction predictlinear <table_name> <value1> <value2> ...` 使用线性回归模型进行预测 #### 朴素贝叶斯 - `extension ai-direction createbayes <table_name> <features> <target>` 创建朴素贝叶斯模型 - features: 特征列名，多个用逗号分隔 - target: 目标列名 - `extension ai-direction predictbayes <table_name> <value1> <value2> ...` 使用朴素贝叶斯模型进行预测 #### 多项式拟合 - `extension ai-direction polynomial <table_name> <degree> [x_column] [y_column]` 对数据进行多项式拟合 - degree: 多项式阶数 - x_column: X轴列名（默认为'x'） - y_column: Y轴列名（默认为'y'） #### 张量操作 - `extension ai-direction createtensor <tensor_name> <rows> <cols>` 创建指定形状的张量（当前仅支持2D张量） - `extension ai-direction tensor <operation> <tensor1_name> [tensor2_name]` 执行张量运算 - operation: transpose（转置）, add（加法）, multiply（矩阵乘法） - 转置操作只需一个张量，其他操作需要两个张量 ### 14. 其它功能 - `exit` - `-- <comment>`（注释行，以--开头的行会被忽略） - `load all`重新从硬盘中加载数据 --- ## 四、高级特性说明 ### 1. 分区表架构 - 采用哈希分区策略，根据分区键自动分配数据到不同分区 - 支持自定义分区数量，默认10个分区 - 主键查询支持O(1)直接定位分区 - 分区间负载自动均衡 ### 2. 压缩算法 - 采用黎曼球面映射压缩算法 - 支持高维数据到低维的有损压缩 - 圆锥投影技术实现空间数据压缩 - 可配置压缩参数和焦点 ### 3. 索引优化 - 复合索引支持多维范围查询 - 金字塔索引提供k近邻搜索 - 递归球面编织实现高维数据降维索引 - 索引动态维护，支持实时更新 ### 4. 查询优化 - 主键查询自动优化为O(1)操作 - 复杂条件查询支持索引加速 - 查询结果缓存机制 - 分区剪枝优化 --- ## 五、日志与调试 - 所有命令执行日志会通过 `console.log` 输出，并写入 `dbms.log` 文件。 - `/execute` 路由返回本次命令的所有日志输出。 - 所有 `console.log(obj)` 会自动转为 JSON 字符串，便于日志分析。 - 支持DEBUG、INFO、WARN、ERROR四个日志级别 --- ## 六、批量导入与性能建议 - 大批量插入时建议关闭自动持久化，插入完毕后再手动保存数据库。 - 大批量导入时建议删除所有索引，导入完成后再重建索引。 - `insert batch` 指令不自动保存，建议插入或更改一条工具表数据以触发保存。 - 使用批量更新命令提高大量数据修改的性能 - 合理设置分区数量以优化查询性能 --- ## 七、Web 可视化 - 访问 `http://<服务器IP>:3125/entrence` 可查看 `entr.html` 页面（需自行开发前端）。 - 支持生成points.json可视化数据文件 - 支持三维球面投影可视化 --- ## 八、扩展与自定义 - 支持通过 `load extension 扩展路径` 加载自定义扩展 - 扩展需导出包含execute对象的模块 - 支持扩展的动态加载、卸载和管理 - 内置ai-direction和sql-direction扩展模块 --- ## 九、常见问题 - 数据库文件损坏修复：如遇 `incorrect header check`，请执行 `node repairdb.js` 查看说明。 - 速度过低：注意剩余内存，本数据库的性能极大地取决于内存量 - 分区键选择：建议选择数据分布均匀的字段作为分区键 - 索引选择：根据查询模式选择合适的索引类型 - 压缩使用：仅在存储空间紧张时启用压缩功能 --- ## 十、示例：通过 HTTP 执行命令 ```bash # 创建数据库 curl -X POST http://localhost:3125/execute -H "Content-Type: application/json" -d "{\"command\":\"create database test\"}" # 使用数据库 curl -X POST http://localhost:3125/execute -H "Content-Type: application/json" -d "{\"command\":\"use test\"}" # 创建表 curl -X POST http://localhost:3125/execute -H "Content-Type: application/json" -d "{\"command\":\"create table users (id,name,age) partition by id partitions = 5\"}" # 插入数据 curl -X POST http://localhost:3125/execute -H "Content-Type: application/json" -d "{\"command\":\"insert into users values {id:1, name:Alice, age:25}\"}" # 查询数据 curl -X POST http://localhost:3125/execute -H "Content-Type: application/json" -d "{\"command\":\"select * from users where id=1\"}" ``` --- ## 十一、完整示例工作流 ```sql -- 创建和使用数据库 create database analytics use analytics -- 创建分区表 create table sales_data (id,region,amount,date) partition by region partitions = 8 -- 批量插入数据 insert batch into sales_data values [ {id:1, region:north, amount:1000, date:2024-01-01}, {id:2, region:south, amount:1500, date:2024-01-02}, {id:3, region:east, amount:1200, date:2024-01-03} ] -- 创建复合索引 create composite index on sales_data dimensions region,amount -- 范围查询 query composite index on sales_data with dimensions {region:[north,south], amount:[1000,2000]} -- K-means聚类 kmeans cluster sales_data on amount,id with k 3 -- 数据可视化 visualize sales_data with amount,id,region -- 加载扩展并执行统计 load extension main-sql-direction.js extension sql-direction average sales_data amount extension sql-direction group sales_data region amount sum ``` --- 如需更多命令或高级用法，请查阅源码或联系开发。