docs: add timescaledb_toolkit adaptation guide

CN/modules/ROOT/nav.adoc

@@ -76,6 +76,7 @@
 *** xref:master/ecosystem_components/zhparser.adoc[zhparser]
 *** xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest]
 *** xref:master/ecosystem_components/set_user.adoc[set_user]
+*** xref:master/ecosystem_components/timescaledb_toolkit.adoc[timescaledb_toolkit]
 * 监控运维
 ** xref:master/getting-started/daily_monitoring.adoc[日常监控]
 ** xref:master/getting-started/daily_maintenance.adoc[日常维护]

CN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc

@@ -41,6 +41,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库
 | 28 | xref:master/ecosystem_components/zhparser.adoc[zhparser] | master branch | 用于中文全文搜索的PostgreSQL插件，基于SCWS（即：简易中文分词系统）实现了一个中文解析器 | 搜索引擎、关键字提取
 | 29 | xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest] | 2.58.0 | 可靠的 PostgreSQL 备份和恢复解决方案 | 容灾备份、大库备份、异地/多层容灾
 | 30 | xref:master/ecosystem_components/set_user.adoc[set_user] | REL4_2_0 | PostgreSQL 安全审计扩展，可控角色切换，支持白名单、强制审计、拦截高危操作 | 可控角色切换、权限管理、审计日志
+| 31 | xref:master/ecosystem_components/timescaledb_toolkit.adoc[timescaledb_toolkit] | 1.26.0 | 提供统计分析和时间序列聚合函数 | 可观测性、传感器分析、近似分析
 |====
 
 这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。

CN/modules/ROOT/pages/master/ecosystem_components/timescaledb_toolkit.adoc

@@ -0,0 +1,107 @@
+:sectnums:
+:sectnumlevels: 5
+
+= timescaledb_toolkit
+
+== 概述
+
+TimescaleDB Toolkit 为 PostgreSQL 提供统计分析、近似百分位数、近似去重计数、计数器和时间加权计算等聚合函数。Toolkit 也可运行在普通 PostgreSQL 兼容数据库上，本文示例不强制依赖 TimescaleDB。
+
+本文在 x86_64 Linux 上使用 IvorySQL 5.4（PostgreSQL 18.4）、TimescaleDB Toolkit 1.26.0、Rust 1.98.1 和 `cargo-pgrx` 0.18.1 完成验证。Toolkit Rust 工作区测试全部通过，发布版扩展无需修改源码即可编译，代表性超函数在 PostgreSQL 和 Oracle 兼容会话中均通过验证。
+
+== 准备环境
+
+安装 C 编译工具链、Rust，以及与运行扩展的 IvorySQL 实例完全匹配的开发文件。Toolkit 1.26.0 要求 Rust 1.96 或更高版本。
+
+[source,bash]
+----
+cargo install cargo-pgrx --version 0.18.1 --locked
+cargo pgrx init --pg18 /path-to/ivorysql/bin/pg_config
+----
+
+== 编译安装
+
+[source,bash]
+----
+git clone --branch 1.26.0 --depth 1 \
+  https://github.com/timescale/timescaledb-toolkit.git
+cd timescaledb-toolkit
+
+./tools/build \
+  -pg18 \
+  -pgconfig /path-to/ivorysql/bin/pg_config \
+  -profile release \
+  install
+----
+
+部署前运行上游测试：
+
+[source,bash]
+----
+cargo test --workspace --exclude timescaledb_toolkit
+----
+
+== 创建扩展
+
+通过 IvorySQL PostgreSQL 兼容端口连接，并在每个目标数据库中创建扩展：
+
+[source,sql]
+----
+CREATE EXTENSION timescaledb_toolkit;
+SELECT extversion
+FROM pg_extension
+WHERE extname = 'timescaledb_toolkit';
+----
+
+== 功能验证
+
+[source,sql]
+----
+CREATE TABLE metrics (
+    ts timestamptz NOT NULL,
+    device text NOT NULL,
+    value double precision NOT NULL
+);
+
+INSERT INTO metrics VALUES
+  ('2026-01-01 00:00:00+00', 'sensor-a', 10),
+  ('2026-01-01 00:01:00+00', 'sensor-a', 20),
+  ('2026-01-01 00:02:00+00', 'sensor-b', 30),
+  ('2026-01-01 00:03:00+00', 'sensor-c', 40);
+
+SELECT round(average(stats_agg(value))::numeric, 2) AS average_value,
+       round(approx_percentile(0.5, percentile_agg(value))::numeric, 2)
+         AS approximate_median
+FROM metrics;
+
+SELECT distinct_count(hyperloglog(32, device)) AS approximate_devices
+FROM metrics;
+
+SELECT round(delta(counter_agg(ts, value))::numeric, 2) AS counter_delta,
+       round(average(time_weight('Linear', ts, value))::numeric, 2)
+         AS time_weighted_average
+FROM metrics;
+----
+
+验证结果分别为：平均值 `25.00`、近似中位数 `29.99`、设备数 3、计数器增量 `30.00`、时间加权平均值 `25.00`。
+
+== Oracle 兼容模式
+
+通过 PostgreSQL 兼容端口创建扩展后，可在 Oracle 兼容会话中调用已验证的函数：
+
+[source,sql]
+----
+SET ivorysql.compatible_mode=oracle;
+SELECT 1 FROM dual;
+
+SELECT round(average(stats_agg(value))::numeric, 2) AS oracle_average,
+       distinct_count(hyperloglog(32, device)) AS oracle_devices
+FROM metrics;
+----
+
+[IMPORTANT]
+====
+在 IvorySQL 5.4 中，直接通过 Oracle 兼容连接执行 `CREATE EXTENSION timescaledb_toolkit` 会失败，因为上游安装脚本使用 PostgreSQL 语法。请先通过 PostgreSQL 兼容端口创建扩展。该限制不影响切换到 Oracle 兼容模式后调用本文验证的 Toolkit 函数。
+====
+
+Toolkit 本身不提供 hypertable 或后台任务；如需这些功能，应另行安装 TimescaleDB。完整函数说明请参阅 https://github.com/timescale/timescaledb-toolkit[上游项目]。

