DQL 高级函数

# 高级函数[¶](https://docs.guance.com/dql/advanced-funcs/#_1)

DQL 查询支持选择**高级函数**。通过使用高级函数，用户可以根据需求和期望目标效果对数据进行更加深入的分析和处理。

高级函数主要用于对 DQL 查出的数据进行进一步的函数计算，并进行直观的时序图展示。观测云除了提供官方的时序处理函数之外，还支持通过本地 Func 上报自定义的数据处理函数，观测云时序图表中支持选择自定义函数对数据进行二次处理并返回数据结果显示。

中心函数由观测云算法团队持续更新，目前 v1 版本已经支持 DBSCAN 高级函数使用，点击查看更多：

- [  中心高级函数](https://docs.guance.com/dql/advanced-funcs/center-funcs/)

# DBSCAN[¶](https://docs.guance.com/dql/advanced-funcs/center-funcs/#dbscan)

即基于历史数据对多条时间序列进行检测发现异常离群检测对象。

## 算法介绍[¶](https://docs.guance.com/dql/advanced-funcs/center-funcs/#_1)

DBSCAN 是一种基于密度的聚类算法。它将密度达到一定阈值的区域划分为簇，并将低密度区域视为噪声。DBSCAN 算法不需要预先指定簇的数量，能够发现任意形状的簇，并且对噪声数据有较好的鲁棒性。

- 检测对象：多条时间序列数据；
- 使用场景：适合同一组时序中发现离群时序的场景；
- 传参: 检测区间 T，距离参数；
- 含义: 从 `Now- T, Now` 中的多条时间线里, 有哪些时间线异常；
- 返回: 返回 1 到 n 条离群时间线。

## 核心参数[¶](https://docs.guance.com/dql/advanced-funcs/center-funcs/#_2)

> 距离（eps）：float, default=0.5

距离参数表示其中一个样本与另一个样本相邻，两个样本之间的最大距离，不是簇内点距离的最大界限。（float, default=0.5）

可选择配置 range(0-3.0) 之间的任意浮点值。如果不配置，默认距离参数为0.5，距离设置越大得到的异常点越少，距离值设置过小可能检测到的离群值非常多，距离值设置过大可能导致没有任何离群检测到，所以需要根据不同的数据特征设置合适的距离参数。

## 使用场景[¶](https://docs.guance.com/dql/advanced-funcs/center-funcs/#_3)

以中心函数 DBSCAN 为例，用户加入观测云空间时，支持选择 DBSCAN。**高级函数 - DBSCAN** 离群检测基于历史数据对多条时间序列进行检测。

在**场景**中选择**时序图**，点击**查询**下的**添加函数**按钮，选择**高级函数 > DBSCAN**，选定算法参数，视图中即可展示多条时间序列的离群效果。如图：

[![img](https://docs.guance.com/dql/img/ad-2.png)](https://docs.guance.com/dql/img/ad-2.png)

DQL 查询示例写法：

```
DBSCAN(`M::cpu:(usage_idle)`, 0.5)
```

<details class="warning" open="open" style="box-sizing: inherit; background-color: rgb(255, 255, 255); border: 0.075rem solid rgb(255, 145, 0); border-radius: 0.2rem; box-shadow: rgba(0, 0, 0, 0.05) 0px 4px 10px 0px, rgba(0, 0, 0, 0.1) 0px 0px 1px 0px; color: rgba(0, 0, 0, 0.87); display: flow-root; font-size: 0.64rem; margin: 1.5625em 0px; padding: 0px 0.6rem; break-inside: avoid; transition: box-shadow 125ms; overflow: visible; font-family: Roboto, -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;"><summary style="box-sizing: border-box; background-color: rgba(255, 145, 0, 0.1); border-top: none; border-right: none; border-bottom: none; border-left: 0.2rem none; border-image: initial; font-weight: 700; margin: 0px -0.6rem; padding: 0.4rem 1.8rem 0.4rem 2rem; position: relative; cursor: pointer; display: block; min-height: 1rem; border-top-left-radius: 0.1rem; border-top-right-radius: 0.1rem; -webkit-tap-highlight-color: transparent; outline: none;">Warning</summary>在进行查询时:<ul style="box-sizing: border-box; margin-bottom: 0.6rem; margin-top: 1em; list-style-type: disc; padding: 0px; margin-left: 0.625em; display: flow-root;"><li style="box-sizing: inherit; margin-bottom: 0.5em; margin-left: 1.25em;">查询数据中需要加入时间分片，例如&nbsp;<code style="box-sizing: inherit; font-feature-settings: &quot;kern&quot;; font-family: &quot;Roboto Mono&quot;, SFMono-Regular, Consolas, Menlo, monospace; color: rgb(54, 70, 78); direction: ltr; font-variant-ligatures: none; transition: color 125ms, background-color 125ms; background-color: rgb(245, 245, 245); border-radius: 0.1rem; -webkit-box-decoration-break: clone; box-decoration-break: clone; font-size: 0.85em; padding: 0px 0.294118em; word-break: break-word; -webkit-tap-highlight-color: transparent; outline: none;">1h:5m:1m</code>；</li><li style="box-sizing: inherit; margin-bottom: 0.5em; margin-left: 1.25em;">该算法计算至少需要五个值，查询时请满足数据点数；</li><li style="box-sizing: inherit; margin-bottom: 0px; margin-left: 1.25em;">该算法是对多条时序进行处理，需要在数据查询时有&nbsp;<code style="box-sizing: inherit; font-feature-settings: &quot;kern&quot;; font-family: &quot;Roboto Mono&quot;, SFMono-Regular, Consolas, Menlo, monospace; color: rgb(54, 70, 78); direction: ltr; font-variant-ligatures: none; transition: color 125ms, background-color 125ms; background-color: rgb(245, 245, 245); border-radius: 0.1rem; -webkit-box-decoration-break: clone; box-decoration-break: clone; font-size: 0.85em; padding: 0px 0.294118em; word-break: break-word; -webkit-tap-highlight-color: transparent; outline: none;">group by</code>&nbsp;字段。</li></ul></details>

## 显示样式[¶](https://docs.guance.com/dql/advanced-funcs/center-funcs/#_4)

- 配置后离群的效果：

[![img](https://docs.guance.com/dql/img/ad-3.png)](https://docs.guance.com/dql/img/ad-3.png)

- 如果没有离群，前端原数据展示：

[![img](https://docs.guance.com/dql/img/ad-4.png)](https://docs.guance.com/dql/img/ad-4.png)

用户通过本地 Func 上报的自定义数据处理函数，点击查看如何上报自定义高级函数：

- [  本地高级函数](https://docs.guance.com/dql/advanced-funcs/local-funcs/)

# 本地 Func 如何上报自定义高级函数[¶](https://docs.guance.com/dql/advanced-funcs/local-funcs/#func)

如果您想在**时序图 > 高级函数**中使用配置好的本地函数，需在创建好观测云连接器后在本地 Func 中新建本地函数脚本，同步发布后即可使用自定义高级函数。

## 具体操作[¶](https://docs.guance.com/dql/advanced-funcs/local-funcs/#_1)

### 步骤一：创建观测云连接器[¶](https://docs.guance.com/dql/advanced-funcs/local-funcs/#_2)

> 参考[创建观测云连接器](https://func.guance.com/doc/practice-guance-self-build-notify-function/#31)

### 步骤二：编写高级函数[¶](https://docs.guance.com/dql/advanced-funcs/local-funcs/#_3)

> 参考[编写自建通知函数](https://func.guance.com/doc/practice-guance-self-build-notify-function/#32)

[![img](https://docs.guance.com/dql/img/local.png)](https://docs.guance.com/dql/img/local.png)

在 Func 中新建本地函数脚本，示例算法写法如下：

```
'''
高级函数示例算法

示例处理内容为：    
1. 数据传入 DQL 语句
2. 返回算法处理后的结果

注意：  
    检测算法的入口函数固定为`AlgorithmScriptName(data,**kwargs)`
    data 为 DQL 查询数据后里面'series'的结构，示例结构如下：
        [
            {
              'name': 'cpu',
              'tags': {'image': 'nginx'},
              'columns': ['usage_total', 'last'],
              'values': [[1681200000000, 8],[1681202880000, 23],......]
              }
              ...
           ]
    **kwargs 为算法可选参数

入口函数：DBSCAN(data,eps)
输出示例：  
    [
        {
            'status'        : "abnormal_series",
                            # 标记此条时序数据是正常还是离群，离群 status 为 "abnormal_series"，正常 status 为 "normal_series"
            'name'          : 'cpu',
            "tags"          : {'image': 'nginx'},
            'colums'        : ['usage_total', 'last'],
            "values"        : [[1681274880000,8],[1681277760000,20],……],
        },
        ...
    ]
'''
```

函数写好后，添加 category 类型，用户 category 类别写法如下：

```
@DFF.API('用户自定义函数名称', category='guance.dqlFunc')
```

<details class="warning" open="open" style="box-sizing: inherit; background-color: rgb(255, 255, 255); border: 0.075rem solid rgb(255, 145, 0); border-radius: 0.2rem; box-shadow: rgba(0, 0, 0, 0.05) 0px 4px 10px 0px, rgba(0, 0, 0, 0.1) 0px 0px 1px 0px; color: rgba(0, 0, 0, 0.87); display: flow-root; font-size: 0.64rem; margin: 1.5625em 0px; padding: 0px 0.6rem; break-inside: avoid; transition: box-shadow 125ms; overflow: visible; font-family: Roboto, -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;"><summary style="box-sizing: border-box; background-color: rgba(255, 145, 0, 0.1); border-top: none; border-right: none; border-bottom: none; border-left: 0.2rem none; border-image: initial; font-weight: 700; margin: 0px -0.6rem; padding: 0.4rem 1.8rem 0.4rem 2rem; position: relative; cursor: pointer; display: block; min-height: 1rem; border-top-left-radius: 0.1rem; border-top-right-radius: 0.1rem; -webkit-tap-highlight-color: transparent; outline: none;">Warning</summary>代码编写完成后，不要忘记发布!!!</details>

### 步骤三：使用本地函数[¶](https://docs.guance.com/dql/advanced-funcs/local-funcs/#_4)

上述步骤操作完毕后，自定义的高级函数即已经新增到观测云的工作空间。在观测云**场景**中**新建仪表盘**，添加**时序图**，可在**高级函数**下看到本地函数，如图：

[![img](https://docs.guance.com/dql/img/ad-5.png)](https://docs.guance.com/dql/img/ad-5.png)

### 步骤四：显示样式[¶](https://docs.guance.com/dql/advanced-funcs/local-funcs/#_5)

- 配置后离群的效果：

[![img](https://docs.guance.com/dql/img/ad-3.png)](https://docs.guance.com/dql/img/ad-3.png)

- 如果没有离群，前端原数据展示：

[![img](https://docs.guance.com/dql/img/ad-4.png)](https://docs.guance.com/dql/img/ad-4.png)