Merge remote-tracking branch 'origin/3.0' into merge/mainto3.0

taosdata · Nov 5, 2024 · 5701340 · 5701340
2 parents fde95b1 + cca24b7
commit 5701340
Show file tree

Hide file tree

Showing 108 changed files with 6,780 additions and 6,206 deletions.
diff --git a/.github/workflows/taoskeeper-ci.yml b/.github/workflows/taoskeeper-ci.yml
@@ -28,7 +28,7 @@ jobs:
         run: |
           mkdir debug
           cd debug
-          cmake .. -DBUILD_HTTP=false -DBUILD_JDBC=false -DBUILD_TOOLS=false -DBUILD_TEST=off -DBUILD_KEEPER=true
+          cmake .. -DBUILD_HTTP=false -DBUILD_JDBC=false -DBUILD_TOOLS=false -DBUILD_TEST=off -DBUILD_KEEPER=true -DBUILD_DEPENDENCY_TESTS=false
           make -j 4
           sudo make install
           which taosd
@@ -48,7 +48,7 @@ jobs:
         working-directory: tools/keeper
         run: |
           go mod tidy
-          go test -v -coverpkg=./... -coverprofile=coverage.out ./...
+          sudo go test -v -ldflags="-X 'github.com/taosdata/taoskeeper/version.IsEnterprise=true'" -coverpkg=./... -coverprofile=coverage.out ./...
           go tool cover -func=coverage.out
 
       - name: Clean up

diff --git a/contrib/CMakeLists.txt b/contrib/CMakeLists.txt
@@ -261,11 +261,19 @@ if(${TD_DARWIN})
 endif(${TD_DARWIN})
 
 add_subdirectory(zlib EXCLUDE_FROM_ALL)
+
+if(${TD_DARWIN})
+    target_compile_options(zlibstatic PRIVATE -Wno-error=deprecated-non-prototype)
+endif()
 target_include_directories(
     zlibstatic
     PUBLIC ${CMAKE_CURRENT_BINARY_DIR}/zlib
     PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/zlib
 )
