From 2f89264e93acaa942b52c5d920a73928fe2658a5 Mon Sep 17 00:00:00 2001 From: niebayes Date: Sun, 19 Jul 2026 17:45:17 +0000 Subject: [PATCH 1/2] update docs --- zh_CN/admin/backup-restore.md | 12 ++++++++++++ .../query-optimization/last-cache-optimization.md | 6 ++++++ 2 files changed, 18 insertions(+) diff --git a/zh_CN/admin/backup-restore.md b/zh_CN/admin/backup-restore.md index b2b19cf4..e077fc69 100644 --- a/zh_CN/admin/backup-restore.md +++ b/zh_CN/admin/backup-restore.md @@ -32,6 +32,18 @@ description: "Datalayers 数据备份与恢复指南：介绍 dldump 的核心 | --tls | - | 通过 TLS 加密方式与数据库进行交互。自签证书则需指定 root ca，如：--tls /etc/datalayers/datalayers.crt | | --help | - | show this help, then exit | +### 参数说明 + +#### `-d` / `--database` 参数 + +- **导出时**：`-d` 用于选择备份**指定的数据库**。如果不指定，默认备份所有数据库。 +- **导入时**：`-d` 用于从备份目录中选择**哪个数据库**进行导入。**注意：`-d` 不是用来指定将数据导入到目标数据库的名称**。即导入时的目标数据库名就是备份时的原数据库名，不可通过 `-d` 更改。 + +#### `-t` / `--table` 参数 + +- **导出时**：`-t` 用于选择备份指定数据库下的**某张表**。指定 `-t` 时必须同时指定 `-d`。 +- **导入时**：`-t` 用于从备份目录中选择**哪张表**进行导入。**注意：`-t` 不是用来指定将数据导入到目标表的名称**。即导入时的目标表名就是备份时的原表名，不可通过 `-t` 更改。 + ## 备份与恢复 以下通过一个示例来介绍 **dldump** 工具的使用。这个示例首先为单机版 Datalayers 写入一些数据，然后使用 **dldump** 将数据导出到备份目录；再创建一个新的 Datalayers 实例，从备份目录加载数据并写入到新的 Datalayers 实例；最后使用 **dlsql** 工具查询新的 Datalayers 实例，以验证成功执行了备份与恢复。 diff --git a/zh_CN/development-guide/query-optimization/last-cache-optimization.md b/zh_CN/development-guide/query-optimization/last-cache-optimization.md index d9afc9da..a618ff80 100644 --- a/zh_CN/development-guide/query-optimization/last-cache-optimization.md +++ b/zh_CN/development-guide/query-optimization/last-cache-optimization.md @@ -8,6 +8,12 @@ description: "介绍 Datalayers LAST CACHE 的适用场景、配置方式和典 在时序数据场景中，经常需要查询特定设备或点位的最新数据记录，用于实时监控和状态追踪。Datalayers 提供 LAST CACHE 功能，用于缓存最新记录，从而显著提升“查最新值”类查询性能。 +### 热数据与冷数据 + +用户写入的数据会首先进入 MemTable，因此**热数据（最近写入的数据）**驻留在 MemTable 中。当查询某个主键的最新值时，如果该 PK 的数据仍在 MemTable 中，Datalayers 可以直接从内存中获取结果，完全避免或大量剪枝需要扫描的 SST 文件，从而大幅提升最新值查询性能。 + +对于**冷数据**——即很久没有新写入的主键，其数据可能已经下沉到 SST 文件中。此时，如果直接扫描 SST 文件，I/O 开销会很大。LAST CACHE 正是为此类冷数据查询场景设计的缓存：它将每个主键的最新记录缓存在内存中（只要查询过该主键、或该主键的最新数据经过了 flush），使得查询冷数据的最新值时，无需扫描底层 SST 文件，直接从缓存返回结果，显著降低查询延迟。 + ## 功能特性 - **高效内存缓存**：专为最新数据查询优化 From 57b9d2f38827508aa3f33ec69b7bbcc7c8a188b1 Mon Sep 17 00:00:00 2001 From: YinBo Date: Mon, 20 Jul 2026 15:07:47 +0800 Subject: [PATCH 2/2] chore --- zh_CN/admin/backup-restore.md | 38 +++++++------------ .../last-cache-optimization.md | 8 ++-- 2 files changed, 18 insertions(+), 28 deletions(-) diff --git a/zh_CN/admin/backup-restore.md b/zh_CN/admin/backup-restore.md index e077fc69..8bdb4712 100644 --- a/zh_CN/admin/backup-restore.md +++ b/zh_CN/admin/backup-restore.md @@ -6,13 +6,13 @@ description: "Datalayers 数据备份与恢复指南：介绍 dldump 的核心 ## 概述 -数据库备份和恢复用于保护数据安全、防止数据丢失或损坏。通过定期备份，可在系统故障、硬件损坏或人为错误时，将数据库恢复到最近可用状态，确保业务连续性与数据完整性。本文主要介绍数据备份与恢复能力。 +数据库备份与恢复用于保护数据安全，防止数据丢失或损坏。通过定期备份，可以在系统故障、硬件损坏或人为误操作后，将数据库恢复到最近的可用状态，确保业务连续性和数据完整性。本文介绍如何使用 Datalayers 提供的工具完成数据备份与恢复。 `dldump` 是 Datalayers 提供的数据导出与导入工具，适合用于单库、单表或全库级别的备份恢复操作。 ## 工具使用说明 -`dldump` 工具提供了丰富的选项以供配置，您可以通过执行 `dldump --help` 以查看 `dldump` 的所有子命令和选项。此处对一些重要的选项进行说明： +`dldump` 提供了丰富的命令行选项。您可以执行 `dldump --help` 查看全部子命令和选项。下面对几个常用参数进行说明： | 参数 | 简写 | 描述 | | --- | --- | --- | @@ -24,29 +24,17 @@ description: "Datalayers 数据备份与恢复指南：介绍 dldump 的核心 | --input | -i | 指定恢复时数据的加载路径。如果指定的目录为空，则会中止恢复操作 | | --meta | - | 指定备份时是否要包含元信息（如：建库和建表语句），默认包含元信息。如果不备份元信息，您可以传入 --meta false | | --data | - | 指定备份时是否要包含表数据，默认包含表数据。如果要求不备份表数据，您可以传入 --data false | -| --database | -d | 指定备份或恢复的数据库。如果不显式设定该选项，则默认转储所有数据库 | -| --table | -t | 指定备份或恢复的表。如果指定了 table，则必须指定 database。如果不显式设定该选项，则默认备份 database 下所有表 | +| --database | -d | 导出时：`-d` 用于选择备份 **指定的数据库** 。如果不指定，默认备份所有数据库。
导入时：`-d` 用于从备份目录中选择 **哪个数据库** 进行导入。**注意：`-d` 不是用来指定将数据导入到目标数据库的名称**。即导入时的目标数据库名就是备份时的原数据库名，不可通过 `-d` 更改。 | +| --table | -t | 导出时：`-t` 用于选择备份指定数据库下的 **某张表** 。指定 `-t` 时必须同时指定 `-d`。
导入时：`-t` 用于从备份目录中选择 **哪张表** 进行导入。**注意：`-t` 不是用来指定将数据导入到目标表的名称**。即导入时的目标表名就是备份时的原表名，不可通过 `-t` 更改。 | | --max-file-size | -s | 指定一个数据文件大小的最大值，默认为 8GiB。只支持整型作为合法的输入。单位为：GiB | | --start | - | 指定一个时间戳，时间戳大于或等于 start 的表数据才会被备份。合法的日期格式和整型均认为是合法的时间戳 | | --end | - | 指定一个时间戳，时间戳小于或等于 end 的表数据才会被备份。合法的日期格式和整型均认为是合法的时间戳 | | --tls | - | 通过 TLS 加密方式与数据库进行交互。自签证书则需指定 root ca，如：--tls /etc/datalayers/datalayers.crt | | --help | - | show this help, then exit | -### 参数说明 - -#### `-d` / `--database` 参数 - -- **导出时**：`-d` 用于选择备份**指定的数据库**。如果不指定，默认备份所有数据库。 -- **导入时**：`-d` 用于从备份目录中选择**哪个数据库**进行导入。**注意：`-d` 不是用来指定将数据导入到目标数据库的名称**。即导入时的目标数据库名就是备份时的原数据库名，不可通过 `-d` 更改。 - -#### `-t` / `--table` 参数 - -- **导出时**：`-t` 用于选择备份指定数据库下的**某张表**。指定 `-t` 时必须同时指定 `-d`。 -- **导入时**：`-t` 用于从备份目录中选择**哪张表**进行导入。**注意：`-t` 不是用来指定将数据导入到目标表的名称**。即导入时的目标表名就是备份时的原表名，不可通过 `-t` 更改。 - ## 备份与恢复 -以下通过一个示例来介绍 **dldump** 工具的使用。这个示例首先为单机版 Datalayers 写入一些数据，然后使用 **dldump** 将数据导出到备份目录；再创建一个新的 Datalayers 实例，从备份目录加载数据并写入到新的 Datalayers 实例；最后使用 **dlsql** 工具查询新的 Datalayers 实例，以验证成功执行了备份与恢复。 +下面通过一个示例介绍 `dldump` 的使用方法。示例中会先向单机版 Datalayers 写入一些数据，再使用 `dldump` 将数据导出到备份目录；随后创建一个新的 Datalayers 实例，并从备份目录恢复数据；最后使用 `dlsql` 查询新实例中的数据，以验证备份与恢复是否成功。 为方便叙述，本文将被备份的 Datalayers 实例称为 1 号节点，将被恢复的 Datalayers 实例称为 2 号节点。 @@ -97,9 +85,9 @@ Query OK, 10 rows affected. (0.002 sec) dldump -h localhost -P 8360 -d test -o /tmp/datalayers/backup ``` -该命令将 1 号节点的数据导出到指定的 `/tmp/datalayers/backup` 目录。 +该命令会将 1 号节点的数据导出到指定的 `/tmp/datalayers/backup` 目录。 -备份完成后，`/tmp/datalayers/backup` 目录将会有如下的层次结构： +备份完成后，`/tmp/datalayers/backup` 目录结构如下： ```text backup @@ -108,9 +96,9 @@ backup - device_0.parquet ``` -根据 `dldump` 工具的设计，每个数据库会有一个独立的备份目录，这个目录会以数据库的名称命名。例如，`test` 数据库对应一个同名的 `test` 目录。数据库目录下存在一个 `create.sql` 文件，它里面包含了这个数据库的建库语句和每个表的建表语句。数据库目录下的其他文件则为表数据文件。表数据文件的命名规则是 `_.parquet`，`table_name` 为表名，如示例中的 `device` 表；`sequence` 表示该数据文件为这张表的第几个数据文件，`dldump` 会根据数据导出时的顺序对数据文件进行排序。 +`dldump` 会为每个数据库创建独立的备份目录，并使用数据库名称作为目录名。例如，`test` 数据库对应同名目录 `test`。该目录中的 `create.sql` 文件包含建库语句以及各表的建表语句，其他文件则为表数据文件。表数据文件的命名规则为 `_.parquet`：其中 `table_name` 表示表名，如示例中的 `device`；`sequence` 表示该文件是该表导出的第几个数据文件，`dldump` 会按导出顺序为其编号。 -> **注**：如果您开启了文件系统的“显示隐藏文件和目录”的选项，那么您还会在 `test` 目录下发现 `.schema` 文件。为了保证数据恢复时的 schema 与备份时的一致，`dldump` 在备份时会将所有表的 schema 统一编码到 `.schema` 文件中，在恢复时再从中解码出 schema。 +> **注**：如果您开启了文件系统的“显示隐藏文件和目录”选项，还会在 `test` 目录下看到 `.schema` 文件。为保证恢复时的 schema 与备份时保持一致，`dldump` 会在备份阶段将所有表的 schema 统一编码到 `.schema` 文件中，并在恢复阶段从中解码。 ### 数据恢复 @@ -120,19 +108,21 @@ backup datalayers standalone -c datalayers.toml ``` -请注意，您需要对配置文件 `datalayers.toml` 做必要的修改。一方面，2 号节点使用的数据目录 `storage.local.path` 必须与 1 号节点不同，否则会导致恢复失败。另一方面，如果 1 号节点没有关闭，那么您需要改动 2 号节点使用的 SQL 服务端口 `server.port` 和 HTTP 服务端口 `server.http_port`，以确保其能够成功启动。 +请注意，您需要对配置文件 `datalayers.toml` 做必要调整。一方面，2 号节点使用的数据目录 `storage.local.path` 必须与 1 号节点不同，否则会导致恢复失败。另一方面，如果 1 号节点仍在运行，则还需要修改 2 号节点的 SQL 服务端口 `server.port` 和 HTTP 服务端口 `server.http_port`，以确保其能够成功启动。 执行数据恢复： +以下命令假设 2 号节点的 SQL 服务端口为 `8360`。如果您在前一步调整了端口，请将命令中的 `-P` 参数替换为实际端口。 + ``` shell dldump -h localhost -P 8360 -i /tmp/datalayers/backup ``` -该命令将从 `/tmp/datalayers/backup` 路径加载备份文件，并将数据写入到 2 号节点中。待该命令执行完成后，便完成了数据恢复。 +该命令会从 `/tmp/datalayers/backup` 路径加载备份文件，并将数据写入 2 号节点。命令执行完成后，数据恢复即完成。 ### 验证数据 -使用 `dlsql` 工具对 2 号节点执行查询，以验证恢复数据的完整性。 +使用 `dlsql` 对 2 号节点执行查询，以验证恢复结果的完整性。 验证 `test` 数据库被成功恢复： diff --git a/zh_CN/development-guide/query-optimization/last-cache-optimization.md b/zh_CN/development-guide/query-optimization/last-cache-optimization.md index a618ff80..c50ed5a0 100644 --- a/zh_CN/development-guide/query-optimization/last-cache-optimization.md +++ b/zh_CN/development-guide/query-optimization/last-cache-optimization.md @@ -10,9 +10,9 @@ description: "介绍 Datalayers LAST CACHE 的适用场景、配置方式和典 ### 热数据与冷数据 -用户写入的数据会首先进入 MemTable，因此**热数据（最近写入的数据）**驻留在 MemTable 中。当查询某个主键的最新值时，如果该 PK 的数据仍在 MemTable 中，Datalayers 可以直接从内存中获取结果，完全避免或大量剪枝需要扫描的 SST 文件，从而大幅提升最新值查询性能。 +写入的数据会先进入 MemTable，因此最近写入的数据通常属于 **热数据**，并驻留在 MemTable 中。当查询某个主键的最新值时，如果该主键的最新记录仍在 MemTable 中，Datalayers 可以直接从内存返回结果，无需或仅需极少扫描 SST 文件，因此查询性能通常较高。 -对于**冷数据**——即很久没有新写入的主键，其数据可能已经下沉到 SST 文件中。此时，如果直接扫描 SST 文件，I/O 开销会很大。LAST CACHE 正是为此类冷数据查询场景设计的缓存：它将每个主键的最新记录缓存在内存中（只要查询过该主键、或该主键的最新数据经过了 flush），使得查询冷数据的最新值时，无需扫描底层 SST 文件，直接从缓存返回结果，显著降低查询延迟。 +相较之下，长时间没有新写入的主键可视为 **冷数据**，其最新记录往往已经刷写到 SST 文件中。查询这类主键的最新值时，如果直接访问底层 SST 文件，I/O 开销会较大。LAST CACHE 正是为这类场景设计的缓存：它将每个主键的最新记录保存在内存中。在该主键被查询过，或其最新记录完成 flush 后，后续查询即可优先命中缓存，避免扫描 SST 文件，从而显著降低查询延迟。 ## 功能特性 @@ -21,7 +21,7 @@ description: "介绍 Datalayers LAST CACHE 的适用场景、配置方式和典 ## 配置步骤 -如需启用 LAST CACHE，需通过以下两个步骤 +如需启用 LAST CACHE，需要完成以下两个步骤： ### 配置全局缓存大小 @@ -58,7 +58,7 @@ WITH ( ## 优化的查询场景 -通过上述配置，即可对下面 SQL 加速查询： +完成上述配置后，即可加速以下 SQL 查询： - select * from t where sid = 1 order by ts desc limit 1 - select last_value(value order by ts) from t where sid = 1