diff --git a/CONTRIBUTING-CN.md b/CONTRIBUTING-CN.md
index 80c3bb42..a57c294e 100644
--- a/CONTRIBUTING-CN.md
+++ b/CONTRIBUTING-CN.md
@@ -2,7 +2,6 @@
欢迎您的参与，以帮助改善 Datalayers 文档。当您反馈问题，编辑、新增、翻译文档内容时，可以为 Datalayers 开源社区提供非常有价值的帮助。
-
## 目录
- [文档编写指南](#文档编写指南)
@@ -14,12 +13,10 @@
- [PR 自动检查](#pr-自动检查)
- [如何寻求帮助](#如何寻求帮助)
-
## 文档编写指南
为了确保文档的一致性，我们要求所有贡献者参考我们的 [文档编写指南](./DOCS-WRITING-GUIDE-CN.md)，该指南对文档**目录配置**及 **Markdown 书写规范**进行了详细的说明。
-
## 如何贡献文档
Datalayers 的文档发布在 [https://docs.datalayers.io/](https://docs.datalayers.io/)，您可以通过以下几种方式贡献文档。
@@ -70,7 +67,7 @@ todo截图
2. 将 Fork 的仓库 Clone 到本地，然后进入本地目录，添加上游仓库。
- ```
+ ```shell
git remote add upstream https://github.com/datalayers-io/docs-datalayers.git
```
@@ -102,12 +99,10 @@ Datalayers 中文文档一般会先于英文文档发布，所以文档翻译大
回到步骤 2 里认领的 PR 里，依次添加 2 条评论：`/unlabel translation/doing` 及 `/label translation/done`，表明翻译已完成。
-
## PR 自动检查
文档项目将会根据 [文档编写指南](./DOCS-WRITING-GUIDE-CN.md) 里的规则进行自动检查，检查通过的 PR 才能被合并。假如你提 PR 时遇到了 markdownlint check 失败，报错信息里会明确提示哪一个文件的哪一行出了什么问题，请根据提示修改后再更新到 PR 里。
-
## 如何寻求帮助
在进行文档贡献时遇到任何问题，都可以通过以下方式联系我们获取帮助。
@@ -117,4 +112,3 @@ Datalayers 中文文档一般会先于英文文档发布，所以文档翻译大
todo截图
- 直接提交 GitHub Issue：[https://github.com/datalayers-io/docs-datalayers/issues/new](https://github.com/datalayers-io/docs-datalayers/issues/new)。
-
diff --git a/CONTRIBUTING-EN.md b/CONTRIBUTING-EN.md
index 6072aea1..e024a73d 100644
--- a/CONTRIBUTING-EN.md
+++ b/CONTRIBUTING-EN.md
@@ -17,14 +17,12 @@ Thank you for your contributions to Datalayers open-source project.
- [PR automatic check](#pr-automatic-check)
- [How to get help](#how-to-get-help)
-
## Documentation Writing Guide
To ensure consistency throughout all Datalayers documentation,
we kindly request all contributors reference our [Documentation Writing Guide](./DOCS-WRITING-GUIDE-EN.md).
This guideline provides detailed instructions on document **directory configuration** and **Markdown writing specifications**.
-
## How to contribute
Datalayers's documentation is published at [https://docs.datalayers.io/](https://docs.datalayers.io/).
@@ -82,7 +80,8 @@ We recommend first-time contributors to directly use the [Online editing](#onlin
1. Open the document repository [https://github.com/datalayers-io/docs-datalayers](https://github.com/datalayers-io/docs-datalayers) for Fork.
1. Clone the forked repository into your local workspace and then go to the local directory and add the upstream repository.
- ```
+
+ ```shell
git remote add upstream https://github.com/datalayers-io/docs-datalayers.git
```
@@ -92,14 +91,14 @@ We recommend first-time contributors to directly use the [Online editing](#onlin
1. Optional: Checkout a work-branch `git checkout -b my-first-pr-branch-for-datalayers-1.0`
1. Edit, commit, and push the branch to your fork
- ```
+
+ ```shell
git commit -a -m 'docs(WHICH_DOC): fix xxxx in WHICH_DOC'
git push origin my-first-pr-branch-for-datalayers-1.0
```
1. Create a Pull request from your forked repository to the upstream repository.
-
## PR automatic check
Document projects will be automatically checked according to the rules in the [Documentation Writing Guide](./DOCS-WRITING-GUIDE-EN.md).
@@ -111,5 +110,4 @@ so please follow the instructions to modify and update the PR.
If you encounter any problems when contributing to the documentation, you can contact us for getting help in the following methods.
-
- Submit the GitHub Issue directly: [https://github.com/datalayers-io/docs-datalayers/issues/new](https://github.com/datalayers-io/docs-datalayers/issues/new).
diff --git a/dir.yaml b/dir.yaml
index dfb093c0..2cdf0674 100644
--- a/dir.yaml
+++ b/dir.yaml
@@ -63,28 +63,21 @@
- title_en: Arrow Flight SQL
title_cn: Arrow Flight SQL
path: development-guide/arrow-flight-sql
+ - title_en: PostgreSQL Protocol
+ title_cn: PostgreSQL 协议
+ path: development-guide/postgresql/overview
+ - title_en: Prometheus Protocol
+ title_cn: Prometheus 协议
+ path: development-guide/prometheus/overview
- title_en: REST API
title_cn: REST API
- collapsed: true
- children:
- - title_en: Authentication
- title_cn: 认证
- path: development-guide/auth-with-restapi
- - title_en: Insert
- title_cn: 数据写入
- path: development-guide/insert-with-restapi
- - title_en: Query
- title_cn: 数据查询
- path: development-guide/query-with-restapi
- - title_en: ERROR CODE
- title_cn: 错误码说明
- path: development-guide/errno-with-restapi
- - title_en: Multi-language Access Examples
- title_cn: 多语言接入示例
- path: development-guide/multi-language-examples
+ path: development-guide/rest-api/overview
- title_en: InfluxDB Line Protocol
title_cn: InfluxDB Line Protocol
path: development-guide/writing-with-influxdb-line-protocol
+ - title_en: Redis Protocol
+ title_cn: Redis 协议
+ path: development-guide/redis
- title_en: Table design best practices
title_cn: 数据表设计
path: development-guide/table-design/overview
@@ -98,7 +91,7 @@
path: development-guide/table-design/timeseries-table-design
- title_en: High-performance writing
title_cn: 高性能写入
- path: development-guide/high-performance-writing
+ path: development-guide/high-performance-ingestion
- title_en: Query Performance Tuning
title_cn: 查询加速
path: development-guide/query-performance-tuning-overview
@@ -126,7 +119,7 @@
path: development-guide/query-optimization/hints/index
- title_en: Downsampling
title_cn: 时间窗口查询
- path: development-guide/downsampling
+ path: development-guide/time-window-aggregation-query
- title_en: Object Storage
title_cn: 对象存储
path: development-guide/object-storage
@@ -352,6 +345,20 @@
title_cn: Redis 兼容性
path: key-value-data-model/redis-compatibility
+- title_en: Prometheus
+ title_cn: Prometheus
+ collapsed: true
+ children:
+ - title_en: Overview
+ title_cn: 概述
+ path: prometheus/overview
+ - title_en: Quick Start
+ title_cn: 快速开始
+ path: prometheus/quick-start
+ - title_en: PromQL Compatibility
+ title_cn: PromQL 兼容性
+ path: prometheus/promql-compatibility
+
- title_en: Operation Guide
title_cn: 运维指南
collapsed: true
@@ -395,9 +402,15 @@
- title_en: Log Configuration
title_cn: 日志配置
path: admin/configuration-fields/log
+ - title_en: Audit logs
+ title_cn: 审计日志
+ path: admin/configuration-fields/audit-logs
- title_en: License Configuration
title_cn: License 配置
path: admin/configuration-fields/license
+ - title_en: MCP
+ title_cn: MCP 配置
+ path: admin/configuration-fields/mcp
- title_en: Command Line Interface
title_cn: 命令行接口
path: admin/datalayers-cli
@@ -444,8 +457,8 @@
title_cn: DBeaver
path: integration/datalayers-with-dbeaver
- title_en: User & Security
- title_cn: 用户与安全
- collapsed: false
+ title_cn: 安全与合规
+ collapsed: true
children:
- title_en: TLS
title_cn: 连接加密(TLS)
@@ -481,6 +494,9 @@
- title_en: Privileges
title_cn: 权限管理
path: user-security/rbac/privilege
+ - title_en: Audit Logs
+ title_cn: 审计日志
+ path: user-security/audit-logs
- title_en: Release Notes
title_cn: 版本发布说明
collapsed: true
diff --git a/en_US/development-guide/auth-with-restapi.md b/en_US/admin/configuration-fields/audit-logs.md
similarity index 100%
rename from en_US/development-guide/auth-with-restapi.md
rename to en_US/admin/configuration-fields/audit-logs.md
diff --git a/en_US/development-guide/downsampling.md b/en_US/admin/configuration-fields/mcp.md
similarity index 100%
rename from en_US/development-guide/downsampling.md
rename to en_US/admin/configuration-fields/mcp.md
diff --git a/en_US/development-guide/errno-with-restapi.md b/en_US/development-guide/high-performance-ingestion.md
similarity index 100%
rename from en_US/development-guide/errno-with-restapi.md
rename to en_US/development-guide/high-performance-ingestion.md
diff --git a/en_US/development-guide/high-performance-reading.md b/en_US/development-guide/postgresql/overview.md
similarity index 100%
rename from en_US/development-guide/high-performance-reading.md
rename to en_US/development-guide/postgresql/overview.md
diff --git a/en_US/development-guide/high-performance-writing.md b/en_US/development-guide/prometheus/overview.md
similarity index 100%
rename from en_US/development-guide/high-performance-writing.md
rename to en_US/development-guide/prometheus/overview.md
diff --git a/en_US/development-guide/insert-with-restapi.md b/en_US/development-guide/redis.md
similarity index 100%
rename from en_US/development-guide/insert-with-restapi.md
rename to en_US/development-guide/redis.md
diff --git a/en_US/development-guide/multi-language-examples.md b/en_US/development-guide/rest-api/overview.md
similarity index 100%
rename from en_US/development-guide/multi-language-examples.md
rename to en_US/development-guide/rest-api/overview.md
diff --git a/en_US/development-guide/query-with-restapi.md b/en_US/development-guide/time-window-aggregation-query.md
similarity index 100%
rename from en_US/development-guide/query-with-restapi.md
rename to en_US/development-guide/time-window-aggregation-query.md
diff --git a/en_US/prometheus/overview.md b/en_US/prometheus/overview.md
new file mode 100644
index 00000000..e69de29b
diff --git a/en_US/prometheus/promql-compatibility.md b/en_US/prometheus/promql-compatibility.md
new file mode 100644
index 00000000..e69de29b
diff --git a/en_US/prometheus/quick-start.md b/en_US/prometheus/quick-start.md
new file mode 100644
index 00000000..e69de29b
diff --git a/en_US/user-security/audit-logs.md b/en_US/user-security/audit-logs.md
new file mode 100644
index 00000000..e69de29b
diff --git a/zh_CN/admin/backup-restore.md b/zh_CN/admin/backup-restore.md
index 95f63475..f257a76e 100644
--- a/zh_CN/admin/backup-restore.md
+++ b/zh_CN/admin/backup-restore.md
@@ -1,9 +1,11 @@
# 数据备份与恢复
## 概述
+
数据库备份和恢复的目的是为了保护数据安全，防止数据丢失或损坏。通过定期备份，能够在系统故障、硬件损坏或人为错误时，将数据库恢复到最近的可用状态，确保业务连续性和数据完整性。本章节主要介绍数据备份与恢复功能。
## 工具使用说明
+
`dldump` 工具提供了丰富的选项以供配置，您可以通过执行 `dldump --help` 以查看 `dldump` 的所有子命令和选项。此处对一些重要的选项进行说明：
| 参数 | 简写
| 描述 |
@@ -25,17 +27,21 @@
| --help | | show this help, then exit |
## 备份与恢复
+
以下通过一个示例来介绍 **dldump** 工具的使用。这个示例首先为单机版 Datalayers 写入一些数据，然后使用 **dldump** 将数据导出到备份目录；再创建一个新的 Datalayers 实例，从备份目录加载数据并写入到新的 Datalayers 实例；最后使用 **dlsql** 工具查询新的 Datalayers 实例，以验证成功执行了备份与恢复。
为方便叙述，本文将被备份的 Datalayers 实例称为 1 号节点，将被恢复的 Datalayers 实例称为 2 号节点。
### 准备工作
+
启动 1 号节点：
+
``` shell
datalayers standalone -c datalayers.toml
```
使用 `dlsql` 工具创建数据库 `test`、表 `device`、以及往 `device` 表写入一些数据，对应的 SQL 及输出如下：
+
``` sql
> CREATE DATABASE test;
Query OK, 0 rows affected. (0.001 sec)
@@ -66,40 +72,52 @@ Query OK, 10 rows affected. (0.002 sec)
```
### 数据备份
+
执行数据备份：
+
``` shell
dldump -h localhost -P 8360 -d test -o /tmp/datalayers/backup
```
+
该命令将 1 号节点的数据导出到指定的 `/tmp/datalayers/backup` 目录。
备份完成后，`/tmp/datalayers/backup` 目录将会有如下的层次结构：
-```
+
+```text
backup
- test
- create.sql
- device_0.parquet
```
+
根据 `dldump` 工具的设计，每个数据库会有一个独立的备份目录，这个目录会以数据库的名称命名。例如，`test` 数据库对应一个同名的 `test` 目录。数据库目录下存在一个 `create.sql` 文件，它里面包含了这个数据库的建库语句和每个表的建表语句。数据库目录下的其他文件则为表数据文件。表数据文件的命名规则是 `_.parquet`，`table_name` 为表名，如示例中的 `device` 表；`sequence` 表示该数据文件为这张表的第几个数据文件，`dldump` 会根据数据导出时的顺序对数据文件进行排序。
> **注**：如果您开启了文件系统的“显示隐藏文件和目录”的选项，那么您还会在 `test` 目录下发现 `.schema` 文件。为了保证数据恢复时的 schema 与备份时的一致，`dldump` 在备份时会将所有表的 schema 统一编码到 `.schema` 文件中，在恢复时再从中解码出 schema。
### 数据恢复
+
启动 2 号节点：
+
``` shell
datalayers standalone -c datalayers.toml
```
+
请注意，您需要对配置文件 `datalayers.toml` 做必要的修改。一方面，2 号节点使用的数据目录 `storage.local.path` 必须与 1 号节点不同，否则会导致恢复失败。另一方面，如果 1 号节点没有关闭，那么您需要改动 2 号节点使用的 SQL 服务端口 `server.port` 和 HTTP 服务端口 `server.http_port`，以确保其能够成功启动。
执行数据恢复：
+
``` shell
dldump -h localhost -P 8360 -i /tmp/datalayers/backup
```
+
该命令将从 `/tmp/datalayers/backup` 路径加载备份文件，并将数据写入到 2 号节点中。待该命令执行完成后，便完成了数据恢复。
### 验证数据
+
使用 `dlsql` 工具对 2 号节点执行查询，以验证恢复数据的完整性。
验证 `test` 数据库被成功恢复：
+
``` sql
> SHOW DATABASES;
+--------------------+---------------------------+
@@ -110,9 +128,11 @@ dldump -h localhost -P 8360 -i /tmp/datalayers/backup
+--------------------+---------------------------+
2 rows in set (0.003 sec)
```
+
> **注**：`information_schema` 是每个 Datalayers 实例自动生成的系统表组成的数据库，默认不会备份和恢复它。
验证 `test` 数据库的 `device` 表被成功恢复：
+
``` sql
> USE test;
Database changed to `test`
@@ -127,6 +147,7 @@ test> SHOW TABLES;
```
验证 `device` 表的所有数据被成功恢复：
+
``` sql
test> SELECT * FROM device;
+---------------------------+-----+-------+------+
diff --git a/zh_CN/admin/configuration-fields/audit-logs.md b/zh_CN/admin/configuration-fields/audit-logs.md
new file mode 100644
index 00000000..688718a4
--- /dev/null
+++ b/zh_CN/admin/configuration-fields/audit-logs.md
@@ -0,0 +1,92 @@
+# 审计日志
+
+Datalayers 提供数据库操作审计能力，可记录用户对数据库的查询、修改等操作。审计日志以文件形式存储，便于后续查询与分析。
+
+## 配置示例
+
+```toml
+# 审计日志配置
+[audit]
+# 是否启用审计日志功能
+# 默认值：false
+enable = true
+
+# 审计日志文件存储目录
+# 路径相对于 `base_dir` 配置项
+# 默认值："audit"
+path = "audit"
+
+# 审计日志文件最大保留数量
+# 系统每日生成新的日志文件
+# 默认值：30
+max_files = 30
+
+# 需要记录的审计日志类型，多个类型用逗号分隔
+# 支持的类型："read", "write", "ddl", "dql", "admin", "misc"
+# 特殊值："all" 表示记录所有类型
+# 默认值："ddl,admin"
+kinds = "ddl,admin"
+
+# 需要记录的审计操作类型，多个操作用逗号分隔
+# 支持的操作："select", "insert", "update", "delete", "create", "alter", "drop", "truncate", "trim",
+# "desc", "show", "create_user", "drop_user", "set_password", "grant", "revoke",
+# "flush", "cluster", "migrate", "compact", "export", "misc",
+# 特殊值："all" 表示记录所有操作
+# 默认值："all"
+actions = "all"
+
+# 要排除记录的审计操作类型，多个操作用逗号分隔
+# 支持的操作和 actions 相同
+# 默认值："select,insert"
+excludes = "select,insert"
+```
+
+## 配置说明
+
+- **enable**: 设置为 true 以启用审计日志功能
+- **path**: 指定日志存储路径，支持相对路径（基于 base_dir）或绝对路径
+- **max_files**: 控制日志文件轮转数量，避免磁盘空间过度占用
+- **kinds**: 精细化控制需要记录的日志类型，减少不必要的日志记录
+- **actions**: 根据实际安全需求，选择需要审计的具体数据库操作
+- **excludes**: 根据实际安全需求，选择排除不需要记录的操作类型
+- 同时满足 **kinds** 和 **actions** 且不在 **excludes** 条件的日志才会被记录
+
+## 操作约束
+
+| 操作 | kind | action |
+|-------------------|---------|---------|
+| INSERT | dml | insert |
+| UPDATE | dml | update |
+| DELETE | dml | delete |
+| SELECT | dql | select |
+| DESC TABLE | dql | desc |
+| SHOW | dql | show |
+| CREATE ROLE | admin | create_user |
+| CREATE USER | admin | create_user |
+| DROP ROLE | admin | drop_user |
+| DROP USER | admin | drop_user |
+| GRANT | admin | grant |
+| REVOKE | admin | revoke |
+| SET PASSWORD | admin | set_password |
+| CREATE DATABASE | ddl | create |
+| DROP DATABASE | ddl | drop |
+| TRIM DATABASE | ddl | trim |
+| CREATE TABLE | ddl | create |
+| DROP TABLE | ddl | drop |
+| ALTER TABLE | ddl | alter |
+| TRUNCATE TABLE | ddl | truncate |
+| CREATE INDEX | ddl | alter |
+| DROP INDEX | ddl | alter |
+| FLUSH | admin | flush |
+| COMPACT | admin | compact |
+| EXPORT | admin | export |
+| EXCLUDE NODE | admin | cluster |
+| INCLUDE NODE | admin | cluster |
+| DROP NODE | admin | cluster |
+| REBALANCE | admin | migrate |
+| STOP MIGRATION | admin | migrate |
+
+## 注意事项
+
+- 当前审计日志功能暂不支持记录 SELECT 和 INSERT 语句的相关操作。
+- 审计日志会在语句执行前进行记录，不包含语句执行状态信息。如需查看语句是否执行成功或出现异常，请在常规日志中进一步查询。
diff --git a/zh_CN/admin/configuration-fields/mcp.md b/zh_CN/admin/configuration-fields/mcp.md
new file mode 100644
index 00000000..63f1c233
--- /dev/null
+++ b/zh_CN/admin/configuration-fields/mcp.md
@@ -0,0 +1,15 @@
+# MCP
+
+## 配置
+
+```toml
+# The configurations of the MCP (Model Context Protocol) server.
+[mcp]
+# Whether to enable SSE.
+# Default: true.
+enable_sse = false
+
+# Whether to enable SSE OAuth.
+# Default: false.
+enable_sse_oauth = false
+```
diff --git a/zh_CN/admin/configuration-fields/server.md b/zh_CN/admin/configuration-fields/server.md
index 40ac27d4..7b136a09 100644
--- a/zh_CN/admin/configuration-fields/server.md
+++ b/zh_CN/admin/configuration-fields/server.md
@@ -25,11 +25,6 @@ addr = "0.0.0.0:8360"
# Default: "0.0.0.0:8361".
http = "0.0.0.0:8361"
-# The unix socket file of peer server.
-# Don't support peer server by default.
-# Default: ""
-# peer_addr = "run/datalayers.sock"
-
# 配置 session 超时时间.
# Default: "10s".
session_timeout = "10s"
@@ -77,13 +72,20 @@ jwt_secret = "87212c3d906df71e9c6289fbd456d917"
# 默认：0/0/0 表示不开启防暴力破解
#password_lockout = "3/5/5"
+# The configurations of the unix domain socket server.
+[server.uds]
+# Unix Domain Socket 的文件路径，指定相对路径则是相对 `base_dir`.
+# 不配置表示不开启此服务，默认为不开启。
+# 建议配置项: "run/datalayers.sock"
+# path = "run/datalayers.sock"
+
# The configurations of the Redis service.
[server.redis]
# 配置 Key-Value 服务的监听地址.
# Key-Value 服务仅在集群模式下才能工作.
# 默认情况下不启动 Key-Value 服务.
# Default: "".
-# addr = "0.0.0.0:8362"
+# addr = "0.0.0.0:6379"
# The username.
# Default: "admin".
diff --git a/zh_CN/admin/configuration-fields/ts-engine.md b/zh_CN/admin/configuration-fields/ts-engine.md
index 1577fb95..16ab3920 100644
--- a/zh_CN/admin/configuration-fields/ts-engine.md
+++ b/zh_CN/admin/configuration-fields/ts-engine.md
@@ -17,7 +17,7 @@
# 缓存 SST 文件的结构化元信息，用于条件过滤以加速查询。
# 缓存配置过小，在文件较多时，可能导致缓存频繁换入换出，影响性能，可通过监控面板观察缓存的使用情况。
-# 关于如何配置该缓存大小，可参考[高性能查询](https://docs.datalayers.cn/datalayers/latest/development-guide/high-performance-reading.html)
+# 关于如何配置该缓存大小，可参考[高性能查询](https://docs.datalayers.cn/zh/datalayers/latest/development-guide/query-performance-tuning-overview.html)
# Default: 2GB
meta_cache_size = "2GB"
diff --git a/zh_CN/admin/datalayers-cli.md b/zh_CN/admin/datalayers-cli.md
index fe559d2a..a2ee7f1f 100644
--- a/zh_CN/admin/datalayers-cli.md
+++ b/zh_CN/admin/datalayers-cli.md
@@ -2,68 +2,60 @@
Datalayers CLI 交互终端（dlsql）是与 Datalayers 数据库进行交互的命令行工具。该工具已包含在 Datalayers 的镜像和安装包中，提供 SQL 执行和系统管理功能。
-## SQL 交互终端
+Datalayers CLI 支持两种连接认证方式，用户可根据实际场景选择。
-**基本连接方式**
+## 基于帐号密码认证
+
+适用于远程或本地 TCP/IP 连接，提供灵活的身份验证。在终端中执行以下命令进入交互式界面：
-在终端中执行以下命令进入交互式界面：
```shell
-dlsql -h 127.0.0.1 -u admin -p public -d sensor_info -P 8360
+dlsql -h 127.0.0.1 -u admin -p public -P 8360
```
-**连接参数详解**
-
-| 参数 | 简写 | 描述 |
-| ---------- | ------- | ---------------------------------------------------------------------------------------------- |
-| --host | -h | 设置连接 Datalayers 服务器地址, 默认:127.0.0.1 |
-| --username | -u | 设置连接 Datalayers 使用的用户名 |
-| --password | -p | 设置连接 Datalayers 使用的密码 |
-| --port | -P | 设置连接 Datalayers 的端口 |
-| --database | -d | 设置连接 Datalayers 时使用的数据库 |
-| --execute | -e | 运行一次 SQL STATEMENT后退出 |
-| --load-file | | 执行指定的 SQL 脚本文件 |
-| --version | -V | 显示 CLI 工具的版本 |
-| --tls | | 通过 TLS 加密方式与数据库进行交互。自签证书则需指定 root ca，如：--tls /etc/datalayers/datalayers.crt |
-| --max-display-rows | | 在使用 `dlsql` 查询数据时最多显示多少条记录，缺省值为： `40`，如需显示更多记录，则需通过该参数进行指定（`0` 表示无限制） |
-| --help | | show this help, then exit |
-
+## 基于 Peer 认证
-## 管理工具
+Linux 的 Peer 认证（Peer Credentials Authentication）是基于内核级别的进程身份验证机制，通过 `Unix Domain Socket` 通信为连接方提供可靠的身份验证。
-Datalayers 通过 Peer 认证提供本地账户管理功能。该机制基于 Unix Domain Socket 进行进程间认证，仅限服务器本地访问。使用该功能时需确保服务端已经启用 peer 服务。
+Datalayers 集成 Peer 认证能力，为数据库账号管理提供安全便捷的解决方案，通过 Peer 认证的连接，将获得系统最高权限。使用 Peer 认证需依赖 `Unix Socket` 服务，因此需确保该服务已启用，如下：
-**启用 Peer 服务**
```toml
-[server]
-# The unix socket file of peer server.
-# Don't support peer server by default.
-# Default: ""
-peer_addr = "run/datalayers.sock"
+# The configurations of the unix domain socket server.
+[server.uds]
+# The path of the unix domain socket, relative to `base_dir`.
+# DONOT configure this options means do not support uds server by default.
+# Recommend: "run/datalayers.sock"
+path = "run/datalayers.sock"
```
-配置后需要重启 Datalayers 服务生效。
-**管理命令使用**
+通过以下命令即可进入交互终端：
-通过执行以下指令，查看相应功能说明：
```shell
-dlsql admin --help
+# 以 deb/rpm 安装场景为例
+sudo -u datalayers dlsql
```
-**子命令说明**
+**Peer 认证注意事项**：
-| 子命令 | 描述 |
-| ---------- | ------------------------------------------------------ |
-| init-root | 初始化管理员帐号，详细参数可通过 --help 查看 |
-| list-user | 列出系统的帐号信息，详细参数可通过 --help 查看 |
-| reset-password | 重置指定帐号的密码，详细参数可通过 --help 查看 |
+- **认证限制**
+ - 仅限本地访问：Peer 认证仅支持通过 Unix Socket 的本地连接
+- **连接端权限要求**：连接端账号必须满足以下条件之一：
+ - 具备超级管理员权限（root 用户）
+ - 用户的 UID 与数据库服务运行时的 UID 完全一致
+- **权限**：通过 Peer 认证建立的连接将获得系统级最高权限
+- 配置 `Unix Socket` 服务后，需重启 Datalayers，以确保服务生效
-**详细帮助查看**
+## 连接参数详解
-```shell
-# 查看 init-root 的参数说明
-dlsql admin init-root --help
-# 查看 list-user 的参数说明
-dlsql admin list-user --help
-# 查看 reset-password 的参数说明
-dlsql admin reset-password --help
-```
+| 参数 | 简写 | 描述 |
+| ---------- | ------- | ---------------------------------------------------------------------------------------------- |
+| --host | -h | 设置连接 Datalayers 服务器地址, 默认为本地路径通过 Unix Socket 方式连接: /var/lib/datalayers/run/datalayers.sock |
+| --username | -u | 设置连接 Datalayers 使用的用户名 |
+| --password | -p | 设置连接 Datalayers 使用的密码 |
+| --port | -P | 设置连接 Datalayers 的端口 |
+| --database | -d | 设置连接 Datalayers 时使用的数据库 |
+| --execute | -e | 运行一次 SQL STATEMENT后退出 |
+| --load-file | | 执行指定的 SQL 脚本文件 |
+| --version | -V | 显示 CLI 工具的版本 |
+| --tls | | 通过 TLS 加密方式与数据库进行交互。自签证书则需指定 root ca，如：--tls /etc/datalayers/datalayers.crt |
+| --max-display-rows | | 在使用 `dlsql` 查询数据时最多显示多少条记录，缺省值为： `40`，如需显示更多记录，则需通过该参数进行指定（`0` 表示无限制） |
+| --help | | show this help, then exit |
diff --git a/zh_CN/admin/datalayers-configuration.md b/zh_CN/admin/datalayers-configuration.md
index aede2129..b48460a4 100644
--- a/zh_CN/admin/datalayers-configuration.md
+++ b/zh_CN/admin/datalayers-configuration.md
@@ -38,11 +38,6 @@ addr = "0.0.0.0:8360"
# Default: "0.0.0.0:8361".
http = "0.0.0.0:8361"
-# The Redis Service endpoint of the server.
-# Users can start this service only when Datalayers server starts in cluster mode.
-# Default: "0.0.0.0:8362".
-# redis = "0.0.0.0:8362"
-
# A session is regarded timeout if it's not active in the past `session_timeout` duration.
# Default: "10s".
session_timeout = "10s"
@@ -60,6 +55,11 @@ timezone = "Asia/Shanghai"
# The configurations of authorization.
[server.auth]
+# The type of the authorization.
+# type = "static" or "rbac"
+# Default: "static"
+type = "static"
+
# The username.
# Default: "admin".
username = "admin"
@@ -72,6 +72,46 @@ password = "public"
# Default: "871b3c2d706d875e9c6389fb2457d957".
jwt_secret = "871b3c2d706d875e9c6389fb2457d957"
+# Password strength requirements.
+# weak: no requirements, simple password.
+# moderate: at least 8 characters, including at least three types of the following:
+# uppercase letters, lowercase letters, digits, and special characters.
+# strong: at least 14 characters, including all types of the following:
+# uppercase letters, lowercase letters, digits, and special characters.
+# Default: "weak"
+#password_strength = "weak"
+
+# Password protection against brute-force attacks.
+# Form as "a/b/c", means:
+# Account locked for "b" minutes after "a" failed password attempts,
+# and locked for another "c" miniutes after the each failed attempt.
+# The maximum of a/b/c is 10/120/120 respectively, and will be set to 3/5/5 if too big.
+# 0/-/- means no lockout.
+# Default: "0/0/0"
+#password_lockout = "3/5/5"
+
+# The configurations of the unix domain socket server.
+[server.uds]
+# The path of the unix domain socket, relative to `base_dir`.
+# DONOT configure this options means do not support uds server by default.
+# Recommend: "run/datalayers.sock"
+# path = "run/datalayers.sock"
+
+# The configurations of the Redis service.
+[server.redis]
+# Users can start this service only when Datalayers server starts in cluster mode.
+# Do not support redis service by default.
+# Default: "".
+# addr = "0.0.0.0:6379"
+
+# The username.
+# Default: "admin".
+#username = "admin"
+
+# The password.
+# Default: "public".
+#password = "public"
+
# The configurations of the Time-Series engine.
[ts_engine]
# The size of the request channel for each worker.
@@ -84,9 +124,13 @@ jwt_secret = "871b3c2d706d875e9c6389fb2457d957"
#max_memory_used_size = "10GB"
# Cache size for SST file metadata. Setting it to 0 to disable the cache.
-# Default: 512M
+# Default: 2GB
meta_cache_size = "2GB"
+# Cache size for last value. Setting it to 0 to disable the cache.
+# Default: 2GB
+last_cache_size = "2GB"
+
# Whether or not to preload parquet metadata on startup.
# This config only takes effect if the `ts_engine.meta_cache_size` is greater than 0.
# Default: true.
@@ -186,7 +230,7 @@ write_rate_limit = "2MB"
# In a path-style URI, the bucket is the first slash-delimited component of the Request-URI,
# the endpoint use the following format: https://s3.region-code.amazonaws.com/bucket-name.
# We support path-style URL access in minio even though your minio service does not enable this feature,
-# and you are also allowed accessing with path-style like http://: or http://minio.example.net
+# and you are also allowed accessing with path-style like http://: or http://minio.example.net
# if you set `virtual_hosted_style` to false
# [storage.object_store.s3]
# bucket = "datalayers"
@@ -216,8 +260,10 @@ write_rate_limit = "2MB"
# Default: "0MB"
memory = "256MB"
+# The file cache of storage is a hybrid cache. Enabling disk cache requires memory cache to be enabled as well.
+# However, you can enable memory cache without enabling disk cache.
[storage.object_store.file_cache]
-# Setting to 0 to disable file cache in memory.
+# Setting to 0 will disable both memory cache and disk cache.
# Default: "0MB"
# memory = "1024MB"
@@ -346,11 +392,46 @@ enable_err_file = false
# Default: true.
verbose = true
+# The configurations of audit logs.
+[audit]
+# Whether to enable audit logs.
+# Default: false.
+enable = false
+
+# The directory to store audit log files.
+# The path relative to `base_dir`
+# Default: "audit".
+path = "audit"
+
+# The maximum count of audit log files.
+# Generate a new file every day.
+# Default: 30.
+max_files = 30
+
+# Supported kinds of audit logs, separated by comma.
+# Kind list: "dml", "ddl", "dql", "admin", "misc"
+# "all" means all kinds could be logged.
+# Default: "ddl,admin"
+kinds = "ddl,admin"
+
+# Supported actions of audit logs, separated by comma.
+# Action list: "select", "insert", "update", "delete", "create", "alter", "drop", "truncate", "trim",
+# "desc", "show", "create_user", "drop_user", "set_password", "grant", "revoke",
+# "flush", "cluster", "migrate", "compact", "export", "misc",
+# "all" means all actions could be logged.
+# Default: "all"
+actions = "all"
+
+# Exclude actions of audit logs, separated by comma.
+# Optional value is the same as `actions`.
+# Default: "select,insert"
+excludes = ""
+
# The configurations of the MCP (Model Context Protocol) server.
[mcp]
# Whether to enable SSE.
# Default: true.
-enable_sse = true
+enable_sse = false
# Whether to enable SSE OAuth.
# Default: false.
@@ -378,7 +459,6 @@ enable_sse_oauth = false
[license]
# A trial license key which may be deprecated.
key = "eyJ2IjoxLCJ0IjoxLCJjbiI6Iua+nOWbvuacquadpe+8iOaIkOmDve+8ieaVsOaNruenkeaKgOaciemZkOWFrOWPuCIsImNlIjoieWluYm8ueWFuZ0BkYXRhbGF5ZXJzLmlvIiwic2QiOiIyMDI1MDUwOSIsInZkIjoyMzYsIm5sIjozLCJjbCI6MzAsImVsIjoxMDAwMDAsImZzIjpbXX0K.e1gDGsCpvPA1fy/j2JUDvuug/kxJQyuAan0fIn3gGmFL1JUQ3V1bsi73jVl6R3wBkxMbJ13tWdBcTYZREVCVjqy22HvcSkGYJqKiQ0qx2jP2Zq22z2oiO/3frs0xuMdF6g5IE9C6PQq5X/OeFi6eFSTze4mcJhc5DaeB176oSqkyyAf+aKS23ncybYE2Nb55tkKwEVkWao3guMVhIsySInE0PXlaRYuAwmMsA0laYt1C1ZX+ktBu4CI/+C9tH6BvmkvPEagayjoITzjqdx9YRjM7/c8cSa159thLqYzvfQlLXX48bua5DS16KETk19BBc/uaHZxYXzSE1wYXFArjKw=="
-
```
其中配置文件字段详细解释，请查看配置手册。
diff --git a/zh_CN/admin/system-metrics.md b/zh_CN/admin/system-metrics.md
index 4ba5e148..2a79c1a6 100644
--- a/zh_CN/admin/system-metrics.md
+++ b/zh_CN/admin/system-metrics.md
@@ -1,42 +1,52 @@
# 系统监控指标
-Datalayers 提供了丰富的指标来帮助用户了解当前服务状态，监测和定位系统的异常。
+Datalayers 提供丰富的监控指标，帮助用户全面掌握服务运行状态，快速识别和定位系统异常。
## 与监控系统集成
-Datalayers 指标支持与 Prometheus 集成。使用第三方监控系统对 Datalayers 进行监控有如下好处：
+Datalayers 原生支持与 Prometheus 集成，实现高效的监控数据采集。将 Datalayers 接入第三方监控系统可带来以下优势：
-* Datalayers 的监控数据与其他系统的监控数据进行整合，形成一个完整的监控系统，如监控服务器主机的相关信息。
-* 使用更加丰富的监控图表，更直观地展示监控数据，如使用 Grafana 的仪表盘，参考[Grafana监控](./system-monitor-grafana.md)。
-* 使用更加丰富的告警方式，更及时地发现问题，如使用 Prometheus 的 Alertmanager。
+* **统一监控视图**：将 Datalayers 的监控数据与其他系统指标（如服务器主机信息）整合，构建完整的监控体系
+* **可视化展示**：通过 Grafana 等工具创建丰富的监控仪表盘，直观呈现系统运行状态（详见 [Grafana监控](./system-monitor-grafana.md)）
+* **智能告警**：利用 Prometheus Alertmanager 实现多通道告警通知，及时发现问题并快速响应
## Datalayers Metrics
| Key | Type | 说明 |
| ----------------------------------------------------- | --------- | --------------------------------------------------------- |
-| datalayers_system_memory_total | gauge | Datalayers 节点总内存 |
-| datalayers_system_memory_usage | gauge | Datalayers 节点内存使用量 |
-| datalayers_memory_usage | gauge | Datalayers 进程内存占用 |
-| datalayers_cpu_total | gauge | Datalayers 节点CPU core 数量 |
-| datalayers_cpu_usage | gauge | Datalayers 节点CPU 使用率 |
+| **datalayers_system_memory_usage** | gauge | * Datalayers 节点系统内存使用量，建议峰值负载不高于 60% |
+| **datalayers_memory_usage** | gauge | * Datalayers 进程内存占用，建议峰值时不高于系统总内存的 60% |
+| **datalayers_cpu_usage** | gauge | * Datalayers 进程 CPU 使用率，建议峰值时不高于 60% |
+| **datalayers_system_cpu_usage** | gauge | * Datalayers 节点系统整体 CPU 使用率，建议峰值时不高于 60% |
+| datalayers_system_memory_total | gauge | Datalayers 节点系统总内存 |
+| datalayers_cpu_total | gauge | Datalayers 节点 CPU core 数量 |
| datalayers_ingest_rows_total | counter | Datalayers 写入的行数 |
| datalayers_select_total | counter | Datalayers select 请求次数 |
| parquet_meta_op_total | counter | parquet meta 缓存相关指标 |
| datalayers_parquet_meta_cache_usage | gauge | Parquet meta 和 statistics 的缓存使用量 |
-| datalayers_parquet_meta_cache_config_size | gauge | 缓存 Parquet meta 和 statistics 的最大内存使用量 |
+| datalayers_parquet_meta_cache_config_size | gauge | 缓存 Parquet meta 和 statistics 的最大内存使用量 |
| datalayers_flush_queue_limit | gauge | Flush 任务队列长度限制 |
| datalayers_flush_concurrence_limit | gauge | Flush 并行任务限制 |
-| datalayers_flush_pending_length | gauge | Flush pending 中的数量 |
-| datalayers_flush_running_length | gauge | Flush running 中的数量 |
+| **datalayers_flush_pending_length** | gauge | * Flush 队列中等待的数量，该值不应该等于 datalayers_flush_queue_limit 的数量 |
+| datalayers_flush_running_length | gauge | 正在 Flush 任务的数量 |
| datalayers_compact_queue_limit | gauge | Compact 任务队列长度限制 |
| datalayers_compact_concurrence_limit | gauge | Compact 并行任务限制 |
| datalayers_compact_pending_length | gauge | Compact pending 中的数量 |
| datalayers_compact_running_length | gauge | Compact running 中的数量 |
-| datalayers_global_rejected_write | counter | Datalayers 节点 memtable 的数据量达到阈值后拒绝写入的次数 |
-| datalayers_rejected_write | counter | Table 分区 memtable 的数据量达到阈值后拒绝写入的次数 |
+| datalayers_global_rejected_write | counter | Datalayers 节点 memtable 的数据量达到阈值后拒绝写入的次数 |
+| datalayers_rejected_write | counter | Table 分区 memtable 的数据量达到阈值后拒绝写入的次数 |
| latency_flush_per_10m_milliseconds | histogram | Flush 平均生成 10M 数据的延迟 |
| latency_compact_per_10m_milliseconds | histogram | Compact 平均生成 10M 数据的延迟 |
| datalayers_panic_total | counter | Datalayers panic 的次数 |
-| datalayers_hybrid_cached_file_memory_config_size | gauge | 缓存对象存储文件内容的最大内存使用量 |
-| datalayers_hybrid_cached_file_disk_config_size | gauge | 缓存对象存储文件内容的最大磁盘使用量 |
-| datalayers_hybrid_cached_file_meta_memory_config_size | gauge | 缓存对象存储文件 meta 信息的最大内存使用量 |
+| datalayers_hybrid_cached_file_memory_config_size | gauge | 缓存对象存储文件内容的最大内存使用量 |
+| datalayers_hybrid_cached_file_disk_config_size | gauge | 缓存对象存储文件内容的最大磁盘使用量 |
+| datalayers_hybrid_cached_file_meta_memory_config_size | gauge | 缓存对象存储文件 meta 信息的最大内存使用量 |
+
+## FDB Metrics
+
+| Key | Type | 说明 |
+| ----------------------------------------------------- | --------- | --------------------------------------------------------- |
+| **fdb_database_available** | gauge | * 元数据服务状态状态，`0` 不健康，`1` 状态 |
+| **fdb_process_disk_free_bytes** | gauge | * 元数据存储磁盘已使用空间大小，单位：bytes, 使用空间超过 `95%` 会导致服务不可用 |
+| **fdb_exporter_latency_seconds** | gauge | * 访问元数据服务的时延，单位：秒。不应该大于 `1` |
+| fdb_process_disk_total_bytes | gauge | 元数据存储磁盘的总空间大小，单位：bytes |
diff --git a/zh_CN/admin/system-monitor-grafana.md b/zh_CN/admin/system-monitor-grafana.md
index 4242362b..8b71dd9e 100644
--- a/zh_CN/admin/system-monitor-grafana.md
+++ b/zh_CN/admin/system-monitor-grafana.md
@@ -1,14 +1,20 @@
# 系统监控
-Datalayers 实例启动以后，可经`8361`端口，通过 http 协议访问 `/metrics` 获得当前系统指标数据。
+## 概述
-可通过 Prometheus 获取并存储系统监控指标，采用 Grafana 可视化展示监控的指标数据，可监控 Datalayers 的指标。
+Datalayers 指标支持与 Prometheus 集成。Datalayers 启动后，您可以通过 HTTP 协议访问 `http://<服务地址>:8361/metrics` 获取系统实时指标数据。这些指标可通过 Prometheus 进行采集存储，并通过 Grafana 进行可视化展示。
-## 配置 Prometheus
+本章节介绍如何通过 Prometheus + Grafana 实现 Datalayers 指标的可视化。
-如果你还未安装，请前往 Prometheus 官网下载并安装。
+## 通过 Prometheus 收集数据
-安装完成后，请手动配置你的 `prometheus.yml`，增加以下配置内容：
+### 安装 Prometheus
+
+如果你还未安装，请前往 [Prometheus 官网](https://prometheus.io/download/) 下载并安装。
+
+### 配置 Prometheus
+
+安装完成后，手动配置 `prometheus.yml`，增加以下配置内容：
``` yml
global:
@@ -30,11 +36,11 @@ scrape_configs:
- targets: ["127.0.0.1:8361"]
```
-请确保 Datalayers HTTP Server 的 IP 地址、端口号正确。
+**注意**：请确保配置中的 IP 地址和端口号与您的 Datalayers HTTP 服务器地址一致。
-你也可以通过 Docker 快速启动 Prometheus，具体步骤如下：
+### 启动 Prometheus
-1. 首先准备配置文件`prometheus.yml`，内容同上述文件相同。
+1. 首先准备配置文件`prometheus.yml`，内容同上述文件相同
2. 通过以下命令启动 prometheus 的 docker 容器:
@@ -47,35 +53,37 @@ docker run --name my-prometheus -d \
Prometheus 启动完成后，将会定时从 Datalayers 服务定时拉取指标数据并存储。
-如果你希望持久化存储这些数据，请使用 `-v` 参数挂载固定目录到 Prometheus 容器。
+如果希望持久化存储这些数据，则使用 `-v` 参数挂载固定目录到 Prometheus 容器。
例如：
-```
+```text
-v /home/my/prometheus-data:/prometheus
```
-## Grafana 配置
+## 配置 Grafana
+
+### 安装 Grafana
-如果你还未安装 Grafana，请至 Grafana 官网下载页下载并安装。
+如果你还未安装 Grafana，请至 [Grafana 官网下载页](https://grafana.com/grafana/download?pg=get&plcmt=selfmanaged-box1-cta1) 下载并安装。
-你也可以通过 Docker 快速启动 Grafana 实例：
+### 启动 Grafana
``` bash
docker run --name my-grafana --network host grafana/grafana
```
-### 登陆到 Grafana
+### 登陆 Grafana
-启动成功后，请通过浏览器登录到 Grafana，默认用户名/密码为：`admin/admin`
+启动后通过浏览器访问 Grafana，默认用户名/密码为：admin/admin。
### 添加 Prometheus 数据源
-找到 Grafana 菜单 `Configuration - Data sources` ，或访问 `/datasources/new` 页面，选择 Prometheus 分类，进入页面后，填入 Prometheus Server 地址，根据需求填写其他配置，保存并通过测试后生效。
+找到 Grafana 菜单 `Configuration - Data sources` ，选择 Prometheus 分类，进入页面后，填入 Prometheus Server 地址，根据需求填写其他配置，保存并通过测试后生效。
-### 添加指标面板
+### 添加监控面板
-添加 Prometheus 数据源后，可在 `Grafana - Dashboards` 手动添加指标面板，或通过 `Grafana - Dashboards - Import` 功能快速导入我们提供的模版。
+添加 Prometheus 数据源后，可在 `Grafana - Dashboards` 手动添加指标面板，或通过 `Grafana - Dashboards - Import` 功能快速导入我们提供的 [Dashboard 模版](https://github.com/datalayers-io/datalayers-with-grafana/blob/main/grafana/datalayers-dashboard.json)。
以下为监控面板示意图：
diff --git a/zh_CN/development-guide/auth-with-restapi.md b/zh_CN/development-guide/auth-with-restapi.md
deleted file mode 100644
index 10b6f351..00000000
--- a/zh_CN/development-guide/auth-with-restapi.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# 认证与安全
-
-## 概述
-Datalayers 支持基于 HTTP/HTTPS 协议的身份认证机制，确保数据库连接的安全性。系统提供内置的身份验证方式，允许管理员配置固定的用户名和密码进行访问控制。
-
-## 认证配置
-在 Datalayers 配置文件（默认路径：/etc/datalayers/datalayers.toml）中设置认证参数：
-```toml
-# ...
-[server]
-# ...
-[server.auth]
-username = "admin"
-password = "public"
-# ...
-```
-详细配置请参考 [Datalayers 配置手册](../admin/datalayers-configuration.md) 章节。
-
-**注：** *以下示例均使用 [时序表引擎](../sql-reference/table-engine/timeseries.md) 进行演示，如使用其他类型的表引擎，请参考[表引擎](../sql-reference/table-engine.md)。
-Datalayers REST API 支持以下两种认证方式，可根据使用场景自由选择。配置参见 [Datalayers 配置](../admin/datalayers-configuration.md)章节。*
-
-
-## HTTP BASIC 认证
-Datalayers REST API 默认使用 [`HTTP BASIC 认证`](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Authentication#basic) 认证方式，认证凭据通过 HTTP 头部传递。
-
-**基本用法**
-```shell
-curl -u":" -X POST \
-http://:/api/v1/sql?db= \
--H 'Content-Type: application/binary' \
--d ''
-```
-
-**示例**
-
-```shell
-curl -u"admin:public" -i -XPOST "http://127.0.0.1:8361/api/v1/sql" \
- -d 'show databases'
-```
diff --git a/zh_CN/development-guide/connection.md b/zh_CN/development-guide/connection.md
index 0d347a39..dd4eeeff 100644
--- a/zh_CN/development-guide/connection.md
+++ b/zh_CN/development-guide/connection.md
@@ -1,38 +1,78 @@
# 数据库连接指南
## 概述
+
Datalayers 提供多种协议支持，满足不同场景下的数据库连接和交互需求。用户可根据性能要求、开发生态和集成复杂度等因素选择合适的连接协议。
+## 用户与权限
+
+Datalayers 支持多种认证机制与细粒度的权限控制。默认为静态认证，初始帐号密码为：`admin/public`。
+更多介绍参考 [连接认证与权限](../user-security/authentication/overview.md)
+
+## 端口说明
+
+下表列出 Datalayers 支持的协议及其对应的默认端口号，您可以在配置文件中按需修改这些端口：
+
+| 协议类型 | 默认端口 | 用途简述 | 是否默认开启 |
+| ------------- | ----------- | ----------------------------------------------------- | -------- |
+| **Arrow Flight SQL 高速传输协议** | 8360 | 高性能、低延迟的 SQL 查询传输协议（基于 Arrow 格式） | ✅ 是 |
+| **PostgreSQL 连接协议** | 5342 | 标准 PostgreSQL 连接协议（如 JDBC/ODBC 使用） | ✖ 否 |
+| **Prometheus 协议** | 9090 | 兼容 PromQL 与 Remote-Write协议，可用于 Prometheus 补充或替换 | ✖ 否 |
+| **REST API** | 8361 | 基于 HTTP 的通用接口，用于查询、管理、元数据获取等 | ✅ 是 |
+| **InfluxDB 行协议** | 8361 | 用于写入 InfluxDB 格式的时序数据 | ✅ 是 |
+| **Redis 协议** | 6379 | 兼容 Redis 协议的访问（如使用 redis-cli 连接） | ✖ 否 |
+
## 支持的协议
### Arrow Flight SQL（推荐用于高性能场景）
+
- **协议特点**：基于 Apache Arrow 内存格式和 Flight RPC 框架的高性能 SQL 交互协议
- **性能优势**：在数据传输场景下，相比 JDBC/ODBC 等驱动数据传输方案，性能提升可达百倍
- **适用场景**：对性能有高要求的数据写入与查询场景
### PostgreSQL 协议（即将推出）
+
- **兼容性**：完整兼容 PostgreSQL 网络连接协议
- **工具生态**：支持 PostgreSQL 生态的命令行工具、JDBC/ODBC 驱动及各类可视化工具
- **当前状态**：该协议正在开发中，计划近期正式发布
+### Prometheus 协议
+
+- **兼容性**：兼容 `PromQL` 查询语言以及 `Remote-Write` 协议
+- **工具生态**： 可使用 Prometheus 生态相关工具、组件快速集成
+
### REST API
+
- **交互方式**：通过标准的 RESTful API 接口执行 SQL 操作
- **适用场景**：适合需要 HTTP 协议集成的应用场景
### InfluxDB 行协议
+
- **功能特性**：专为时序数据写入优化的行协议
- **使用限制**：该协议仅支持数据写入操作
- **适用场景**：InfluxDB 兼容的时序数据摄入
+### Redis 协议
+
+- **兼容性**：完全兼容 Redis 协议
+- **适用场景**：分布式、海量键值存储需求
## 协议选择建议
+| 特性 | 适用场景 | 功能支持 | 备注 |
+| ------------- | ----------------------- | --------------------| ------------------- |
+| **Arrow Flight SQL 高速传输协议** | 高性能写入、查询与大数据量传输 | 完整读写 | 完整功能 |
+| **PostgreSQL 连接协议** | PostgreSQL 生态集成 | 完整读写 | 完整功能 |
+| **Prometheus 协议** | Prometheus 生态集成 | 完整读写 | Prometheus 为单值模型，使用上存在细微差异 |
+| **REST API** | HTTP 集成、简单查询 | 完整读写 | 完整读写 |
+| **InfluxDB 行协议** | 替换 InfluxDB 场景 | 仅支持写入 | 仅支持写入 |
+| **Redis 协议** | 键值存储场景 | 完整读写 | 仅支持 key-value 操作 |
-| 特性 | 适用场景 | 功能支持 |
-| ------------- | ----------------------- | --------------------|
-| **Arrow Flight SQL 高速传输协议** | 高性能写入、查询与大数据量传输 | 完整读写 |
-| **PostgreSQL 连接协议** | PostgreSQL 生态集成 | 完整读写 |
-| **REST API** | HTTP 集成、简单查询 | 完整读写 |
-| **InfluxDB 行协议** | 替换 InfluxDB 场景 | 仅支持写入 |
+## 推荐选择
-**推荐选择**：对于性能敏感的生产环境，建议优先考虑 Arrow Flight SQL 协议；如需使用现有 PostgreSQL 工具链，可等待 PostgreSQL 协议正式发布。
+- 对于性能敏感的生产环境，建议使用 Arrow Flight SQL 协议
+- 如需使用现有 PostgreSQL 工具链，可等待 PostgreSQL 协议正式发布
+- 如需使用现有 Prometheus 工具链，可使用 Prometheus 协议
+- 如需使用现有 InfluxDB 工具链写入，可使用 InfluxDB 行协议
+- 键值存储需求场景，可使用 Redis 协议接入
+- 如上述相关协议均不能满足的情况，可使用 REST API 协议
diff --git a/zh_CN/development-guide/errno-with-restapi.md b/zh_CN/development-guide/errno-with-restapi.md
deleted file mode 100644
index 9258f560..00000000
--- a/zh_CN/development-guide/errno-with-restapi.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# 错误码与故障排除指南
-
-## 概述
-Datalayers 遵循标准的 HTTP 状态码规范，提供清晰的错误信息帮助用户快速定位和解决问题。本文详细说明各类错误码的含义和相应的处理建议。
-
-## HTTP 响应状态码
-
-Datalayers 遵循 [HTTP响应状态码](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) 标准，可能的状态码如下：
-
-| HTTP CODE | 描述 |
-| ---- | ---- |
-| 200 | 请求成功，返回的 JSON 数据将提供更多信息 |
-| 201 | 创建成功，新建的对象将在 Body 中返回 |
-| 204 | 请求成功，常用于删除与更新操作，Body 不会返回内容 |
-| 400 | 请求无效，例如请求体或参数错误 |
-| 401 | 未通过服务端认证，API 密钥过期或不存在时可能会发生 |
-| 403 | 无权操作，检查操作对象是否正在使用或有依赖约束 |
-| 404 | 找不到请求路径或请求的对象不存在，可参照 Body 中的 message 字段判断具体原因 |
-| 405 | Method Not Allowed |
-| 409 | 请求的资源已存在或数量超过限制 |
-| 500 | 服务端处理请求时发生内部错误，可通过 Body 返回内容与日志判断具体原因 |
-
-## 返回报文
-
-当你发送一条错误的SQL语句后，Datalayers 会返回一个 JSON 格式的错误信息，如下所示：
-
-```json
-{
- "error": "Only support execute one statement"
-}
-```
diff --git a/zh_CN/development-guide/high-performance-ingestion.md b/zh_CN/development-guide/high-performance-ingestion.md
new file mode 100644
index 00000000..e8bc02d2
--- /dev/null
+++ b/zh_CN/development-guide/high-performance-ingestion.md
@@ -0,0 +1,119 @@
+# 高性能写入
+
+本章节详细介绍在时序数据场景下实现数据高效写入 Datalayers 的最佳实践，涵盖影响写入性能的关键因素及优化策略。
+
+## 批量写入
+
+原则：单次请求数据量越大，写入效率越高。建议每批次数据量控制在8000条以内以获得最佳性能。
+
+**通过 SQL 批量写入**：
+
+```SQL
+-- CREATE TABLE sx1 (
+-- ts TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+-- sid INT32,
+-- temp REAL,
+-- timestamp KEY (ts))
+-- PARTITION BY HASH(sid) PARTITIONS 8
+-- ENGINE=TimeSeries;
+
+insert into sx1 (sid, value) values (1, 26.3),(2,23.4),(3, 26.6)......
+```
+
+**通过行协议批量写入**：
+
+```shell
+curl -i -XPOST "http://127.0.0.1:8361/write?db=db_name&u=admin&p=public&precision=ns" -d 'weather,location=us-midwest temperature=82 1699429527\nweather,location=us-midwest temperature=82 1699429528
+```
+
+:::tip
+无论是使用 SQL 写入还 行协议 写入，在每一次请求中携带更多的数据，将获得更好的写入性能。
+:::
+
+## 并发写入
+
+在服务器资源充足的情况下，适当增加并发连接数可显著提升整体写入吞吐量。建议根据实际硬件资源配置合理的并发度。
+
+## 传输协议
+
+- **gRPC协议**：性能更优，推荐在高吞吐量生产环境使用
+- **HTTP协议**：适用于开发、测试或者受限环境
+
+## Prepared Statement
+
+预处理语句是数据库系统中用于预编译 SQL 语句的一种机制，它在提升查询性能和安全性方面发挥着重要作用。
+
+当使用预处理语句时，Datalayers 会预先编译 SQL 语句并将其存储在一个准备好的状态中。在后续执行该语句时，Datalayers 可以直接使用已编译的版本，从而避免重复编译。这种机制不仅绕过了 SQL 解析器，加速了单条 SQL 的执行，更重要的是，它显著降低了 CPU 负载，释放了系统资源。
+
+同时，数据库系统可以在执行 SQL 语句之前进行语法检查、语义分析和优化，进一步提高查询的执行效率。
+
+在 Datalayers 中，Prepared Statement 目前支持Insert 与 Query，核心是通过`?`作为占位符，随后对占位符进行参数绑定，以达到绕过 SQL 解析的效果。
+
+在 Insert 中，首先通过带有占位符的语句开启 Prepared Statement，随后通过 RecordBatch 的形式来绑定参数，完成执行，需要注意：
+
+- 为保证高效执行，Insert 中在 values 部分只支持单行的形式，而最终生成的 Insert batch 大小取决于 参数绑定时 RecordBatch 中的行数
+- 进行参数绑定时，每一行的列数必须严格相等，同时需和占位符数量相等且类型匹配
+
+具体语法如下：
+
+```SQL
+-- CREATE TABLE sx1 (
+-- ts TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+-- sid INT32 ,
+-- value INT32 DEFAULT 10,
+-- timestamp KEY (ts))
+-- PARTITION BY HASH(sid) PARTITIONS 8
+-- ENGINE=TimeSeries;
+
+insert into sx1 (sid) values (?)
+
+```
+
+```Rust
+// Use RecordBatch to bind parameters:
+
+let schema = Arc::new(Schema::new(vec![Field::new("sid", DataType::Int32, false)]));
+// int32 array
+let array = Int32Array::from(vec![1]);
+let columns = vec![Arc::new(array) as Arc];
+let batch = RecordBatch::try_new(schema, columns).unwrap();
+
+```
+
+## Table Options
+
+在时序数据模型场景，合理设置 table options 有利于提升写的性能。
+
+### Partition 数量
+
+- 一般来说 1 个 partition 每秒可高达数十万点位的写入，因此根据实际场景需求来设置即可
+- Partition 越多，会消耗越多的 CPU 与内存，建议 partition 数量不超过集群内所有节点的 CPU CORE 之和
+
+示例：
+
+```SQL
+CREATE TABLE sx1 (
+ts TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+sid INT32 ,
+value INT32 DEFAULT 10,
+timestamp KEY (ts))
+PARTITION BY HASH(sid) PARTITIONS 8
+ENGINE=TimeSeries;
+```
+
+### Memtable size
+
+在时序模型中，数据首先被写入到内存中（即：memtable），当内存中数据达到设置的阈值的一半时（即：memtable_size），将会触发落盘的行为，将内存中的数据转存到持久中。后台线程再根据策略，对落盘的文件进行合并、整理，如果 memtable size 设置较小，会导致频繁落盘、compact，从而影响读写性能。
+
+示例：
+
+```SQL
+CREATE TABLE sx1 (
+ts TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+sid INT32 ,
+value INT32 DEFAULT 10,
+timestamp KEY (ts))
+PARTITION BY HASH(sid) PARTITIONS 8
+ENGINE=TimeSeries
+WITH(memtable_size=512MB)
+```
diff --git a/zh_CN/development-guide/high-performance-writing.md b/zh_CN/development-guide/high-performance-writing.md
index d1a681a8..e8bc02d2 100644
--- a/zh_CN/development-guide/high-performance-writing.md
+++ b/zh_CN/development-guide/high-performance-writing.md
@@ -1,10 +1,13 @@
# 高性能写入
-本章节介绍在时序数据模型场景下如何将数据高效的写入到 Datalayers 中。在数据写入过程中，以下相关因素将影响数据写入的性能：
+本章节详细介绍在时序数据场景下实现数据高效写入 Datalayers 的最佳实践，涵盖影响写入性能的关键因素及优化策略。
## 批量写入
-在数据写入时，每次请求携带的数据量越大写入效率越高（注：每次请求batch数量建议控制在8000以下，以获取最佳性能）。
-### SQL 示例
+
+原则：单次请求数据量越大，写入效率越高。建议每批次数据量控制在8000条以内以获得最佳性能。
+
+**通过 SQL 批量写入**：
+
```SQL
-- CREATE TABLE sx1 (
-- ts TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
@@ -17,7 +20,8 @@
insert into sx1 (sid, value) values (1, 26.3),(2,23.4),(3, 26.6)......
```
-### 行协议写入示例
+**通过行协议批量写入**：
+
```shell
curl -i -XPOST "http://127.0.0.1:8361/write?db=db_name&u=admin&p=public&precision=ns" -d 'weather,location=us-midwest temperature=82 1699429527\nweather,location=us-midwest temperature=82 1699429528
```
@@ -27,12 +31,16 @@ curl -i -XPOST "http://127.0.0.1:8361/write?db=db_name&u=admin&p=public&precisio
:::
## 并发写入
-在服务器资源足够的情况下，更高的并发（连接）会带来更好的写入性能。
+
+在服务器资源充足的情况下，适当增加并发连接数可显著提升整体写入吞吐量。建议根据实际硬件资源配置合理的并发度。
## 传输协议
-Datalayers 支持`HTTP`、`gRPC` 两种协议来进行交互，gRPC 的性能优于 HTTP。
+
+- **gRPC协议**：性能更优，推荐在高吞吐量生产环境使用
+- **HTTP协议**：适用于开发、测试或者受限环境
## Prepared Statement
+
预处理语句是数据库系统中用于预编译 SQL 语句的一种机制，它在提升查询性能和安全性方面发挥着重要作用。
当使用预处理语句时，Datalayers 会预先编译 SQL 语句并将其存储在一个准备好的状态中。在后续执行该语句时，Datalayers 可以直接使用已编译的版本，从而避免重复编译。这种机制不仅绕过了 SQL 解析器，加速了单条 SQL 的执行，更重要的是，它显著降低了 CPU 负载，释放了系统资源。
@@ -42,6 +50,7 @@ Datalayers 支持`HTTP`、`gRPC` 两种协议来进行交互，gRPC 的性能优
在 Datalayers 中，Prepared Statement 目前支持Insert 与 Query，核心是通过`?`作为占位符，随后对占位符进行参数绑定，以达到绕过 SQL 解析的效果。
在 Insert 中，首先通过带有占位符的语句开启 Prepared Statement，随后通过 RecordBatch 的形式来绑定参数，完成执行，需要注意：
+
- 为保证高效执行，Insert 中在 values 部分只支持单行的形式，而最终生成的 Insert batch 大小取决于 参数绑定时 RecordBatch 中的行数
- 进行参数绑定时，每一行的列数必须严格相等，同时需和占位符数量相等且类型匹配
@@ -59,6 +68,7 @@ Datalayers 支持`HTTP`、`gRPC` 两种协议来进行交互，gRPC 的性能优
insert into sx1 (sid) values (?)
```
+
```Rust
// Use RecordBatch to bind parameters:
@@ -71,13 +81,16 @@ let batch = RecordBatch::try_new(schema, columns).unwrap();
```
## Table Options
+
在时序数据模型场景，合理设置 table options 有利于提升写的性能。
### Partition 数量
+
- 一般来说 1 个 partition 每秒可高达数十万点位的写入，因此根据实际场景需求来设置即可
- Partition 越多，会消耗越多的 CPU 与内存，建议 partition 数量不超过集群内所有节点的 CPU CORE 之和
-示例：
+示例：
+
```SQL
CREATE TABLE sx1 (
ts TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
@@ -87,10 +100,13 @@ timestamp KEY (ts))
PARTITION BY HASH(sid) PARTITIONS 8
ENGINE=TimeSeries;
```
+
### Memtable size
+
在时序模型中，数据首先被写入到内存中（即：memtable），当内存中数据达到设置的阈值的一半时（即：memtable_size），将会触发落盘的行为，将内存中的数据转存到持久中。后台线程再根据策略，对落盘的文件进行合并、整理，如果 memtable size 设置较小，会导致频繁落盘、compact，从而影响读写性能。
-示例：
+示例：
+
```SQL
CREATE TABLE sx1 (
ts TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
diff --git a/zh_CN/development-guide/insert-with-restapi.md b/zh_CN/development-guide/insert-with-restapi.md
deleted file mode 100644
index 451d8424..00000000
--- a/zh_CN/development-guide/insert-with-restapi.md
+++ /dev/null
@@ -1,140 +0,0 @@
-# 数据写入指南
-
-## 概述
-Datalayers 支持通过 HTTP/HTTPS 协议执行数据写入操作，SQL 语句通过 HTTP 请求体进行传输。本文详细介绍如何使用 REST API 进行数据库操作，包括库表创建和数据插入。SQL 相关语法请参考：[SQL Reference](../sql-reference/data-type.md)
-
-## 基础语法
-
-**通用请求格式**
-```shell
-curl -u":" -X POST \
-http://127.0.0.1:8361/api/v1/sql?db= \
--H 'Content-Type: application/binary' \
--d ''
-```
-
-## 示例
-
-### 创建数据库
-
-```shell
-curl -u"admin:public" -X POST \
-http://127.0.0.1:8361/api/v1/sql \
--H 'Content-Type: application/binary' \
--d 'create database demo'
-```
-
-### 创建表
-
-```shell
-curl -u"admin:public" -X POST \
-http://127.0.0.1:8361/api/v1/sql?db=demo \
--H 'Content-Type: application/binary' \
--d 'CREATE TABLE sensor_info (
- ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
- sn INT32 NOT NULL,
- speed int,
- longitude float,
- latitude float,
- timestamp KEY (ts)) PARTITION BY HASH(sn) PARTITIONS 2 ENGINE=TimeSeries;'
-```
-
-返回值
-
-```json
-{"affected_rows":0}
-```
-
-### 插入数据
-
-插入命令：
-
-```shell
-curl -u"admin:public" -X POST \
-http://127.0.0.1:8361/api/v1/sql?db=demo \
--H 'Content-Type: application/binary' \
--d 'INSERT INTO sensor_info(sn, speed, longitude, latitude) VALUES(1, 120, 104.07, 30.59),(2, 120, 104.07, 30.59)'
-```
-
-返回值：
-
-```json
-{"affected_rows":2}
-```
-
-## 编程语言示例
-
-::: code-group
-
-```go
-package main
-
-import (
- "bytes"
- "encoding/base64"
- "fmt"
- "io"
- "net/http"
-)
-
-func main() {
-
- username := "admin"
- password := "public"
-
- auth := username + ":" + password
- authHeader := "Basic " + base64.StdEncoding.EncodeToString([]byte(auth))
-
- sql := "select * from sensor_info limit 10"
-
- url := "http://127.0.0.1:8361/api/v1/sql?db=demo"
- req, err := http.NewRequest("POST", url, bytes.NewBuffer([]byte(sql)))
- if err != nil {
- fmt.Println("Error creating request:", err)
- return
- }
-
- req.Header.Set("Content-Type", "application/binary")
- req.Header.Set("Authorization", authHeader)
-
- client := &http.Client{}
- resp, err := client.Do(req)
- if err != nil {
- fmt.Println("Error sending request:", err)
- return
- }
- defer resp.Body.Close()
-
- body, err := io.ReadAll(resp.Body)
- if err != nil {
- fmt.Println("Error reading response:", err)
- return
- }
-
- fmt.Println("Response Status:", resp.Status)
- fmt.Println("Response Body:", string(body))
-}
-
-```
-
-```java [JAVA]
-import type { UserConfig } from 'vitepress'
-
-const config: UserConfig = {
- // ...
-}
-
-export default config
-```
-
-```rust [Rust]
-import type { UserConfig } from 'vitepress'
-
-const config: UserConfig = {
- // ...
-}
-
-export default config
-```
-
-:::
diff --git a/zh_CN/development-guide/multi-language-examples.md b/zh_CN/development-guide/multi-language-examples.md
deleted file mode 100644
index ffe60ecc..00000000
--- a/zh_CN/development-guide/multi-language-examples.md
+++ /dev/null
@@ -1,307 +0,0 @@
-# 多语言接入示例
-
-## 概述
-Datalayers 提供基于 HTTP/HTTPS 的 REST API 接口，支持多种编程语言进行数据交互。本文提供 Python、Go 和 Shell 的完整接入示例，帮助您快速集成 Datalayers 到现有应用中。
-
-* Python
-* Go
-* Shell
-
-::: code-group
-
-```Python [Python]
-import http
-import json
-from http.client import HTTPConnection
-
-
-def print_response(conn: HTTPConnection):
- with conn.getresponse() as response:
- response_body = response.read().decode('utf-8')
- print(f"Status: {response.status} {response.reason}")
- print("Headers:")
- for header, value in response.getheaders():
- print(f" {header}: {value}")
- print("Body:")
- try:
- # Try to parse and pretty print JSON response
- response_json = json.loads(response_body)
- print(json.dumps(response_json, indent=2))
- except json.JSONDecodeError:
- # If not JSON, print raw response
- print(response_body)
-
-
-def print_query_result(conn: HTTPConnection):
- with conn.getresponse() as response:
- # Parses the response into a json object since the Datalayers server always encodes response into json.
- data = response.read().decode('utf-8')
- obj = json.loads(data)
- # Retrieves the `columns` and `values` objects.
- # The `columns` object are the column names of the query result.
- # The `values` object are the rows of the query result.
- columns = obj['result']['columns']
- rows = obj['result']['values']
- # First prints the column names and then prints each row separately.
- print(columns)
- for row in rows:
- print(row)
-
-
-def main():
- # Establishes an HTTP connection with the Datalayers server.
- #
- # The authorization token `YWRtaW46cHVibGlj` is the encoded username and password
- # which are 'admin' and 'public', respectively.
- host = "127.0.0.1"
- port = 8361
- url = "http://{}:{}/api/v1/sql".format(host, port)
- headers = {
- "Content-Type": "application/binary",
- "Authorization": "Basic YWRtaW46cHVibGlj"
- }
- conn = http.client.HTTPConnection(host=host, port=port)
-
- # Creates a database `test`.
- sql = "create database test;"
- conn.request(method="POST", url=url, headers=headers, body=sql)
- # The returned status code should be 200.
- print_response(conn)
-
- # Creates a table `demo` within the database `test`.
- sql = '''
- CREATE TABLE test.demo (
- ts TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
- sid INT32,
- value REAL,
- flag INT8,
- timestamp key(ts)
- )
- PARTITION BY HASH(sid) PARTITIONS 8
- ENGINE=TimeSeries;
- '''
- conn.request(method="POST", url=url, headers=headers, body=sql)
- # The returned status code should be 200.
- print_response(conn)
-
- # Inserts some data into the `demo` table.
- sql = '''
- INSERT INTO test.demo (ts, sid, value, flag) VALUES
- ('2024-09-01 10:00:00', 1, 12.5, 0),
- ('2024-09-01 10:05:00', 2, 15.3, 1),
- ('2024-09-01 10:10:00', 3, 9.8, 0),
- ('2024-09-01 10:15:00', 4, 22.1, 1),
- ('2024-09-01 10:20:00', 5, 30.0, 0);
- '''
- conn.request(method="POST", url=url, headers=headers, body=sql)
- # The returned status code should be 200.
- print_response(conn)
-
- # Queries the inserted data.
- sql = "SELECT * FROM test.demo"
- conn.request(method="POST", url=url, headers=headers, body=sql)
- # Prints the query result.
- print_query_result(conn)
-
-
-if __name__ == "__main__":
- main()
-```
-
-```Go [Go]
-package main
-
-import (
- "bytes"
- "encoding/base64"
- "encoding/json"
- "fmt"
- "io"
- "net/http"
-)
-
-type Executor struct {
- client *http.Client
- url string
- requestHeaders map[string]string
-}
-
-func makeExecutor(host string, port uint32, username, password string) *Executor {
- auth := username + ":" + password
- encodedAuth := "Basic " + base64.StdEncoding.EncodeToString([]byte(auth))
- headers := make(map[string]string)
- headers["Content-Type"] = "application/binary"
- headers["Authorization"] = encodedAuth
-
- return &Executor{
- client: &http.Client{},
- url: fmt.Sprintf("http://%s:%d/api/v1/sql", host, port),
- requestHeaders: headers,
- }
-}
-
-func (exec *Executor) execute(sql string) (*http.Response, error) {
- encodedSql := bytes.NewBuffer([]byte(sql))
- request, err := http.NewRequest("POST", exec.url, encodedSql)
- if err != nil {
- fmt.Println("Error creating request:", err)
- return nil, err
- }
-
- for k, v := range exec.requestHeaders {
- request.Header.Set(k, v)
- }
-
- response, err := exec.client.Do(request)
- if err != nil {
- fmt.Println("Error sending request:", err)
- return nil, err
- }
- return response, nil
-}
-
-func print_response_status(response *http.Response) {
- fmt.Println("Status:", response.Status)
-}
-
-func print_query_result(response *http.Response) error {
- defer response.Body.Close()
-
- body, err := io.ReadAll(response.Body)
- if err != nil {
- fmt.Println("Error reading response body:", err)
- return err
- }
-
- // Parses the response into json objects.
- var obj map[string]interface{}
- if err = json.Unmarshal(body, &obj); err != nil {
- fmt.Println("Error decoding response into json:", err)
- return err
- }
-
- result := obj["result"].(map[string]interface{})
- columns := result["columns"].([]interface{})
- values := result["values"].([]interface{})
-
- // Print column names
- for _, col := range columns {
- fmt.Print(col, " ")
- }
- fmt.Println()
-
- // Print each row
- for _, row := range values {
- for _, val := range row.([]interface{}) {
- fmt.Print(val, " ")
- }
- fmt.Println()
- }
-
- return nil
-}
-
-func main() {
- // Setups an executor for executing sql against the Datalayers server.
- executor := makeExecutor("127.0.0.1", 8361, "admin", "public")
-
- // Creates a database `test`.
- sql := "create database test;"
- response, err := executor.execute(sql)
- if err != nil {
- fmt.Println("Error executing sql: ", err)
- return
- }
- // The returned status should be 200.
- print_response_status(response)
-
- // Creates a table `demo` within the database `test`.
- sql = `
- CREATE TABLE test.demo (
- ts TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
- sid INT32,
- value REAL,
- flag INT8,
- timestamp key(ts)
- )
- PARTITION BY HASH(sid) PARTITIONS 8
- ENGINE=TimeSeries;`
- response, err = executor.execute(sql)
- if err != nil {
- fmt.Println("Error executing sql: ", err)
- return
- }
- // The returned status code should be 200.
- print_response_status(response)
-
- // Inserts some data into the `demo` table.
- sql = `
- INSERT INTO test.demo (ts, sid, value, flag) VALUES
- ('2024-09-01 10:00:00', 1, 12.5, 0),
- ('2024-09-01 10:05:00', 2, 15.3, 1),
- ('2024-09-01 10:10:00', 3, 9.8, 0),
- ('2024-09-01 10:15:00', 4, 22.1, 1),
- ('2024-09-01 10:20:00', 5, 30.0, 0);`
- response, err = executor.execute(sql)
- if err != nil {
- fmt.Println("Error executing sql: ", err)
- return
- }
- // The returned status code should be 200.
- print_response_status(response)
-
- // Queries the inserted data.
- sql = "SELECT * FROM test.demo"
- response, err = executor.execute(sql)
- if err != nil {
- fmt.Println("Error executing sql: ", err)
- return
- }
- // Prints the query result.
- //
- // The expected result is:
- // ts sid value flag
- // 2024-09-01T18:05:00+08:00 2 15.3 1
- // 2024-09-01T18:10:00+08:00 3 9.8 0
- // 2024-09-01T18:15:00+08:00 4 22.1 1
- // 2024-09-01T18:00:00+08:00 1 12.5 0
- // 2024-09-01T18:20:00+08:00 5 30 0
- if err = print_query_result(response); err != nil {
- fmt.Println("Error executing sql: ", err)
- }
-}
-```
-
-```Shell [Shell]
-// 创建数据库
-curl -u"admin:public" -X POST \
-http://127.0.0.1:8361/api/v1/sql \
--H 'Content-Type: application/binary' \
--d 'create database demo'
-
-// 创建表
-curl -u"admin:public" -X POST \
-http://127.0.0.1:8361/api/v1/sql?db=demo \
--H 'Content-Type: application/binary' \
--d 'CREATE TABLE sensor_info (
- ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
- sn INT32 NOT NULL,
- speed int,
- longitude float,
- latitude float,
- timestamp KEY (ts)) PARTITION BY HASH(sn) PARTITIONS 2 ENGINE=TimeSeries;'
-
-// 写入数据
-curl -u"admin:public" -X POST \
-http://127.0.0.1:8361/api/v1/sql?db=demo \
--H 'Content-Type: application/binary' \
--d 'INSERT INTO sensor_info(sn, speed, longitude, latitude) VALUES(1, 120, 104.07, 30.59),(2, 120, 104.07, 30.59)'
-
-// 查询数据
-curl -u"admin:public" -X POST \
-http://127.0.0.1:8361/api/v1/sql?db=demo \
--H 'Content-Type: application/binary' \
--d 'SELECT * FROM sensor_info'
-```
-
-:::
diff --git a/zh_CN/development-guide/object-storage.md b/zh_CN/development-guide/object-storage.md
index 6466812a..19d06e1f 100644
--- a/zh_CN/development-guide/object-storage.md
+++ b/zh_CN/development-guide/object-storage.md
@@ -1,21 +1,26 @@
# 对象存储
## 概述
-Datalayers 采用云原生存算分离架构，将计算层和存储层完全解耦，使您能够根据业务需求独立扩展计算和存储资源。这种架构不仅避免了资源浪费，优化了成本效益，同时显著提升了系统的整体性能、安全性和可维护性。因此，在具备对象存储服务的情况下，我们推荐用户优先选择**存算分离**的部署方案。
+
+Datalayers 采用存算分离架构，将计算层和存储层完全解耦，使得能够根据业务需求独立扩展计算和存储资源。这种架构不仅避免了资源浪费，优化了成本效益，同时显著提升了系统的整体性能、安全性和可维护性。因此，在具备对象存储服务的情况下，我们推荐用户优先选择 **存算分离** 的部署方案。
## 架构优势
-**弹性扩展**：计算与存储解耦，支持独立按需扩展
+
+**弹性扩展**：计算与存储解耦，支持独立按需扩展
**运维简单**：使用公有云对象存储时，存储运维由云服务商保障，极大降低运维成本
**快速扩容**：在公有云环境中可通过简单操作实现存储容量的快速扩展
**高可用性**：公有云对象存储通常提供高达 99.999999999%（11个9）的数据持久性，并支持跨区域容灾
## 支持的对象存储服务
+
目前，Datalayers 已支持主流公有云的对象存储服务，包括 AWS、GCP、Azure、阿里云、腾讯云、华为云等。同时，对于兼容 S3 协议的对象存储服务（如 MinIO）也可直接接入。
## 配置对象存储服务
### S3 兼容存储配置
+
如需使用对象存储服务，我们需修改配置文件，配置相应的服务地址，如下（以 S3 为例）：
+
```toml
# The configurations of the S3 object store.
# We support both virtual-hosted–style and path-style URL access in S3 service.
@@ -52,6 +57,7 @@ virtual_hosted_style = true
```
### 指定使用对象存储服务
+
启动对象存储服务后，通过修改以下配置，即可让新创建的表默认使用该对象存储服务，本配置以 s3 为例，配置文件如下：
```toml
diff --git a/zh_CN/development-guide/postgresql/overview.md b/zh_CN/development-guide/postgresql/overview.md
new file mode 100644
index 00000000..8fbe006d
--- /dev/null
+++ b/zh_CN/development-guide/postgresql/overview.md
@@ -0,0 +1,7 @@
+# PostgreSQL 协议（开发中）
+
+Datalayers 兼容 PostgreSQL 网络连接协议，兼容 PostgreSQL 生态的命令行工具、JDBC/ODBC 和各种可视化工具。
+
+## ⚠️注意
+
+该协议目前正在开发中，计划近期发布。
diff --git a/zh_CN/development-guide/prometheus/overview.md b/zh_CN/development-guide/prometheus/overview.md
new file mode 100644
index 00000000..e5a9e19f
--- /dev/null
+++ b/zh_CN/development-guide/prometheus/overview.md
@@ -0,0 +1,12 @@
+# Prometheus 协议
+
+## 概述
+
+Datalayers 兼容 Prometheus 的远程写入协议（Remote Write Protocol） 与 PromQL（Prometheus Query Language）查询语言，支持与 Prometheus 原生生态工具的无缝集成。
+这意味着您可以：
+
+- 继续使用现有的 Prometheus 数据采集配置，仅需调整数据写入目标，即可将监控数据推送至 Datalayers；
+- 使用 Grafana 等可视化工具直接查询 Datalayers 中的监控数据，无需重写查询语句；
+- 在不改变现有监控体系架构的前提下，可将 Datalayers 作为 Prometheus 的补充存储层，或直接作为替代方案，以满足更高性能、更大规模、更优成本等需求。
+
+详见 [Prometheus 兼容](../../prometheus/overview.md)
diff --git a/zh_CN/development-guide/query-with-restapi.md b/zh_CN/development-guide/query-with-restapi.md
deleted file mode 100644
index 623e53ed..00000000
--- a/zh_CN/development-guide/query-with-restapi.md
+++ /dev/null
@@ -1,44 +0,0 @@
-# 数据查询指南
-
-## 概述
-
-
-Datalayers 提供基于 HTTP/HTTPS 协议的 SQL 查询接口，支持通过 REST API 执行各类数据检索操作。查询结果以结构化 JSON 格式返回，包含完整的元数据信息。SQL 相关语法请参考：[SQL Reference](../sql-reference/data-type.md)。
-
-## 基础语法
-**通用请求格式**
-```shell
-curl -u":" -X POST \
-http://127.0.0.1:8361/api/v1/sql?db= \
--H 'Content-Type: application/binary' \
--d ''
-```
-
-## 查询数据示例
-
-执行请求：
-
-```shell
-curl -u"admin:public" -X POST \
-http://127.0.0.1:8361/api/v1/sql?db=demo \
--H 'Content-Type: application/binary' \
--d 'SELECT * FROM sensor_info'
-```
-
-返回值：
-
-```json
-{
- "result": {
- "columns": ["ts", "sn", "speed", "longitude", "latitude"],
- "types": ["TIMESTAMP(3)", "INT32", "INT32", "REAL", "REAL"],
- "values": [
- ["2024-09-22T17:30:56.349+08:00", 1, 120, 104.07, 30.59],
- ["2024-09-22T17:30:56.349+08:00", 2, 120, 104.07, 30.59]
- ]
- }
-}
-```
-
-其中，`result`表示这是一条查询的结果,`columns` 为列名，`types` 为列类型，`values` 为查询到的行数组。需要注意的是，类型中时间戳的表示为`Timestamp(TimeUnit, Timezone)`，当某列类型是时区未被指定的时间戳时，Timezone为None。例如`Timestamp(Millisecond, None)`。
-
diff --git a/zh_CN/development-guide/redis.md b/zh_CN/development-guide/redis.md
new file mode 100644
index 00000000..dd177fca
--- /dev/null
+++ b/zh_CN/development-guide/redis.md
@@ -0,0 +1,10 @@
+# 键值存储使用指南
+
+## 概述
+
+Datalayers 支持兼容 Redis 协议的高性能分布式键值存储服务，支持直接通过标准 Redis 客户端、命令行工具（如 redis-cli）及生态工具无缝接入，无需额外适配。详见[键值存储](../key-value-data-model/overview.md)
+
+## 注意事项
+- 通过该协议连接仅支持 key-value 相关操作
+- 目前 key-value 存储的数据暂不能通过 SQL 互通
+- key-value 存储能力仅在集群模式下支持
diff --git a/zh_CN/development-guide/rest-api/overview.md b/zh_CN/development-guide/rest-api/overview.md
new file mode 100644
index 00000000..fe433d86
--- /dev/null
+++ b/zh_CN/development-guide/rest-api/overview.md
@@ -0,0 +1,102 @@
+# HTTP REST API 接入指南
+
+## 概述
+
+Datalayers 提供标准的 HTTP 协议接口，支持通过简单的 RESTful 请求直接与数据库交互（如执行 SQL 语句、管理数据库对象等）。本指南将介绍如何快速接入 API，包括认证方式、基础用法、常见操作示例及错误处理规范。
+
+通过 HTTP REST API，您可以使用任意支持 HTTP 请求的工具（如 curl、Postman 或自定义代码）与 Datalayers 通信，无需依赖特定客户端库。该接口设计遵循 RESTful 原则，以 SQL 语句为核心操作载体，通过 HTTP 方法提交 SQL 请求，并返回结构化结果（JSON 格式）与操作状态码。
+
+## 认证方式
+
+Datalayers REST API 默认使用 `HTTP BASIC` 认证 认证方式，认证凭据通过 HTTP 头部传递。帐户信息参考：[认证与权限](../../user-security/authentication/overview.md)
+
+
+## 基本用法
+
+```shell
+curl -u":" -X POST \
+http://:/api/v1/sql?db= \
+-H 'Content-Type: application/binary' \
+-d ''
+```
+
+**参数说明**：
+- `:`：Datalayers 的认证凭据（如 admin:public）。
+- `:`：Datalayers 服务的 HTTP API 地址（示例中为 127.0.0.1:8361，实际以您的部署配置为准）。
+- `db=`：目标数据库名称（通过 ?db=参数指定，若操作不涉及数据库可省略）。
+- ``：待执行的 SQL 语句（如建库、建表、插入数据等，需用单引号包裹）。
+
+## 示例
+
+### 创建数据库
+
+```shell
+curl -u"admin:public" -X POST \
+http://127.0.0.1:8361/api/v1/sql \
+-H 'Content-Type: application/binary' \
+-d 'create database demo'
+```
+
+返回值：
+
+```json
+{"affected_rows":0}
+```
+
+### 创建表
+
+```shell
+curl -u"admin:public" -X POST \
+http://127.0.0.1:8361/api/v1/sql?db=demo \
+-H 'Content-Type: application/binary' \
+-d 'CREATE TABLE sensor_info (
+ ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+ sn INT32 NOT NULL,
+ speed int,
+ longitude float,
+ latitude float,
+ timestamp KEY (ts)) PARTITION BY HASH(sn) PARTITIONS 2 ENGINE=TimeSeries;'
+```
+
+### 写入数据
+
+```shell
+curl -u"admin:public" -X POST \
+http://127.0.0.1:8361/api/v1/sql?db=demo \
+-H 'Content-Type: application/binary' \
+-d 'INSERT INTO sensor_info(sn, speed, longitude, latitude) VALUES(1, 120, 104.07, 30.59),(2, 120, 104.07, 30.59)'
+```
+
+### 查询数据
+
+```shell
+curl -u"admin:public" -X POST \
+http://127.0.0.1:8361/api/v1/sql?db=demo \
+-H 'Content-Type: application/binary' \
+-d 'SELECT * FROM sensor_info'
+```
+
+## HTTP 状态码
+
+Datalayers 遵循标准的 [HTTP状态码](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) 规范，提供清晰的错误信息帮助用户快速定位和解决问题。本文详细说明各类错误码的含义和相应的处理建议。
+
+| HTTP CODE | 描述 |
+| ---- | ---- |
+| 200 | 请求成功，返回的 JSON 数据将提供更多信息 |
+| 201 | 创建成功，新建的对象将在 Body 中返回 |
+| 204 | 请求成功，常用于删除与更新操作，Body 不会返回内容 |
+| 400 | 请求无效，例如请求体或参数错误 |
+| 401 | 未通过服务端认证，API 密钥过期或不存在时可能会发生 |
+| 403 | 无权操作，检查操作对象是否正在使用或有依赖约束 |
+| 404 | 找不到请求路径或请求的对象不存在，可参照 Body 中的 message 字段判断具体原因 |
+| 405 | Method Not Allowed |
+| 409 | 请求的资源已存在或数量超过限制 |
+| 500 | 服务端处理请求时发生内部错误，可通过 Body 返回内容与日志判断具体原因 |
+
+**错误报文**
+
+```json
+{
+ "error": "Only support execute one statement"
+}
+```
diff --git a/zh_CN/development-guide/downsampling.md b/zh_CN/development-guide/time-window-aggregation-query.md
similarity index 55%
rename from zh_CN/development-guide/downsampling.md
rename to zh_CN/development-guide/time-window-aggregation-query.md
index 75d1efe4..a52f9919 100644
--- a/zh_CN/development-guide/downsampling.md
+++ b/zh_CN/development-guide/time-window-aggregation-query.md
@@ -1,21 +1,24 @@
-# 聚合查询：降采样与时间窗口分析
+# 聚合查询
## 概述
-在时序数据场景中，降采样与聚合计算是核心的数据处理技术。通过降低数据采样频率并将多个数据点合并为代表性数值，能够有效减少计算和传输开销，特别适用于长期趋势分析和可视化展示。
+
+在时序数据场景中，聚合运算是核心的数据处理技术。通过降低数据采样频率并将多个数据点合并为代表性数值，能够有效减少计算和传输开销，特别适用于长期趋势分析和可视化展示。
## 应用价值
-- 性能优化：减少数据处理量，提升查询效率
-- 趋势分析：保留关键数据特征，突出长期变化规律
-- 资源节约：降低存储、传输和计算资源消耗
-- 可视化友好：生成适合图表展示的数据密度
-典型应用场景：工业物联网监控、系统性能指标分析、业务数据趋势展示等。
+- **性能优化**：减少数据处理量，提升查询效率
+- **趋势分析**：保留关键数据特征，突出长期变化规律
+- **资源节约**：降低存储、传输和计算资源消耗
+- **可视化友好**：生成适合图表展示的数据密度
+典型应用场景：工业物联网监控、系统性能指标分析、业务数据趋势展示等。
## 时间窗口聚合查询
+
### 场景说明
-以传感器数据为例，采集频率为1秒级别。当需要展示最近一天或一个月的数据趋势时，原始数据点过于密集会导致：
+以传感器数据为例，采集频率为`100Hz`。当需要展示最近一天或一个月的数据趋势时，原始数据点过于密集会导致：
+
- 数据传输量过大
- 客户端渲染性能下降
- 图表可读性差（点距过密）
@@ -23,7 +26,9 @@
时间窗口聚合通过数据分组和计算，有效解决上述问题。
### 数据表结构示例
+
Table schema 如下：
+
```sql
CREATE TABLE sensor_info (
ts TIMESTAMP(9) NOT NULL DEFAULT CURRENT_TIMESTAMP,
@@ -37,7 +42,9 @@ CREATE TABLE sensor_info (
```
### 查询示例
+
#### 分钟级聚合分析
+
查询设备`sn=1`的温度数据，按1分钟窗口计算平均值
```sql
@@ -50,7 +57,9 @@ GROUP BY timepoint
```
#### 天级聚合分析
+
查询设备sn=1的温度数据，按1天窗口计算最大值
+
```sql
SELECT
date_bin('1 day', ts) as timepoint,
@@ -61,8 +70,9 @@ GROUP BY timepoint
```
更多函数说明：
-* [聚合函数](../sql-reference/aggregation.md)
-* [时间与日期函数](../sql-reference/date.md)
-* [数学函数](../sql-reference/math.md)
-* [插值函数](../sql-reference/gap_fill.md)
-* [Json 函数](../sql-reference/json.md)
+
+- [聚合函数](../sql-reference/aggregation.md)
+- [时间与日期函数](../sql-reference/date.md)
+- [数学函数](../sql-reference/math.md)
+- [插值函数](../sql-reference/gap_fill.md)
+- [Json 函数](../sql-reference/json.md)
diff --git a/zh_CN/getting-started/centos.md b/zh_CN/getting-started/centos.md
index c3a6f522..0033afcd 100644
--- a/zh_CN/getting-started/centos.md
+++ b/zh_CN/getting-started/centos.md
@@ -79,4 +79,4 @@ sudo yum remove datalayers
成功启动容器后，您可以通过以下方式体验 Datalayers：
- 使用命[命令行工具](./command-line-tool.md)连接数据库进行操作
- 使用 [DBeaver](../integration/datalayers-with-dbeaver.md) 连接数据库进行操作
-- 使用 [HTTP](../development-guide/insert-with-restapi.md) 协议连接数据库进行操作
+- 使用 [HTTP](../development-guide/rest-api/overview.md) 协议连接数据库进行操作
diff --git a/zh_CN/getting-started/command-line-tool.md b/zh_CN/getting-started/command-line-tool.md
index fc80fdf5..1749f9af 100644
--- a/zh_CN/getting-started/command-line-tool.md
+++ b/zh_CN/getting-started/command-line-tool.md
@@ -4,19 +4,27 @@
dlsql 是 Datalayers 内置的一个 通过 SQL 交互的命令行管理工具，为用户提供高效、便捷的数据库操作与管理。
+详细用法参考 [命令行工具](../admin/datalayers-cli.md)。
+
## 连接数据库
+
Datalayers 安装完成后，便可使用 dlsql 工具实现数据库的连接，其格式如下：
> 在静态认证的模式下（默认为静态认证），Datalayers 提供了一个默认账号，其用户名/密码为: `admin/public`
+
``` bash
-dlsql -u admin -p public
+dlsql -h 127.0.0.1 -u admin -p public
```
+
参数说明：
+
+- `-h`参数用于指定服务器地址；
- `-u`参数用于指定用户名；
- `-p`参数用于指定用户对应的密码；
以下是使用 dlsql 来连接 Datalayers 数据库的简单实例：
+
``` bash
-dlsql -u admin -p public
+dlsql -h 127.0.0.1 -u admin -p public
```
若需要更换主机地址、启动端口等参数，可使用以下命令执行：
@@ -32,13 +40,13 @@ dlsql -h -P -u admin -p public
连接数据库服务后，可以执行以下命令创建一个数据库：
``` sql
-create database demo;
+> create database demo;
```
-可通过以下命令查看数据库的情况：
+可通过以下命令查看当前帐户下所有数据库：
``` sql
-show databases;
+> show databases;
```
## 创建表
@@ -46,7 +54,7 @@ show databases;
首先选中要执行操作的数据库：
``` sql
-use demo;
+> use demo;
```
接着，可以通过以下命令尝试创建数据表：
@@ -66,6 +74,7 @@ CREATE TABLE sensor_info (
> Datalayers 支持更多[数据类型](../sql-reference/data-type.md)以及[表配置](../sql-reference/table-engine/timeseries.md)。
## 写入数据
+
可以执行以下命令写入一些示例数据：
``` sql
@@ -79,7 +88,9 @@ INSERT INTO sensor_info(sn, speed, temperature) VALUES('100', 22.12, 30.8), ('10
``` sql
use demo;
```
+
以下是一些查询操作示例：
+
- 查询表中记录总条数：
``` sql
@@ -98,7 +109,6 @@ SELECT AVG(speed) FROM sensor_info;
SELECT date_bin('1 days', ts) as timepoint, count(*) as total from sensor_info group by timepoint;
```
-
## 其他常见操作
查看所有表：
@@ -130,16 +140,11 @@ DROP TABLE sensor_info;
``` sql
DROP DATABASE demo;
```
-**注：删除数据库，需要先删除所有表。**
-## 退出
+**注**：删除数据库前，必须先行删除其包含的所有表。若数据库中存在表，为确保数据安全，删除操作将被系统禁止。
-使用以下命令可退出交互：
+## 退出
-``` sql
-exit
-```
+使用 `exit` 或者 `quit` 命令可退出交互终端。
-::: tip
更多 SQL 相关的使用，可查看 [SQL 参考](../sql-reference/data-type.md) 章节。
-:::
diff --git a/zh_CN/getting-started/docker.md b/zh_CN/getting-started/docker.md
index 9c5c63f0..96cbb699 100644
--- a/zh_CN/getting-started/docker.md
+++ b/zh_CN/getting-started/docker.md
@@ -50,4 +50,4 @@ docker exec -it datalayers bash
成功启动容器后，您可以通过以下方式体验 Datalayers：
- 使用命[命令行工具](./command-line-tool.md)连接数据库进行操作
- 使用 [DBeaver](../integration/datalayers-with-dbeaver.md) 连接数据库进行操作
-- 使用 [HTTP](../development-guide/insert-with-restapi.md) 协议连接数据库进行操作
+- 使用 [HTTP](../development-guide/rest-api/overview.md) 协议连接数据库进行操作
diff --git a/zh_CN/getting-started/ubuntu.md b/zh_CN/getting-started/ubuntu.md
index 8d1b954f..6d66d4b1 100644
--- a/zh_CN/getting-started/ubuntu.md
+++ b/zh_CN/getting-started/ubuntu.md
@@ -139,4 +139,4 @@ sudo dpkg -P datalayers
成功启动容器后，您可以通过以下方式体验 Datalayers：
- 使用命[命令行工具](./command-line-tool.md)连接数据库进行操作
- 使用 [DBeaver](../integration/datalayers-with-dbeaver.md) 连接数据库进行操作
-- 使用 [HTTP](../development-guide/insert-with-restapi.md) 协议连接数据库进行操作
+- 使用 [HTTP](../development-guide/rest-api/overview.md) 协议连接数据库进行操作
diff --git a/zh_CN/index.md b/zh_CN/index.md
index 815207e7..3c274f2e 100644
--- a/zh_CN/index.md
+++ b/zh_CN/index.md
@@ -1,42 +1,50 @@
# 概述
-Datalayers 是一款面向工业物联网、车联网、具身智能、AI、能源等领域的**分布式多模态超融合数据库**。原生支持时序、日志、键值、指标、追踪等多种数据模型，提供一站式数据服务平台，实现多模态数据的统一管理、高效处理与深度分析。
+Datalayers 是一款面向工业物联网、车联网、具身智能、AI、能源等领域的**分布式多模态超融合数据库**。为时序、日志、键值、指标、向量、链路追踪等多种存储检索需求场景提供一站式数据服务平台，实现多模态数据的统一管理、高效处理与深度分析。
## 核心功能特性
### 时序数据存储
+
- 专为时序数据优化的存储引擎，支持高吞吐写入与海量时间线管理
- 提供行业领先的数据压缩比，大幅降低存储成本
- 内置丰富的时序处理函数，满足复杂分析需求
### 向量检索
+
- 支持最高16000维 Float 类型稠密向量
- 提供多种向量相似度计算算法
- 支持混合检索模式，结合语义与特征向量
### 日志检索
+
- 支持对海量日志进行高效查询
- 丰富的索引类型，可在成本、性能、效率间进行平衡
### 高性能键值存储
+
- 提供分布式、持久化的 Key-Value 存储引擎
- 完全兼容 Redis 协议，支持常用数据结构
- 平滑迁移现有 Redis 应用，无需代码改造
### 存算分离架构
+
- 存储与计算资源独立扩展，优化资源利用率
- 支持按需弹性伸缩，灵活应对业务波动
- 支持主流云厂商的对象存储服务集成，如：阿里云、华为云、腾讯去、AWS、Azure、GCP等，同时对于兼容 S3 协议的对象存储服务也可 0 代码接入（如：MinIO）
### 联邦查询
+
- 支持与MySQL、PostgreSQL 等进行联邦查询，可在 Datalayers 中像查询普通表一样，支持 SELECT、JOIN 等操作
### 受限设备支持
+
- 专为资源受限设备深度优化
- 在有限资源环境下实现高性能数据处理
- 满足边缘计算场景的特殊需求
### 生态丰富
+
- 使用 SQL (兼容 MySQL 方言)作为查询语言，以降低学习、使用与迁移成本
- 完整实现 `Arrow Flight SQL` 协议，实现数据高速传输
- 即将支持 `PostgreSQL` 网络连接协议
diff --git a/zh_CN/integration/datalayers-with-emqx.md b/zh_CN/integration/datalayers-with-emqx.md
index fc0ec049..808a8e80 100644
--- a/zh_CN/integration/datalayers-with-emqx.md
+++ b/zh_CN/integration/datalayers-with-emqx.md
@@ -5,12 +5,14 @@
本章节介绍如何通过 EMQX 的规则引擎数据数据存储到 Datalayers 中。
## 前置条件
+
1. 已安装 Datalayers, 版本要求：>= 2.1.8。
2. 已安装 EMQX 企业版，版本要求：>= 5.8。
## 配置步骤
-### 配置 Datalayers
+### 配置 Datalayers
+
向 Datalayers 中写入数据，需提前创建 `database` 与 `table`，可使用 Datalayers 命令行工具 `dlsql` 来进行创建。
```sql
@@ -31,20 +33,22 @@ Query OK, 0 rows affected. (0.034 sec)
```
-
### 配置 EMQX
+
#### 创建连接器
+
- 登录 EMQX 管理控制台
- 左侧菜单导航致至 `集成` > `连接器`
- 点击 "创建"，在搜索框中输入 `Datalayers`，在搜索结果中选择 **Datalayers**, 点击下一步
- 填写 **Datalayers** 连接信息，填写完成后可点击**测试连接**，确保连接成功，如下图：
-```
-注：服务器通讯地址填写 `Datalayers HTTP 地址`
-```
+
+**注**：服务器通讯地址填写 `Datalayers HTTP 地址`
+
- 点击`创建`，保存资源配置
#### 创建规则
+
- 在左侧菜单导航 `集成` > `规则` 页面，在左侧 SQL 编辑器中填写相应的 SQL 规则，点击右侧 `创建`。如下图：
- 在创建规则页面填写相应连接器信息、数据模板。如下图：
@@ -52,20 +56,26 @@ Query OK, 0 rows affected. (0.034 sec)
在`写语句`的编辑器中，写入相应的语句模板。
- 在右下角点击创建，以保存动作
- 在创建规则页面，点击`保存`
-```
+
+```text
此时，经过以上几步实现了使用 EMQX 规则引擎将数据写入到 Datalayers 中。
```
+
## 数据写入示例
+
通过以上配置后，我们通过向 EMQX 发布消息（topic以 `t/` 开头），相应的数据就会自动保存到 Datalayers 中。我们使用 EMQX Dashboard 中提供的问题分析工具 > WebSocket 客户端来演示说明。
- 在右边连接配置中，确保相应配置信息正常，点击连接，确保成功连接到 MQTT Broker
- 在订阅栏中，主题框中输入 `t/#` 进行通配订阅，方便后续观察
- 在发布窗口中，主题框输入`t/1`，Payload 框中输入 `{ "sid": "1", "temp":25.6 }`，点击发布，此时我们将看到 pub 与 sub 的消息，如下：
-```
+
+```text
此时，说明已经成功将数据 pub 到了 MQTT Broker 中。
```
+
- 使用 Datalayers dlsql 命令行工具查看写入的数据
+
```sql
demo> select * from sensor_info;
+-------------------------------+-----+------+
diff --git a/zh_CN/integration/datalayers-with-grafana.md b/zh_CN/integration/datalayers-with-grafana.md
index 349fbf9a..1f77bfb6 100644
--- a/zh_CN/integration/datalayers-with-grafana.md
+++ b/zh_CN/integration/datalayers-with-grafana.md
@@ -23,7 +23,7 @@ Datalayers 支持多种安装方式，具体安装方法请参考**快速开始*
首先，通过以下命令连接到数据库：
``` bash
-dlsql -u admin -p public
+dlsql -h 127.0.0.1 -u admin -p public
```
然后创建一个示例数据库：
diff --git a/zh_CN/key-value-data-model/overview.md b/zh_CN/key-value-data-model/overview.md
index c432ab01..1c57cc38 100644
--- a/zh_CN/key-value-data-model/overview.md
+++ b/zh_CN/key-value-data-model/overview.md
@@ -1,15 +1,19 @@
# 概述
-Key-Value 数据模型是 `Datalayers` 的核心能力之一，提供一个分布式的、具备事务性和强一致性保证的Key-Value存储系统，Datalayers 的 Key-Value 存储模型在使用上完全兼容 Redis 协议，并支持常用的数据数据结构，详见：[Redis 兼容](./redis-compatibility.md) 章节。
+Datalayers 键值存储服务是一个分布式、支持海量存储的的高性能键值存储系统。该服务完全兼容 Redis 协议，用户可直接沿用熟悉的 Redis 客户端、工具链及开发模式，无需为协议适配或架构改造投入额外成本，即享分布式环境下的稳定、高效键值存储能力。
-注：Key-Value 模型仅集群模式下支持。
+## 核心特性
-## 要求
-Key-Value 数据模型在 Datalayers 2.1.8 版本中发布，使用 Key-Value 时， Datalayers 的版本必须 >= 2.1.8。
+- **协议 & 生态无缝兼容**
+ 完全兼容 Redis 协议，支持通过标准 Redis 客户端、命令行工具及生态工具直接接入，业务代码零改造。
+- **丰富的数据结构支持**
+ 原生支持 Redis 常用数据结构，祥见：[Redis兼容性](./redis-compatibility.md)。
+- **低成本高性能存储**
+ 支持 TB 级别 key-value 数据存储 ，依托分布式架构实现弹性扩展，显著降低的服务器资源成本与运维复杂度。
+- **平滑迁移体验**
+ 提供“零代码修改”的 Redis 迁移方案，业务无需调整逻辑即可从原生 Redis 或其他兼容服务无缝迁移至 Datalayers，快速完成存储底座升级。
-## Features
-
-* 完全兼容 Redis 协议，可使用 Redis 客户端接入。
-* 支持常用 Redis 数据结构，参见：[Redis兼容性](./redis-compatibility.md)。
-* 支持 TB 级别的 key-value 存储，能够极大降低服务器资源成本与运维成本。
-* 迁移简单，不用修改代码即可从 Redis 迁移至 Datalayers。
+## 注意事项
+- 通过该协议连接仅支持 key-value 相关操作
+- 目前 key-value 存储的数据暂不能通过 SQL 互通
+- key-value 存储能力仅在集群模式下支持
diff --git a/zh_CN/key-value-data-model/quick-start.md b/zh_CN/key-value-data-model/quick-start.md
index ad24eafe..bae6d8d8 100644
--- a/zh_CN/key-value-data-model/quick-start.md
+++ b/zh_CN/key-value-data-model/quick-start.md
@@ -1,26 +1,45 @@
# 快速开始
-本节将引导您快速启动并使用Datalayers Key-Value服务 的基本步骤。
+Datalayers 提供兼容 Redis 协议的键值存储服务，本节将指导您快速启用并连接该服务，完成从配置到验证的全流程操作。
-## 启动Datalayers服务
+## 配置 Redis 服务
-通过以下配置可开启 Datalayers 的 Key-Value 存储服务。
+Datalayers 中的键值存储服务默认处于禁用状态，通过以下配置可开启 Datalayers 的 Key-Value 存储服务。
-1. 打开 `config/config.toml` 文件，并找到 `[server]` 部分。
-2. 将此部分中的 `standalone` 键设置为 `false`。
-3. 取消注释同一部分中的 `redis` 键。
-4. 保存配置文件并退出。
-5. 使用以下命令启动Datalayers服务：
+配置文件默认路径为：`/etc/datalayers/datalayers.toml`
- ```bash
- ./target/debug/datalayers -c ./config/config.toml
- ```
+```toml
+# The configurations of the Redis service.
+[server.redis]
+# Users can start this service only when Datalayers server starts in cluster mode.
+# Do not support redis service by default.
+# Default: "".
+addr = "0.0.0.0:6379"
-## 使用Redis-cli连接到Datalayers
+# The username.
+# Default: "admin".
+username = "admin"
-1. 如果您的系统尚未安装Redis，可以按照[Install Redis | Docs](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/)中的说明下载并安装Redis。
-2. 安装完成后，使用以下命令连接到Datalayers Key-Value服务：
+# The password.
+# Default: "public".
+password = "public"
+```
- ```bash
- redis-cli -p 8362
- ```
+## 启动 Datalayers
+
+```bash
+# 使用 systemd
+sudo systemctl restart datalayers
+
+# 或者命令行
+./target/debug/datalayers -c ./config/config.toml
+```
+
+## 使用 Redis-cli 连接
+
+1. 如果您的系统尚未安装Redis，可以按照 [Install Redis | Docs](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/) 中的说明下载并安装Redis。
+2. 安装完成后，使用以下命令连接到 Datalayers 键值存储服务：
+
+```bash
+redis-cli -p 8362
+```
diff --git a/zh_CN/key-value-data-model/redis-compatibility.md b/zh_CN/key-value-data-model/redis-compatibility.md
index fb263e14..97b596fd 100644
--- a/zh_CN/key-value-data-model/redis-compatibility.md
+++ b/zh_CN/key-value-data-model/redis-compatibility.md
@@ -1,6 +1,10 @@
-# Redis兼容性
+# Datalayers Redis 兼容性说明
-当前Datalayers Key-Value数据模型的实现支持一部分Redis命令，详细如下：
+## 概述
+
+Datalayers Key-Value 服务兼容大部分常用的 Redis 命令，详见下表。
+
+## 支持命令总览
| 命令类别
| 命令 | 支持级别
| 备注 |
| --- | --- | --- | --- |
@@ -30,8 +34,7 @@
| | ZREM | 完全支持 | |
| | ZCARD | 完全支持 | |
-## 备注
+## 注意事项
-- **支持级别:**
- - **完全支持**: 该命令得到了完全支持。尽管语法和行为应与Redis非常接近，但可能存在细微差异。具体细节请参见备注。
- - **部分支持**: 该命令得到了部分支持。仅支持某些语法或功能。具体细节请参见备注。
+- **完全支持**: 该命令得到了完全支持。尽管语法和行为应与Redis非常接近，但可能存在细微差异。具体细节请参见备注。
+- **部分支持**: 该命令得到了部分支持。仅支持某些语法或功能。具体细节请参见备注。
diff --git a/zh_CN/prometheus/overview.md b/zh_CN/prometheus/overview.md
new file mode 100644
index 00000000..7031cdcd
--- /dev/null
+++ b/zh_CN/prometheus/overview.md
@@ -0,0 +1,33 @@
+# Prometheus 协议兼容
+
+## 概述
+
+Datalayers 兼容 Prometheus 的远程写入协议（Remote Write Protocol） 与 PromQL（Prometheus Query Language）查询语言，支持与 Prometheus 原生生态工具的无缝集成。
+这意味着您可以：
+
+- 继续使用现有的 Prometheus 数据采集配置，仅需调整数据写入目标，即可将数据推送至 Datalayers，实现大规模数据长期低成本存储；
+- 使用 Grafana 等可视化工具直接查询 Datalayers 中的监控数据，无需重写查询语句；
+- 在不改变现有监控体系架构的前提下，将 Datalayers 作为 Prometheus 的替代方案，以满足高性能、大规模、低存储成本等需求。
+
+## 主要优势
+
+- **无缝集成**
+ 支持 Prometheus 原生 Remote Write 协议，可接收 Prometheus 的实时数据推送。
+- **生态兼容**
+ 兼容标准的 PromQL（Prometheus Query Language） 与 HTTP API，可直接对接 Grafana 等生态组件对接。
+- **集群支持**
+ 原生分布式支持，可通过水平扩展实现计算与存储能力的扩展。
+- **低存储成本**
+ Datalayers 支持与主流云厂商的对象存储服务（Object Storage）无缝集成，包括：
+ - 阿里云 OSS
+ - 华为云 OBS
+ - 腾讯云 COS
+ - AWS S3
+ - Azure Blob Storage
+ - Google Cloud Storage (GCS)
+
+ ```text
+ 同时，对于兼容 S3 协议的第三方对象存储服务（如 MinIO），支持零代码接入，帮助您以极低的成本实现监控数据的长期、安全、高效存储。
+ ```
+
+- **高性能/长期存储**：利用 Datalayers 的存储优势，解决原生 Prometheus 在大规模或长期存储场景下的性能和容量瓶颈。
diff --git a/zh_CN/prometheus/promql-compatibility.md b/zh_CN/prometheus/promql-compatibility.md
new file mode 100644
index 00000000..0c4d099d
--- /dev/null
+++ b/zh_CN/prometheus/promql-compatibility.md
@@ -0,0 +1,30 @@
+# PromQL 兼容性
+
+## 概述
+
+Datalayers 提供高度兼容的 PromQL 查询能力，支持绝大多数常用的选择器、运算符和函数，确保从 Prometheus 平滑迁移。
+
+## 选择器
+
+Datalayers 支持 Instant 选择器和 Range 选择器。
+
+**标签匹配支持**：
+
+|匹配运算符 | 普通标签 | 特殊标签 `__name__` | 特殊标签 `__database__` |
+| :--- | :--- | :--- | :--- |
+| = | ✅ 支持 |✅ 支持 |✅ 支持 |
+| != | ✅ 支持 |✖ 不支持 |✖ 不支持 |
+| =~ | ✅ 支持 |✖ 不支持 |✖ 不支持 |
+| !~ | ✅ 支持 |✖ 不支持 |✖ 不支持 |
+
+**注**：Datalayers 支持 `offset` 修饰符，但不支持 `@` 修饰符。
+
+## 运算符和函数
+
+| 类型 | 支持 | 不支持 |
+| :--- | :--- | :--- |
+| **运算符** | `neg`, `add`, `sub`, `mul`, `div`, `mod`, `eq`, `ne`, `gt`, `lt`, `ssgt`, `sslt`, `sseq`, `ssne`, `slt`, `sle`, `sge`, `power`, `atan2`, `and`, `or`, `unless` | - |
+| **聚合** | `sum`, `avg`, `min`, `max`, `stddev`, `stdvar`, `topk`, `bottomk`, `count_values`, `count`, `quantile`, `grouping`| `limitk`, `limit_ratio` |
+| **Instant 函数** | `abs`, `ceil`, `exp`, `ln`, `log2`, `log10`, `sqrt`, `acos`, `asin`, `atan`, `sin`, `cos`, `tan`, `acosh`, `asinh`, `atanh`, `sinh`, `cosh`, `scalar`, `tanh`, `timestamp`, `sort`, `sort_desc`, `histogram_quantile`, `predict_linear`, `absent`, `sgn`, `pi`, `deg`, `rad`, `floor`, `clamp`, `clamp_max`, `clamp_min` | 其它 `histogram_` 函数|
+| **Range 函数** | `idelta`, `_over_time` (如 `count_over_time`, `stddev_over_time`, `stdvar_over_time`), `changes`, `delta`, `rate`, `deriv`, `increase`, `irate`, `reset` | - |
+| **其他函数** | `label_join`, `label_replace`, `sort_by_label`, `sort_by_label_desc` | - |
diff --git a/zh_CN/prometheus/quick-start.md b/zh_CN/prometheus/quick-start.md
new file mode 100644
index 00000000..f802c937
--- /dev/null
+++ b/zh_CN/prometheus/quick-start.md
@@ -0,0 +1,95 @@
+# 快速开始
+
+Datalayers 完全兼容 Prometheus Remote Write 协议，可无缝承接 Prometheus 数据流。本指南将帮助您快速完成数据接入和查询配置。
+
+## 数据写入配置
+
+### 配置 Prometheus Remote Write
+
+通过 Prometheus Remote Write 协议，可以将 Prometheus 中的数据快速导入 Datalayers。为此，您需要在 Prometheus 的配置文件中增加以下内容，将 Datalayers 设置为 Remote Write 端点：
+
+```yaml
+remote_write:
+- url: https://:/api/v1/write
+ basic_auth:
+ username:
+ password:
+ headers:
+ database:
+```
+
+**参数说明**：
+
+- `` 和 ``：Datalayers 服务地址和 HTTP 端口
+- `` 和 ``：认证凭据（默认：admin/public）
+- ``：目标数据库名称（需预先创建）
+
+### 配置示例
+
+```yaml
+# 实际配置示例
+remote_write:
+ - url: "http://localhost:9090/api/v1/write"
+ basic_auth:
+ username: admin
+ password: public
+ headers:
+ database: prometheus_metrics
+```
+
+## 数据查询 API
+
+Datalayers 提供完整的 Prometheus HTTP API 兼容接口：
+
+- Instant queries: `/api/v1/query`
+- Range queries: `/api/v1/query_range`
+- Series: `/api/v1/series`
+- Label names: `/api/v1/labels`
+- Label values: `/api/v1/label//values`
+
+### 查询示例
+
+这些接口的输入和输出与 Prometheus 保持一致。例如，您可以通过如下请求查询指标 `up` 在 `2025-07-22T10:00:00Z` 时刻的数据：
+
+```shell
+curl -v \
+ -u admin:public \
+ -H "database:prom" \
+ -d "query=up&time=2025-07-22T10:00:00Z" \
+ "http://localhost:9090/api/v1/query"
+```
+
+### 响应格式
+
+```json
+{
+ "status": "success",
+ "data": {
+ "resultType": "vector",
+ "result": [
+ { "metric": { "__name__": "up", "sid": "s1", "flag": "ok" }, "value": [ 1753178400.0, "1" ] },
+ { "metric": { "__name__": "up", "sid": "s2", "flag": "fail" }, "value": [ 1753178400.0, "0" ] },
+ { "metric": { "__name__": "up", "sid": "s3", "flag": "ok" }, "value": [ 1753178400.0, "2" ] }
+ ]
+ }
+}
+```
+
+更多关于 API 的内容可参考 [Prometheus 官方文档](https://prometheus.io/docs/prometheus/latest/querying/api/)。
+
+### 注意事项
+
+相较于 Prometheus，Datalayers 有额外的数据库的概念，每个 metric 都归属于某个数据库，因此在查询时需要显式指明数据库的名称。可通过以下两种方式指定数据库：
+
+1. 在 HTTP 请求的 header 中增加 `database: `，之后查询的 metric 都会默认归属该数据库
+2. 或者通过标签 `__database__` 指定数据库，如 `up{__database__="dbname"}`。通过这种方式可以覆盖 HTTP header 中指定的数据库。
+
+## Grafana 集成配置
+
+您可以直接将 Datalayers 作为 Prometheus 数据源添加到 Grafana 中，具体步骤如下：
+
+- 在 Grafana 中 点击 Add new data source，选择 Prometheus 作为数据源
+- 在 Remote server URL 中填入 Datalayers 服务中配置的 Prometheus 协议地址 `http://:`
+- 在 Authentication method 中选择 Basic authentication，填入用户名和密码
+- 在 Http headers 中增加 header `database: `
+- 点击 Save & Test 进行连通性测试，通过后进入面板编写 PromQL 进行查询
diff --git a/zh_CN/releases/changes.md b/zh_CN/releases/changes.md
index 5bf39886..26e7a312 100644
--- a/zh_CN/releases/changes.md
+++ b/zh_CN/releases/changes.md
@@ -5,17 +5,21 @@
发布日期: 2025-10-20
### 🚀 新功能
+
#### PromQL
+
- 实现 PromQL 主要函数，支持 Prometheus 查询协议
### 优化
+
- 优化 TIMESTAMP 数据类型校验逻辑
- 优化 last cache 逻辑，提升 last cache 效率
- 优化 sst file 过期文件清理逻辑，通过分批清理，降低后端压力
- 优化 compaction 逻辑，提升 compaction 的效率
-- 优化 failover 逻辑，如果启动时节点处于 replay 过程中，不触发 failover 逻辑
+- 优化 failover 逻辑，如果启动时节点处于 prepare 过程中，不触发 failover 逻辑
### 修复
+
- 修复了 PIVOT 函数在特殊情况（复杂 SQL）下可能出现栈溢出的问题
## 2.3.12
@@ -23,18 +27,24 @@
发布日期: 2025-09-24
### 🚀 新功能
+
#### LAST CACHE（时序引擎最新值缓存）
+
- **核心功能**：为时序引擎新增点位最新值缓存机制，显著提升最新数据查询速度
- **性能提升**：查询性能提升数十倍，特别适用于高频访问最新数据的场景（如实时监控大屏）
### ⚡ 性能提升
+
#### 查询优化
+
- 优化查询路径逻辑，在 **高并发场景下** 查询 QPS 提升 **10%+**
#### 内存优化
+
- 调整元数据缓存策略，降低服务运行内存占用
### 🔍 其它
+
- 提供更多维度的运行指标，便于实时观测系统健康状态
- 基础镜像从 **Ubuntu 22.04** 升级至 **Ubuntu 24.04**
- 调整日志格式，关键信息更清晰易读，便于快速定位问题
@@ -46,12 +56,14 @@
发布日期: 2025-09-08
### 新功能
+
- **Primary key**
- 在时序引擎中，支持 `Primary Key` 语句,使用方式见[时序引擎](../sql-reference/table-engine/timeseries.md)介绍。
- **数据导入**
- `dlsql` 支持导入指定的 SQL 脚本。
### 增强
+
- **内存管理**
- 优化内存管理逻辑，加速内存回收，降低请求的尾延时。
@@ -60,31 +72,35 @@
发布日期: 2025-08-28
### 增强
+
- 集群模式下重启时刷新集群元数据（如：内存、CPU等）。
- 优化集群节点退出逻辑，节点退出时更加快速、平滑。
- 优化过期数据清理逻辑，加速脏数据回收，更快释放系统资源。
### 修复
+
- 修复了在 SQL 语句中包含某些特殊字符可能导致 SQL 注入的问题。
- 修复在 DBeaver 中通过 Insert 语句写入可能失败的问题。
-
## 2.3.9
发布日期: 2025-08-18
### 新功能
+
- **SQL HINTS**
- 新增对SQL Hints的支持，允许开发者在查询中嵌入优化器指令，以干预执行计划生成。
- - **并行查询**：通过 parallel_degree 控制查询并行度（如：/*+ SET_VAR(parallel_degree=1) */）
+ - **并行查询**：通过 parallel_degree 控制查询并行度（如：/*+ SET_VAR(parallel_degree=1)*/）
### 增强
+
- **优化查询逻辑**
- 时序场景下，缓存 SST 文件列表，减少元数据加载开销，查询QPS提升5%。
- **写入逻辑优化**
- 移除写入路径冗余的优化器调用，降低写入延迟，提升吞吐量。
### 其它
+
- 优化混合缓存逻辑。
- 优化启动逻辑，降低启动耗时。
@@ -93,6 +109,7 @@
发布日期: 2025-08-03
### 增强
+
- **优化 COMPACT 逻辑**
- 在完全乱序写入的情况下减少内存的占用。
- **优化集群备份、恢复逻辑**
@@ -103,12 +120,14 @@
发布日期: 2025-07-28
### 增强
+
- **支持强制删除节点**
- 新增 force 指令，允许在特殊场景下强制删除节点，提升运维灵活性。
- **增强 S3 协议兼容性**
- 新增对 S3 virtual-hosted-style 访问方式的支持，兼容更多对象存储服务。
### 修复
+
- 优化了 SQL 解析逻辑，确保在各类场景下对列名大小写的处理保持一致，避免因大小写差异导致查询异常。
## 2.3.6
@@ -116,14 +135,16 @@
发布日期: 2025-07-23
### 新功能
+
- **向量检索**
- 内置向量检索支持，增强非结构化数据查询能力，详见[向量检索文档](../vector-search/overview.md)
- **时序引擎增强**
- 新增 `append` 格式支持，允许保留重复主键数据，详细使用参考[table options](../sql-reference/table-engine/timeseries.md)
- **协议兼容性**
- - MCP 协议适配至最新版本，确保与上下游系统的无缝集成
+ - MCP 协议适配至最新版本，确保与上下游系统的无缝集成
### 增强
+
- **数据导出改进**
- 优化 dldump 逻辑，导出效率提升， 在导出大量数据时极大的降低了服务端的内存占用。
- **启动效率提升**
@@ -134,23 +155,26 @@
发布日期: 2025-07-07
### 增强
- - 优化统计信息，提升部份场景聚合函数的性能。
+
+- 优化统计信息，提升部份场景聚合函数的性能。
## 2.3.4
发布日期: 2025-07-03
### 新功能
+
- **窗口函数支持**
- 新增对标准窗口函数的支持，详情请参考[窗口函数文档](../sql-reference/statements/window-function.md)
- **流式窗口函数**
- 扩展窗口函数能力至流式数据处理场景，详见[流式窗口函数文档](../sql-reference/streaming-window.md)
- **PIVOT 操作**
- - 新增 PIVOT 数据透视功能，使用方法参考[PIVOT文档](../sql-reference/statements/pivot.md)
+ - 新增 PIVOT 数据透视功能，使用方法参考[PIVOT文档](../sql-reference/statements/pivot.md)
- **WITHIN GROUP 语法**
- 支持有序集合聚合操作，详见[WITHIN GROUP文档](../sql-reference/statements/within-group.md)
### 增强
+
- **SQL 引擎重构**
- 优化底层处理逻辑，为后续关系引擎集成奠定基础。
- **索引缓存优化**
@@ -165,8 +189,8 @@
- **集群优化**
- 简化高可用逻辑，增强集群稳定性与容错能力。
- 优化节点选举机制，减少脑裂风险，提升故障切换速度。
-- **可观察性增强**
- - 新增混合缓存监控指标。
+- **可观察性增强**
+ - 新增混合缓存监控指标。
- 丰富元数据缓存指标，便于监控缓存健康状态。
- **核心函数优化**
- 优化 last_value 函数，提升大数据集查询性能。
diff --git a/zh_CN/sql-reference/aggregation.md b/zh_CN/sql-reference/aggregation.md
index d51d79d1..5476c8f6 100644
--- a/zh_CN/sql-reference/aggregation.md
+++ b/zh_CN/sql-reference/aggregation.md
@@ -1,6 +1,7 @@
# 聚合函数详解
## 功能概述
+
SQL聚合函数用于对一组数据执行计算并返回单一结果，主要用于数据统计和数据分析。
## 函数列表
diff --git a/zh_CN/sql-reference/column-codec.md b/zh_CN/sql-reference/column-codec.md
index 900afe87..37cd382c 100644
--- a/zh_CN/sql-reference/column-codec.md
+++ b/zh_CN/sql-reference/column-codec.md
@@ -1,11 +1,15 @@
# 列级编码与压缩配置指南
## 概述
-Datalayers 支持为每个列单独配置编码和压缩算法，以优化存储效率和查询性能。通过合理的算法选择，可以在数据压缩率、读写速度之间达到最佳平衡。
-## SQL 语法示例
+Datalayers 采用 **列式存储**，列存专门针对分析型工作负载进行了优化，能够显著提高分析效率、降低存储成本。在列式存储中，表的每一列会独立存储，这为压缩技术的应用提供了便利，从而提高了存储效率。Datalayers 支持为每个列单独配置编码和压缩算法，用户可以根据工作负载的需求，选择合适的编码方式与压缩算法来优化存储和查询性能。
-### 建表时指定编码和压缩
+## 为什么需要压缩
+
+- **存储效率提升**：数据压缩技术能够显著减少物理存储空间需求，使得在同等硬件资源条件下可以存储更大规模的数据集。这种空间效率的提升直接转化为成本节约，特别适合大数据量的分析场景。
+- **查询性能优化**：压缩后的数据体积更小，查询时需要的 I/O 操作与网络传输更少，从而加速查询响应时间。
+
+## 配置编码方式与压缩算法
在 CREATE TABLE 语句中，可以为每个列设置 `ENCODING` 和 `COMPRESSION` 参数：
@@ -24,22 +28,23 @@ ENGINE=TimeSeries
**示例说明**：上述语句为 `sid` 列配置了 `RLE` 编码算法和 `SNAPPY` 压缩算法。
-**注意事项**
+**注意事项**：
+
- 当前版本不支持直接修改列的编码压缩算法。
- Datalayers 不区分 `ENCODING`、`COMPRESSION` 关键词的大小写。
- Datalayers 不区分编码和压缩算法的大小写。例如 `RLE`、`rLE`、`rle` 都视为合法的输入。
- 编码和压缩算法可以用双引号、单引号包裹，也可以不带引号。
-### 查看编码和压缩
+## 查看编码和压缩算法
我们目前提供两种方式查看列的编码和压缩算法：
1. 通过 `SHOW CREATE TABLE ` 语法可以查看某个表的建表语句，其中包括每个列的编码和压缩算法（如果显式设置了）。
2. 通过 `SELECT FROM information_schema.columns where table = ""` 可以从 `information_schema.columns` 系统表中查询某个表的列元信息。其中 `codec` 为 `encoding` 或 `compression`。注意，这里的 `encoding`、`compression` 必须为小写。
-## 支持的编码和压缩算法
+## 编码和压缩算法
-### 编码
+### 列编码
Datalayers 支持的编码算法如下：
@@ -53,8 +58,6 @@ Datalayers 支持的编码算法如下：
关于每个编码算法的定义，参考 [Apache Parquet Encoding](https://parquet.apache.org/docs/file-format/data-pages/encodings/)。
-#### 默认的编码
-
如果没有显式指定编码算法，不同数据类型的默认编码算法为：
- `Boolean`：`RLE`。
@@ -63,8 +66,6 @@ Datalayers 支持的编码算法如下：
- `BYTE_ARRAY`：`DELTA_BYTE_ARRAY`。
- 其他类型：`PLAIN`。
-#### 类型兼容性
-
每个编码算法兼容的类型是一定的。此处列出每个编码算法**不兼容**的类型：
- `RLE`：不兼容 `String`、`Binary` 类型。
@@ -73,7 +74,7 @@ Datalayers 支持的编码算法如下：
- `DELTA_BYTE_ARRAY`：不兼容 `Boolean`。
- `BYTE_STREAM_SPLIT`：不兼容 `Boolean`、`String`、`Binary`。
-### 压缩
+### 压缩算法
Datalayers 支持的压缩算法包括：
@@ -81,14 +82,39 @@ Datalayers 支持的压缩算法包括：
- `SNAPPY`
- `GZIP(gzip_level)`：其中 `gzip_level` 为 `GZIP` 的压缩级别，可选值的范围为 [0, 10]。
- `BROTLI(brotli_level)`：其中 `brotli_level` 为 `BROTLI` 的压缩级别，可选值的范围为 [0, 11]。
-- `LZ4`
- `ZSTD(zstd_level)`：其中 `zstd_level` 为 `ZSTD` 的压缩级别，可选值的范围为 [1, 22]。
- `LZ4_RAW`
关于每个压缩算法的定义，参考 [Apache Parquet Compression](https://parquet.apache.org/docs/file-format/data-pages/compression/)。
-::: tip
-- 压缩算法作用于 byte 级别，因此与数据类型无关，Datalayers 的所有数据类型都支持配置以上任意一种压缩算法。
-- 不同的压缩算法具有不同的压缩指标，包括压缩率、压缩与解压缩耗时、压缩与解压缩资源占用等。需要根据具体的场景权衡各项指标，选择合适的压缩算法。
-- 通常来说，压缩级别越高，压缩后数据文件越小，即压缩率越高。但是请注意，高压缩级别会增加压缩、解压缩时的资源开销与耗时。
-:::
+## 影响压缩率的因素
+
+数据压缩率不仅受所选编码与压缩算法的影响，更直接由数据本身的特征决定。主要影响因素包括以下几个方面：
+
+### 数据有序性
+
+数据的排列顺序对压缩效率至关重要。高序列性的数据（如按时间排序的时间戳、连续递增的ID）包含大量规律模式，使压缩算法能更高效地识别和编码重复信息，从而显著提升压缩比。
+
+### 数据重复度
+
+列中数据的重复值比例是影响压缩率的关键因素。重复值越高的列（如状态码、类别标签），越适合使用字典编码等压缩技术，能获得极佳的压缩效果。反之，随机或唯一性高的数据列，其压缩空间则相对有限。
+
+### 数据的类型
+
+数据的类型也会影响压缩效果。通常，数值类型的数据比字符串类型的数据更容易压缩。
+
+### 列的长度
+
+列中数据的长度也会影响压缩效果。较短的列通常比长列更容易压缩，因为压缩算法在较短数据块上能够更高效地找到重复模式。
+
+### 空值
+
+当列中包含大量空值（NULL）时，压缩效率会得到提升。压缩算法可以将空值统一识别为一种特殊的、极简的模式进行编码，从而有效减少存储空间占用。
+
+## 如何选择压缩算法
+
+选择合适的压缩算法需根据工作负载特性：
+
+- 对于 **高性能实时分析** 场景，推荐使用 LZ4_RAW 或 SNAPPY。
+- 对于 **存储效率优先** 场景，推荐使用 ZSTD。
+- 对于 **冷数据存储** 场景，推荐使用 BROTLI。
diff --git a/zh_CN/sql-reference/statements/use.md b/zh_CN/sql-reference/statements/use.md
index 7310deec..54265c04 100644
--- a/zh_CN/sql-reference/statements/use.md
+++ b/zh_CN/sql-reference/statements/use.md
@@ -1,6 +1,7 @@
# USE 语句详解
## 功能概述
+
USE 语句用于设置当前会话的默认数据库。执行后，后续的所有 SQL 操作（如表查询、数据操作等）将默认在该数据库中进行，无需在每条语句中显式指定数据库名称。目前仅支持在命令行工具 `dlsql` 下使用。 关于 dlsql 工具使用，请查看[命令行工具](../../admin/datalayers-cli.md#datalayers-cli)章节。
## 语法
diff --git a/zh_CN/sql-reference/table-engine/timeseries.md b/zh_CN/sql-reference/table-engine/timeseries.md
index 838409fb..7f56f4bc 100644
--- a/zh_CN/sql-reference/table-engine/timeseries.md
+++ b/zh_CN/sql-reference/table-engine/timeseries.md
@@ -1,6 +1,7 @@
# TimeSeries 时序表引擎指南
## 概述
+
TimeSeries 表引擎是专为时序场景设计的高性能存储与计算引擎，具备高效写入、快速查询和优秀压缩比等特性。适用于车联网、工业物联网、能源监控、APM（应用性能监控）等时序数据密集场景。
## 创建表语法
@@ -31,7 +32,7 @@ PARTITION BY HASH(column_list) PARTITIONS 2
* **BY** 根据指定列进行分区。
* **HASH** 表示按给定列的顺序依次计算 HASH 值，并按 HASH 结果计算分区。当前仅支持 HASH 算法。
* **column_list** 必须是`PRIMARY KEY`中除了`TIMESTAMP KEY`列以外的列的子集或者全集（如果指定了`PRIMARY KEY`）。
- * **PARTITIONS** 表示分区数量，[合理的设置分区](../../development-guide/high-performance-writing.md#partition-数量)数量有利于提升性能。
+ * **PARTITIONS** 表示分区数量，[合理的设置分区](../../development-guide/high-performance-ingestion.md#partition-数量)数量有利于提升性能。
* ENGINE
指定表引擎，未指定时默认为时序引擎 TimeSeries。
* WITH
@@ -116,7 +117,7 @@ ALTER TABLE integers MODIFY OPTIONS ttl='10d', memtable_size='64M';
INSERT INTO table_name (column1,column2,column3,...) VALUES (value1,value2,value3,...);
```
-**示例**
+**示例**：
```SQL
INSERT INTO sensor_info (sn, speed, temperature) VALUES
diff --git a/zh_CN/user-security/audit-logs.md b/zh_CN/user-security/audit-logs.md
new file mode 100644
index 00000000..76084f32
--- /dev/null
+++ b/zh_CN/user-security/audit-logs.md
@@ -0,0 +1,19 @@
+# 审计日志
+
+Datalayers 提供数据库操作审计能力，可记录用户对数据库的查询、修改等操作。审计日志以文件形式存储，每条记录采用 `JSON` 格式，便于后续查询与分析。
+
+## 开启审计日志
+
+审计日志功能默认关闭，需要在配置文件中进行启用和配置，配置方法可参考 [配置审计日志](../admin/configuration-fields/audit-logs.md)
+
+## 查看审计日志
+
+审计日志文件默认存储在以下目录：
+
+``` text
+/var/lib/datalayers/audit
+```
+
+您可以通过查看该目录下的日志文件来获取详细的审计信息。系统会按日期自动分割日志文件，便于管理和查询。
+
+在生产环境中，建议根据实际安全合规要求，合理配置 kinds 和 actions 参数，平衡审计需求与系统性能。
diff --git a/zh_CN/user-security/authentication/rbac.md b/zh_CN/user-security/authentication/rbac.md
index f889b771..a092f47f 100644
--- a/zh_CN/user-security/authentication/rbac.md
+++ b/zh_CN/user-security/authentication/rbac.md
@@ -5,6 +5,7 @@
RBAC 提供完整的身份认证和权限管理体系，支持多用户、多角色的细粒度权限控制。
## 核心特性
+
**角色管理**：定义不同权限级别的角色
**用户分配**：将用户分配到特定角色
**权限控制**：精确控制数据访问和操作权限
@@ -37,46 +38,52 @@ jwt_secret = "871b3c2d706d875e9c6389fb2457d957"
```
## 初始化用户
-安装 Datalayers 后，首次使用 rbac 认证模式启动时，系统默认没有预置管理员账户。您需要手动初始化第一个管理员账户。本文提供两种初始化方法。
+
+安装 Datalayers 后，首次使用 rbac 认证模式启动时，系统默认没有预置管理员账户。需要手动初始化第一个管理员账户。本文提供两种初始化方法。
### 基于 Peer 认证初始化
-Peer 认证是一种基于操作系统进程间通信（IPC）的本地认证机制，它通过 Unix Domain Socket 进行身份验证，仅允许在同一台机器上运行的进程进行访问。
-Datalayers 提供 peer 的认证方式来管理帐号，通过该能力，可对帐号进行初始化、修改密码、查看用户等功能。该能力集成在 dlsql 中。
+Linux 的 Peer 认证（Peer Credentials Authentication）是基于内核级别的进程身份验证机制，通过 `Unix Domain Socket` 通信为连接方提供可靠的身份验证。
-**典型使用场景**
-- **系统初始化**：首次创建管理员账户
-- **密码重置**：忘记密码时的恢复操作
+Datalayers 集成 Peer 认证能力，为数据库账号管理提供安全便捷的解决方案，通过 Peer 认证的连接，将获得系统最高权限。通过该功能，您可以：
+
+- **账号初始化**：安全初始化系统账号对应的数据库访问权限
+- **密码管理**：修改或重置用户密码
+- **用户查询**：查看当前用户信息及权限状态
+- **其他**：任意合法 SQL 语句操作
如需通过此种方式来初始化帐号，需通过以下两步
1. 配置 peer 服务（默认未启用）
```toml
-[server]
-# The unix socket file of peer server.
-# Don't support peer server by default.
-# Default: ""
-peer_addr = "run/datalayers.sock"
+# The configurations of the unix domain socket server.
+[server.uds]
+# The path of the unix domain socket, relative to `base_dir`.
+# DONOT configure this options means do not support uds server by default.
+# Recommend: "run/datalayers.sock"
+path = "run/datalayers.sock"
```
配置好后需重启服务
2. 执行初始化指令
-```shell
-dlsql admin init-root --user admin@% --password public
-# 更多指令可通过 dlsql admin --help 查看
+```shell
+# 以 deb/rpm 安装方式为例
+sudo -u datalayers dlsql
+> CREATE USER IF NOT EXISTS'admin'@'%' identified by 'public'
+Query OK, 0 rows affected. (0.001 sec)
+> GRANT SUPER ON *.* TO 'admin'@'%'
+Query OK, 0 rows affected. (0.001 sec)
```
-通过上术命令即可创建一个用户名为 admin、密码为 public，可从任意 IP 地址登录的管理员账户。
-**注意事项**
-- Peer 认证仅限本地访问，确保操作在服务器本地执行
-- 初始化完成后，可根据实际需求决定是否禁用 peer 服务
-- 如遇到连接问题，请检查 socket 文件路径权限及服务状态
+通过上述命令即可创建一个用户名为 admin、密码为 public，可从任意 IP 地址登录的管理员账户。
### 基于静态认证初始化
+
基于静态认证，通过相应的授权语句进行创建用户来初始化系统用户。
+
- 配置为[静态认证](static.md)，配置好后重启系统
- 参考 `rbac` 中的[用户管理](../rbac/user.md),并创建好帐号
- 创建好后将认证 `server.auth.type` 修改为 `rbac` 并重启系统
@@ -86,7 +93,6 @@ dlsql admin init-root --user admin@% --password public
关于 RBAC 的完整功能说明请参考：[访问控制](../rbac/overview.md)
-
::: tip
-启用 `RBAC` 认证，需将 `server.auth.type` 设置为 `rbac`
+启用 `RBAC` 认证，需将 `server.auth.type` 设置为 `rbac`
:::
diff --git a/zh_CN/user-security/authentication/static.md b/zh_CN/user-security/authentication/static.md
index 3a1fb669..cd6fb3e4 100644
--- a/zh_CN/user-security/authentication/static.md
+++ b/zh_CN/user-security/authentication/static.md
@@ -1,6 +1,7 @@
# 静态认证
## 概述
+
静态认证通过预配置的用户名和密码进行身份验证。此模式仅提供基本的连接认证功能，不具备权限控制能力。认证成功的用户将获得系统最高权限。
## 配置说明
@@ -26,6 +27,7 @@ jwt_secret = "871b3c2d706d875e9c6389fb2457d957"
```
::: tip
-- 静态认证模式下，通过认证的用户将拥有系统完整权限
-- 将配置文件中 ```server.auth.type``` 设置为 `static` 或删除该配置项可启用静态认证
+
+- 静态认证模式下，通过认证的用户将拥有系统最高权限
+- 将配置文件中 `server.auth.type` 设置为 `static` 启用静态认证
:::
diff --git a/zh_CN/user-security/rbac/user.md b/zh_CN/user-security/rbac/user.md
index 97c45217..f292690c 100644
--- a/zh_CN/user-security/rbac/user.md
+++ b/zh_CN/user-security/rbac/user.md
@@ -3,10 +3,12 @@
## 用户账户概述
Datalayers 数据库采用`用户名`@`主机名`的复合账户体系，实现基于网络位置的精细化访问控制。每个用户账户包含两个关键要素
+
- 用户名：标识用户身份
- 主机名：限定允许连接的客户端IP范围
## 用户生命周期管理
+
### 创建用户
**语法**：
@@ -14,7 +16,9 @@ Datalayers 数据库采用`用户名`@`主机名`的复合账户体
```sql
CREATE USER [IF NOT EXISTS] user IDENTIFIED BY 'password';
```
-**说明**
+
+**说明**：
+
- `user`：格式为`'user_name'@'host_name'`，例如 `'alice'@'127.0.0.1'`。
- 主机名 `host_name` 支持使用 `%` 通配符，表示匹配任意网段。例如 `'bob'@'%'` 表示允许用户 bob 从任意 IP 地址连接，`'bob'@'192.168.%'` 表示只允许从 `192.168.*.*` 网段连接
- `password`：账户密码，最长为32位字符。
@@ -28,13 +32,13 @@ CREATE USER 'alice'@'%' IDENTIFIED BY '123456';
用户账户创建以后，可以在客户端启动时传递如下参数登录账户：
```shell
-dlsql --username xxx --password xxx
+dlsql -h 127.0.0.1 --username xxx --password xxx
```
**示例**：
```shell
-dlsql --username alice --password 123456
+dlsql -h 127.0.0.1 --username alice --password 123456
```
### 密码管理
@@ -46,6 +50,7 @@ SET PASSWORD FOR user = 'password';
```
**示例**：
+
```sql
SET PASSWORD FOR 'alice'@'%' = '567890';
```
@@ -59,6 +64,7 @@ DROP USER [IF EXISTS] user;
```
**示例**：
+
```sql
DROP USER 'alice'@'%';
```
diff --git a/zh_CN/user-security/tls.md b/zh_CN/user-security/tls.md
index cf532e74..004d7b02 100644
--- a/zh_CN/user-security/tls.md
+++ b/zh_CN/user-security/tls.md
@@ -1,4 +1,5 @@
# TLS 连接加密配置指南
+
Datalayers 支持 TLS（Transport Layer Security）加密连接，确保客户端与服务器之间的通信安全。本文档介绍如何配置和使用 TLS 加密功能。
## 快速配置
@@ -17,6 +18,7 @@ cert = "/etc/datalayers/certs/server.crt"
```
### 重启服务
+
配置完成后重启 Datalayers 服务使更改生效。
## 通过 dlsql 访问
@@ -27,7 +29,9 @@ cert = "/etc/datalayers/certs/server.crt"
# 机构签发证书（系统自动验证）
dlsql -h 127.0.0.1 -P 8360 -u admin -p public --tls
```
+
### 自签证书
+
```shell
# 自签证书（指定CA证书路径）
dlsql -h 127.0.0.1 -P 8360 -u admin -p public --tls /path/to/ca.crt