+
+if(${TD_DARWIN})
+    target_compile_options(zlib PRIVATE -Wno-error=deprecated-non-prototype)
+endif()
 target_include_directories(
     zlib
     PUBLIC ${CMAKE_CURRENT_BINARY_DIR}/zlib

diff --git a/docs/examples/JDBC/taosdemo/readme.md b/docs/examples/JDBC/taosdemo/readme.md
@@ -7,8 +7,4 @@ java -jar target/taosdemo-2.0.1-jar-with-dependencies.jar -host <hostname> -data
 java -jar target/taosdemo-2.0.1-jar-with-dependencies.jar -host <hostname> -database <db name> -doCreateTable false -superTableSQL "create table weather(ts timestamp, f1 int) tags(t1 nchar(4))" -numOfTables 1000 -numOfRowsPerTable 100000000 -numOfThreadsForInsert 10 -numOfTablesPerSQL 10 -numOfValuesPerSQL 100
 ```
 
-如果发生错误 Exception in thread "main" java.lang.UnsatisfiedLinkError: no taos in java.library.path
-请检查是否安装 TDengine 客户端安装包或编译 TDengine 安装。如果确定已经安装过还出现这个错误，可以在命令行 java 后加 -Djava.library.path=/usr/lib 来指定寻找共享库的路径。
-
-
 If you encounter the error Exception in thread "main" `java.lang.UnsatisfiedLinkError: no taos in java.library.path`, please check whether the TDengine client package is installed or TDengine is compiled and installed. If you are sure it is installed and still encounter this error, you can add `-Djava.library.path=/usr/lib` after the `java` command to specify the path to the shared library.
diff --git a/docs/examples/node/package.json b/docs/examples/node/package.json
@@ -4,6 +4,6 @@
   "main": "index.js",
   "license": "MIT",
   "dependencies": {
-    "@tdengine/websocket": "^3.1.0"
+    "@tdengine/websocket": "^3.1.1"
   }
 }
diff --git a/docs/examples/node/websocketexample/sql_example.js b/docs/examples/node/websocketexample/sql_example.js
@@ -3,7 +3,6 @@ const taos = require("@tdengine/websocket");
 
 let dsn = 'ws://localhost:6041';
 async function createConnect() {
-
     try {
         let conf = new taos.WSConfig(dsn);
         conf.setUser('root');

diff --git a/docs/examples/node/websocketexample/tmq_seek_example.js b/docs/examples/node/websocketexample/tmq_seek_example.js
@@ -10,7 +10,6 @@ const groupId = "group1";
 const clientId = "client1";
 
 async function createConsumer() {
-
     let groupId = "group1";
     let clientId = "client1";
     let configMap = new Map([

diff --git a/docs/zh/06-advanced/06-data-analysis/01-arima.md b/docs/zh/06-advanced/06-data-analysis/01-arima.md
@@ -3,8 +3,52 @@ title: "ARIMA"
 sidebar_label: "ARIMA"
 ---
 
-本节讲述如何 ARIMA 算法的使用方法。
+本节讲述 ARIMA 算法模型的使用方法。
 
 ## 功能概述
 
-……
+ARIMA 即自回归移动平均模型(Autoregressive Integrated Moving Average, ARIMA)，也记作 ARIMA(p,d,q)，是统计模型中最常见的一种用来进行时间序列预测的模型。
+ARIMA模型是一种自回归模型，只需要自变量即可预测后续的值。ARIMA模型要求时序数据是**平稳**，或经过差分处理后平稳，如果是不平稳的数据，**无法**获得正确的结果。
+
+>平稳的时间序列：其性质不随观测时间的变化而变化。具有趋势或季节性的时间序列不是平稳时间序列——趋势和季节性使得时间序列在不同时段呈现不同性质。
+
+以下参数可以动态输入控制预测过程中生成 合适的  ARIMA 的模型。
+
+- p= 自回归模型阶数
+- d= 差分阶数
+- q= 移动平均模型阶数
+
+
+### 参数
+分析平台中使用自动化的 ARIMA 模型进行计算，因此每次计算的时候会根据输入的数据自动拟合最合适的模型，然后根据该模型进行预测输出结果。
+|参数名称|说明|必填项|
+|---|---|---|
+|period|输入时间序列数据每个周期包含的数据点个数。如果不设置该参数或则该参数设置为 0， 将使用非季节性/周期性的 ARIMA 模型预测。|选填|
+|start_p|	自回归模型阶数的 起始值，0 开始的整数，不推荐大于 10	|选填|
+|max_p|	自回归模型阶数的 结束值，0 开始的整数，不推荐大于 10	|选填|
+|start_q|	移动平均模型阶数的起始值， 0 开始的整数，不推荐大于 10	|选填|
+|max_q|	移动平均模型阶数的结束值， 0 开始的整数，不推荐大于 10	|选填|
+|d|	差分阶数|选填|
+
+`start_p`、`max_p` `start_q` `max_q` 四个参数约束了模型在多大的范围内去搜寻合适的最优解。相同输入数据的条件下，参数范围越大，消耗的资源越多，系统响应的时间越长。
+
+### 示例及结果
+针对 i32 列进行数据预测，输入列 i32 每 10 个点是一个周期，start_p 起始是 1， 最大拟合是 5，start_q是1，最大值是5，预测结果中返回 95% 置信区间范围边界。
+```
+FORECAST(i32, "algo=arima,alpha=95,period=10, start_p=1, max_p=5, start_q=1, max_q=5")
+```
+
+```json5
+{
+"rows": fc_rows,  // 预测结果的行数
+"period": period, // 返回结果的周期性，同输入
+"alpha": alpha,   // 返回结果的置信区间，同输入
+"algo": "arima",  // 返回结果使用的算法
+"mse":mse,        // 拟合输入时序数据时候生成模型的最小均方误差(MSE)
+"res": res        // 列模式的结果
+}
+```
+
+### 参考文献
+- https://en.wikipedia.org/wiki/Autoregressive_moving-average_model
+- https://baike.baidu.com/item/%E8%87%AA%E5%9B%9E%E5%BD%92%E6%BB%91%E5%8A%A8%E5%B9%B3%E5%9D%87%E6%A8%A1%E5%9E%8B/5023931?fromtitle=ARMA%E6%A8%A1%E5%9E%8B&fromid=8048415
diff --git a/docs/zh/06-advanced/06-data-analysis/02-holtwinters.md b/docs/zh/06-advanced/06-data-analysis/02-holtwinters.md
@@ -0,0 +1,43 @@
+---
+title: "HoltWinters"
+sidebar_label: "HoltWinters"
+---
+
+本节讲述 HoltWinters 算法模型的使用方法。
+
+## 功能概述
+HoltWinters模型又称为多次指数平滑模型（EMA）。对含有线性趋势和周期波动的非平稳序列适用，利用指数平滑法让模型参数不断适应非平稳序列的变化，并对未来趋势进行**短期**预测。
+HoltWinters有两种不同的季节性组成部分，当季节变化在该时间序列中大致保持不变时，通常选择**加法模型**；而当季节变化与时间序列的水平成比例变化时，通常选择**乘法模型**。
+该模型对于返回数据也不提供计算的置信区间范围结果。在 95% 置信区间的上下界结果与预测结果相同。
+
+
+### 参数
+
+分析平台中使用自动化的 ARIMA 模型进行计算，因此每次计算的时候会根据输入的数据自动拟合最合适的模型，然后根据该模型进行预测输出结果。
+|参数名称|说明|必填项|
+|---|---|---|
+|period|	输入时间序列数据每个周期包含的数据点个数。如果不设置该参数或则该参数设置为 0， 将使用一次（简单）指数平滑方式进行数据拟合，并据此进行未来数据的预测|选填|
+|trend|	趋势模型使用加法模型还是乘法模型|选填|
+|seasonal|	季节性采用加法模型还是乘法模型|选填|
+
+参数 `trend` 和 `seasonal`的均可以选择 `add` （加法模型）或 `mul`（乘法模型）。
+
+### 示例及结果
+针对 i32 列进行数据预测，输入列 i32 每 10 个点是一个周期，趋势采用乘法模型，季节采用乘法模型
+```
+FORECAST(i32, "algo=holtwinters,period=10,trend=mul,seasonal=mul")
+```
+
+```json5
+{
+"rows": rows,  //  结果的行数
+"period": period,  // 返回结果的周期性， 该结果与输入的周期性相同，如果没有周期性，该值为 0
+"algo": 'holtwinters'  // 返回结果使用的计算模型
+"mse":mse,   // 最小均方误差（minmum square error）
+"res": res   // 具体的结果，按照列形式返回的结果。一般意义上包含了 两列[timestamp][fc_results]。
+}
+```
+
+### 参考文献
+- https://en.wikipedia.org/wiki/Exponential_smoothing
+- https://orangematter.solarwinds.com/2019/12/15/holt-winters-forecasting-simplified/
diff --git a/docs/zh/06-advanced/06-data-analysis/03-anomaly-detection.md b/docs/zh/06-advanced/06-data-analysis/03-anomaly-detection.md
@@ -0,0 +1,46 @@
+---
+title: "Anomaly-detection"
+sidebar_label: "Anomaly-detection"
+---
+
+本节讲述 异常检测 算法模型的使用方法。
+
+## 概述
+分析平台提供了 6 种异常检查模型，6 种异常检查模型分为 3 个类别，分别属于基于统计的异常检测模型、基于数据密度的检测模型、基于深度学习的异常检测模型。在不指定异常检测使用的方法的情况下，默认调用 iqr 的方法进行计算。
+
+
+### 统计学异常检测方法
+
+- k-sigma<sup>[1]</sup>: 即 ***68–95–99.7 rule*** 。***k***值默认为3， 即序列均值的 3 倍标准差范围为边界，超过边界的是异常值。KSigma 要求数据整体上服从正态分布，如果一个点偏离均值K倍标准差，则该点被视为异常点.
+
+|参数名称|说明|是否必选|默认值|
+|---|---|---|---|
+|k|标准差倍数|选填|3|
+
+
+- IQR<sup>[2]</sup>：四分位距 (Interquartile range, IQR) 是一种衡量变异性的方法. 四分位数将一个按等级排序的数据集划分为四个相等的部分。即 Q1（第 1 个四分位数）、Q2（第 2 个四分位数）和 Q3（第 3 个四分位数）。IQR 定义为 Q3–Q1，位于 Q3+1.5 。无输入参数。
+
+- Grubbs<sup>[3]</sup>: 又称为 Grubbs' test，即最大标准残差测试。Grubbs 通常用作检验最大值、最小值偏离均值的程度是否为异常，该单变量数据集遵循近似标准正态分布。非正态分布数据集不能使用该方法。无输入参数。
+
+- SHESD<sup>[4]</sup>： 带有季节性的 ESD 检测算法。ESD 可以检测时间序列数据的多异常点。需要指定异常点比例的上界***k***，最差的情况是至多49.9%。数据集的异常比例一般不超过5%
+
+|参数名称|说明|是否必选|默认值|
+|---|---|---|---|
+|k|异常点在输入数据集中占比，范围是$`1\le K \le 49.9`$ |选填|5|
+
+
+### 基于数据密度的检测方法
+LOF<sup>[5]</sup>: 局部离群因子(LOF，又叫局部异常因子)算法是Breunig于2000年提出的一种基于密度的局部离群点检测算法，该方法适用于不同类簇密度分散情况迥异的数据。根据数据点周围的数据密集情况，首先计算每个数据点的一个局部可达密度，然后通过局部可达密度进一步计算得到每个数据点的一个离群因子，该离群因子即标识了一个数据点的离群程度，因子值越大，表示离群程度越高，因子值越小，表示离群程度越低。最后，输出离群程度最大的top(n)个点。
+
+
+### 基于深度学习的检测方法
+使用自动编码器的异常检测模型。可以对具有周期性的数据具有较好的检测结果。但是使用该模型需要针对输入的时序数据进行训练，同时将训练完成的模型部署到服务目录中，才能够运行与使用。
+
+
+### 参考文献
+1. https://en.wikipedia.org/wiki/68%E2%80%9395%E2%80%9399.7_rule
+2. https://en.wikipedia.org/wiki/Interquartile_range
+3. Adikaram, K. K. L. B.; Hussein, M. A.; Effenberger, M.; Becker, T. (2015-01-14). "Data Transformation Technique to Improve the Outlier Detection Power of Grubbs's Test for Data Expected to Follow Linear Relation". Journal of Applied Mathematics. 2015: 1–9. doi:10.1155/2015/708948.
+4. Hochenbaum, O. S. Vallis, and A. Kejariwal. 2017. Automatic Anomaly Detection in the Cloud Via Statistical Learning. arXiv preprint arXiv:1704.07706 (2017).
+5. Breunig, M. M.; Kriegel, H.-P.; Ng, R. T.; Sander, J. (2000). LOF: Identifying Density-based Local Outliers (PDF). Proceedings of the 2000 ACM SIGMOD International Conference on Management of Data. SIGMOD. pp. 93–104. doi:10.1145/335191.335388. ISBN 1-58113-217-4.
+
diff --git a/docs/zh/06-advanced/06-data-analysis/addins.md b/docs/zh/06-advanced/06-data-analysis/addins.md
@@ -0,0 +1,167 @@
+---
+title: "addins"
+sidebar_label: "addins"
+---
+
+本节说明如何将自己开发的新预测算法和异常检测算法整合到 TDengine 分析平台， 并能够通过 SQL 语句进行调用。
+
+## 目录结构
+
+![数据分析功能架构图](./pic/dir.png)
+
+|目录|说明|
+|---|---|
+|taos|Python 源代码目录，其下包含了算法具体保存目录 algo，放置杂项目录 misc， 单元测试和集成测试目录 test。 algo目录下 ad 放置异常检测算法代码， fc 放置预测算法代码|
+|script|是安装脚本和发布脚本放置目录|
+|model|放置针对数据集完成的训练模型|
+|cfg|	配置文件目录|
+
+## 约定与限制
+
+定义异常检测算法的 Python 代码文件 需放在 /taos/algo/ad 目录中，预测算法 Python 代码文件需要放在 /taos/algo/fc 目录中，以确保系统启动的时候能够正常加载对应目录下的 Python 文件。
+
+
+### 类命名规范
+
+算法类的名称需要 以下划线开始，以 Service 结尾。例如：_KsigmaService 是  KSigma 异常检测算法的实现类。
+
+### 类继承约定
+
+异常检测算法需要从 `AbstractAnomalyDetectionService` 继承，并实现其核心抽象方法 `execute`.
+预测算法需要从 `AbstractForecastService` 继承，同样需要实现其核心抽象方法 `execute`。
+
+### 类属性初始化
+每个算法实现的类需要静态初始化两个类属性，分别是
+
+`name`: 的触发调用关键词，全小写英文字母。
+`desc`：该算法的描述信息。
+
+### 核心方法输入与输出约定
+
+`execute` 是算法处理的核心方法。调用该方法的时候， `self.list` 已经设置好输入数组。
+异常检测输出结果
+
+`execute` 的返回值是长度与  `self.list` 相同的数组，数组位置为 -1 的即为异常值点。例如：输入数组是  [2, 2, 2, 2, 100]， 如果 100 是异常点，那么返回值是 [1, 1, 1, 1, -1]。
+预测输出结果
+
+对于预测算法， `AbstractForecastService` 的对象属性说明如下：
+
+|属性名称|说明|默认值|
+|---|---|---|
+|period|输入时序数据的周期性，多少个数据点表示一个完整的周期。如果没有周期性，那么设置为 0 即可。|	0|
+|start_ts|预测数据的开始时间|	0|
+|time_step|预测结果的两个数据点之间时间间隔|0	|
+|fc_rows|预测结果数量|	0	|
+|return_conf|返回结果中是否包含执行区间范围，如果算法计算结果不包含置信区间，那么上界和下界与自身相同|	1|	
+|conf|执行区间分位数	0.05|
+
+
+预测返回结果如下：
+```python
+return {
+    "rows": self.fc_rows,   # 预测数据行数
+    "period": self.period,  # 数据周期性，同输入
+    "algo": "holtwinters",  # 预测使用的算法
+    "mse": mse,				# 预测算法的 mse
+    "res": res              # 结果数组 [时间戳数组, 预测结果数组, 预测结果执行区间下界数组，预测结果执行区间上界数组]
+}
+```
+
+
+## 示例代码
+
+```python
+import numpy as np
+from service import AbstractAnomalyDetectionService
+
+# 算法实现类名称 需要以下划线 "_" 开始，并以 Service 结束，如下 _IqrService 是 IQR 异常检测算法的实现类。
+class _IqrService(AbstractAnomalyDetectionService):
+    """ IQR algorithm 定义类，从 AbstractAnomalyDetectionService 继承，并实现 AbstractAnomalyDetectionService类的抽象函数  """
+
+	# 定义算法调用关键词，全小写ASCII码(必须添加)
+    name = 'iqr'
+
+	# 该算法的描述信息(建议添加)
+    desc = """found the anomaly data according to the inter-quartile range"""
+
+    def __init__(self):
+        super().__init__()
+
+    def execute(self):
+		""" execute 是算法实现逻辑的核心实现，直接修改该实现即可 """
+
+		# self.list 是输入数值列，list 类型，例如：[1,2,3,4,5]。设置 self.list 的方法在父类中已经进行了定义。实现自己的算法，修改该文件即可，以下代码使用自己的实现替换即可。
+        #lower = np.quantile(self.list, 0.25)
+        #upper = np.quantile(self.list, 0.75)
+
+        #min_val = lower - 1.5 * (upper - lower)
+        #max_val = upper + 1.5 * (upper - lower)
+        #threshold = [min_val, max_val]
+
+		# 返回值是与输入数值列长度相同的数据列，异常值对应位置是 -1。例如上述输入数据列，返回数值列是 [1, 1, 1, 1, -1],表示 [5] 是异常值。
+        return [-1 if k < threshold[0] or k > threshold[1] else 1 for k in self.list]
+
+
+    def set_params(self, params):
+		"""该算法无需任何输入参数，直接重载父类该函数，不处理算法参数设置逻辑"""
+        pass
+```
+
+
+## 单元测试
+
+在测试文件目录中的 anomaly_test.py 中增加单元测试用例。
+```python
+def test_iqr(self):
+	""" 测试 _IqrService 类 """
+    s = loader.get_service("iqr")
+
+    # 设置需要进行检测的输入数据
+    s.set_input_list(AnomalyDetectionTest.input_list)
+
+	#  测试 set_params 的处理逻辑
+    try:
+        s.set_params({"k": 2})
+    except ValueError as e:
+        self.assertEqual(1, 0)
+
+    r = s.execute()
+
+	# 绘制异常检测结果
+    draw_ad_results(AnomalyDetectionTest.input_list, r, "iqr")
+
+	# 检查结果
+    self.assertEqual(r[-1], -1)
+    self.assertEqual(len(r), len(AnomalyDetectionTest.input_list))
+```
+
+## 需要模型的算法
+
+针对特定数据集，进行模型训练的算法，在训练完成后。需要将训练得到的模型保存在  model 目录中。需要注意的是，针对每个算法，需要建立独立的文件夹。例如 auto_encoder 的训练算法在 model 目录下建立了， autoencoder的目录，使用该算法针对不同数据集训练得到的模型，均需要放置在该目录下。
+
+训练完成后的模型，使用  joblib 进行保存。
+
+并在 model 目录下建立对应的文件夹存放该模型。
+
+保存模型的调用，可参考  encoder.py 的方式，用户通过调用  set_params 方法，并指定参数 `{"model": "ad_encoder_keras"}` 的方式，可以调用该模型进行计算。
+
+具体的调用方式如下：
+
+```python
+def test_autoencoder_ad(self):
+    # 获取特定的算法服务
+    s = loader.get_service("ac")
+    data = self.__load_remote_data_for_ad()
+
+    # 设置异常检查的输入数据
+    s.set_input_list(data)
+
+    # 指定调用的模型，该模型是之前针对该数据集进行训练获得
+    s.set_params({"model": "ad_encoder_keras"})
+    # 执行检查动作，并返回结果
+    r = s.execute()
+
+    num_of_error = -(sum(filter(lambda x: x == -1, r)))
+    self.assertEqual(num_of_error, 109)
+```
+