devilfish-dbms

v2.0.1

Published

16 days ago

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

0High
0Medium
0Low

mumu2009

database DBMS key-value DISK

Devilfish DBMS 用户手册 & API 使用说明

Devilfish DBMS 是一款高性能的数据库管理系统，专为高维数据处理、分析与可视化设计，支持丰富的 SQL 扩展、机器学习、张量操作、数据导入导出等功能。支持 HTTP API 及命令行两种操作方式。

启动方式

# 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 字段
返回：执行日志文本

示例请求

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语句组成的组合
例：
```
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 执行命令

# 创建数据库
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\"}"

十一、完整示例工作流

-- 创建和使用数据库
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

如需更多命令或高级用法，请查阅源码或联系开发。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Devilfish DBMS 用户手册 & API 使用说明

启动方式

注意，high-vx.x-cluster的启动方式有部分不同，详见./high-v3.0-cluster/readme.md

一、系统特性

在本数据库中 每个表最大只能一次性初始化2^29个字符，也就是说 所有的sql语句的长度不能超过2^29=536870912=524.288MB个字符，在执行脚本时为整个脚本的长度不应超过这一限制

二、API 启动与基础信息

1. /execute 路由

示例请求

返回示例

三、命令总览

注意，下文中的指令除单列一行进行说明外，功能一般同mysql的同名命令。标有'*'的功能表示下个版本开放，标有'**'的功能则会在之后的版本中开放（不包含下一个版本）所有的功能后均没有分号，以换行为下一条指令的标志

1. 数据库管理

2. 表管理

3. 数据操作

基础操作

更新操作

删除操作

查询操作

条件语法支持

4. 索引与高维空间

复合索引

金字塔索引

递归球面编织索引

5. 数据可视化

6. 脚本与扩展

扩展管理

脚本执行

7. 数据生成与噪声

注意：这些功能需要先加载 ai-direction 扩展模块：

数据点生成

8. 数据压缩与解压缩

压缩对性能损失较大，最好不要启用压缩功能，默认该选项为disable

9. 数据导入与导出

10. 几何运算与数学分析

模糊函数与泰勒展开

交集点插入

11. 聚类分析

12. SQL 扩展与统计分析

注意：这些功能需要先加载 sql-direction 扩展模块：

逻辑运算

表连接

排序与限制

数据选择与复制

统计函数

分组与聚合

子查询与存在性检查

数据格式化

13. 机器学习扩展

注意：这些功能需要先加载 ai-direction 扩展模块：

线性回归

朴素贝叶斯

多项式拟合

张量操作

14. 其它功能

四、高级特性说明

1. 分区表架构

2. 压缩算法

3. 索引优化

4. 查询优化

五、日志与调试

六、批量导入与性能建议

七、Web 可视化

八、扩展与自定义

九、常见问题

十、示例：通过 HTTP 执行命令

十一、完整示例工作流

在本数据库中每个表最大只能一次性初始化2^29个字符，也就是说所有的sql语句的长度不能超过2^29=536870912=524.288MB个字符，在执行脚本时为整个脚本的长度不应超过这一限制

1. `/execute` 路由