EN/modules/ROOT/nav.adoc

@@ -76,6 +76,7 @@
 *** xref:master/ecosystem_components/zhparser_en.adoc[zhparser]
 *** xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest]
 *** xref:master/ecosystem_components/set_user.adoc[set_user]
+*** xref:master/ecosystem_components/timescaledb_toolkit.adoc[timescaledb_toolkit]
 * Monitor and O&M
 ** xref:master/getting-started/daily_monitoring.adoc[Monitoring]
 ** xref:master/getting-started/daily_maintenance.adoc[Maintenance]

EN/modules/ROOT/pages/master/ecosystem_components/ecosystem_overview.adoc

@@ -42,6 +42,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o
 |*28*| xref:master/ecosystem_components/zhparser_en.adoc[zhparser] | master branch | PostgreSQL extension for full-text search of Chinese language (Mandarin Chinese). It implements a Chinese language parser base on the | Search engine、keyword extraction
 |*29*| xref:master/ecosystem_components/pgbackrest.adoc[pgBackRest] | 2.58.0 | pgBackRest is a reliable backup and restore solution for PostgreSQL that seamlessly scales up to the largest databases and workloads | Disaster recovery backup, large database backup, off-site/multi-tier disaster recovery
 | *30* | xref:master/ecosystem_components/set_user.adoc[set_user] | REL4_2_0 | PostgreSQL security auditing extension with controlled role switching, supporting allowlists, enforced auditing, and blocking of high-risk operations | Controlled role switching, privilege management, audit logging
+| *31* | xref:master/ecosystem_components/timescaledb_toolkit.adoc[timescaledb_toolkit] | 1.26.0 | Provides statistical and time-series aggregate functions | Observability, sensor analytics, approximate analytics
 |====
 
 These plugins have all been tested and adapted by the IvorySQL team to ensure stable operation in the IvorySQL environment. Users can select appropriate plugins based on business needs to further enhance the capabilities and flexibility of the database system.

EN/modules/ROOT/pages/master/ecosystem_components/timescaledb_toolkit.adoc

@@ -0,0 +1,107 @@
+:sectnums:
+:sectnumlevels: 5
+
+= timescaledb_toolkit
+
+== Overview
+
+TimescaleDB Toolkit provides PostgreSQL aggregate functions for statistical analysis, approximate percentiles, distinct counting, counters, and time-weighted calculations. Toolkit can run on plain PostgreSQL-compatible databases; TimescaleDB is optional for the examples in this guide.
+
+This guide was validated on x86_64 Linux with IvorySQL 5.4 (PostgreSQL 18.4), TimescaleDB Toolkit 1.26.0, Rust 1.98.1, and `cargo-pgrx` 0.18.1. The Toolkit Rust workspace tests passed, the release extension built without source changes, and representative hyperfunctions passed in PostgreSQL and Oracle-compatible sessions.
+
+== Prerequisites
+
+Install the C build toolchain, Rust, and the development files for the same IvorySQL installation that will load the extension. Toolkit 1.26.0 requires Rust 1.96 or later.
+
+[source,bash]
+----
+cargo install cargo-pgrx --version 0.18.1 --locked
+cargo pgrx init --pg18 /path-to/ivorysql/bin/pg_config
+----
+
+== Build and install
+
+[source,bash]
+----
+git clone --branch 1.26.0 --depth 1 \
+  https://github.com/timescale/timescaledb-toolkit.git
+cd timescaledb-toolkit
+
+./tools/build \
+  -pg18 \
+  -pgconfig /path-to/ivorysql/bin/pg_config \
+  -profile release \
+  install
+----
+
+Run the upstream tests before deployment:
+
+[source,bash]
+----
+cargo test --workspace --exclude timescaledb_toolkit
+----
+
+== Create the extension
+
+Connect through the IvorySQL PostgreSQL-compatible port and create the extension in each target database:
+
+[source,sql]
+----
+CREATE EXTENSION timescaledb_toolkit;
+SELECT extversion
+FROM pg_extension
+WHERE extname = 'timescaledb_toolkit';
+----
+
+== Functional validation
+
+[source,sql]
+----
+CREATE TABLE metrics (
+    ts timestamptz NOT NULL,
+    device text NOT NULL,
+    value double precision NOT NULL
+);
+
+INSERT INTO metrics VALUES
+  ('2026-01-01 00:00:00+00', 'sensor-a', 10),
+  ('2026-01-01 00:01:00+00', 'sensor-a', 20),
+  ('2026-01-01 00:02:00+00', 'sensor-b', 30),
+  ('2026-01-01 00:03:00+00', 'sensor-c', 40);
+
+SELECT round(average(stats_agg(value))::numeric, 2) AS average_value,
+       round(approx_percentile(0.5, percentile_agg(value))::numeric, 2)
+         AS approximate_median
+FROM metrics;
+
+SELECT distinct_count(hyperloglog(32, device)) AS approximate_devices
+FROM metrics;
+
+SELECT round(delta(counter_agg(ts, value))::numeric, 2) AS counter_delta,
+       round(average(time_weight('Linear', ts, value))::numeric, 2)
+         AS time_weighted_average
+FROM metrics;
+----
+
+The validated results are an average of `25.00`, an approximate median of `29.99`, three distinct devices, a counter delta of `30.00`, and a time-weighted average of `25.00`.
+
+== Oracle-compatible mode
+
+After creating the extension through the PostgreSQL-compatible port, the tested functions can be used in an Oracle-compatible session:
+
+[source,sql]
+----
+SET ivorysql.compatible_mode=oracle;
+SELECT 1 FROM dual;
+
+SELECT round(average(stats_agg(value))::numeric, 2) AS oracle_average,
+       distinct_count(hyperloglog(32, device)) AS oracle_devices
+FROM metrics;
+----
+
+[IMPORTANT]
+====
+With IvorySQL 5.4, running `CREATE EXTENSION timescaledb_toolkit` directly through an Oracle-compatible connection fails because the upstream installation script uses PostgreSQL syntax. Create the extension through the PostgreSQL-compatible port first. This limitation does not prevent the validated Toolkit functions from being called after switching a session to Oracle-compatible mode.
+====
+
+Toolkit does not provide hypertables or background jobs. Install TimescaleDB separately if those features are required. See https://github.com/timescale/timescaledb-toolkit[the upstream project] for the complete function reference.