高级计算函数

衡石系统提供了一些高级计算函数，用于同环比计算、累计计算、移动计算、留存计算、活跃计算等。此类函数说明的示例都是基于数据库中的 advancedcal 表。下面是 advancedcal 的数据。

logindate	username	usertype	energy
2019-01-05 00:00:00	A1	U1	10
2019-01-05 00:00:00	A2	U2	20
2019-01-05 00:00:00	A3	U1	30
2019-01-05 00:00:00	A4	U1	5
2019-01-05 00:00:00	A5	U1	15
2019-01-05 00:00:00	A6	U3	16
2019-01-05 00:00:00	A7	U3	18
2019-01-05 00:00:00	A8	U1	21
2019-01-06 00:00:00	A2	U2	22
2019-01-06 00:00:00	A3	U1	2
2019-01-06 00:00:00	A1	U1	12
2019-01-06 00:00:00	A6	U3	9
2019-01-06 00:00:00	A5	U1	8
2019-01-06 00:00:00	A4	U1	5
2019-01-07 00:00:00	A5	U1	24
2019-01-07 00:00:00	A4	U1	12
2019-01-07 00:00:00	A3	U1	16
2019-01-07 08:00:00	A5	U1	28
2019-01-09 00:00:00	A8	U1	27

bottom_n

保留某列在指定分组和排序下的前n个值，其余值统一为特殊值

函数语法

text

bottom_n(N, field1, constant1) over([ PARTITION BY expr1 ] ORDER BY expr2 [ DESC ])

参数说明
- N: 必填，需要保留的值的个数。
- field1: 必填，要保留值的字段名。
- constant1: 必填，非保留值要统一表示为的值，它需要和 field1 的字段类型相同。
- expr1: 选填，分组字段，如果有分组字段，就表示在该分组下去计算 field1 的保留值。
- expr2: 必填，对 field1 的排序规则，通常它是 field1 本身或者是其它字段的聚合值。
返回值类型
同 field1 的字段类型
示例1

以 userType 为分组，保留按照 count({energy}) 排名最后2名的username，其余的用 "其它" 表示。

text

{"kind":"formula","op":"summarize(dataset(2),{usertype} as t1, bottom_n(2, {username}, '其它') over(PARTITION BY {usertype} order by count({energy}) asc) as test)"}

calculate

预先计算出来一些数据，然后和原始的数据一起计算图表的数据，一般用于新建指标或者图表过滤中。用于指标计算的时候，它的外层需要有合适的聚合计算函数。图表中的 calculate 表达式的值会随着小计发生变化，明细数据计算的维度和小计的维度不同从而影响calculate表达式的值。

函数语法

text

calculate(ARG1, [ARG2],... )

参数说明
- ARG1: 预先计算数据所需的表达式
- ARG2: 非必填，可以是多个，表示要删除的图表中的分组字段
返回值类型
任意类型
示例1

比如图表中维度有 prime_genre 和 month，度量是 votes 求和。过滤条件是按照 prime_genre 分组的 votes 求和中排名前三的。过滤条件的写法如下。

text

calculate(rank() OVER (ORDER BY sum({votes}) ASC), {prime_genre}) < 4

calculatep

预先计算出来一些数据，然后和原始的数据一起计算图表的数据，一般用于新建指标或者图表过滤中。用于指标计算的时候，它的外层需要有合适的聚合计算函数。图表中的 calculatep 表达式的值不会被小计影响。

函数语法

text

calculatep(ARG1, [ARG2],... )

参数说明
- ARG1: 预先计算数据所需的表达式
- ARG2: 非必填，可以是多个，表示要删除的图表中的分组字段
返回值类型
任意类型
示例1

比如图表中维度有 prime_genre 和 month，度量是 votes 求和。过滤条件是按照 prime_genre 分组的 votes 求和中排名前三的。过滤条件的写法如下。

text

calculate(rank() OVER (ORDER BY sum({votes}) ASC), {prime_genre}) < 4

calculatex

预先计算出来一些数据，然后和原始的数据一起计算图表的数据，一般用于新建指标或者图表过滤中。用于指标计算的时候，它的外层需要有合适的聚合计算函数。它不受维度控制，所以也可以用在维度上。

函数语法

text

calculatex(ARG1, ARG2,... )

参数说明
- ARG1: 预先计算数据所需的表达式
- ARG2: 必填，计算表达式所需的分组。
返回值类型
任意类型
示例1

比如图表度量是 votes 求和。过滤条件是按照 prime_genre 分组的 votes 求和中排名前三的。过滤条件的写法如下。

text

calculatex(rank() OVER (ORDER BY sum({votes}) ASC), {prime_genre}) < 4

continuous_retention

时间维度下的连续活跃计算，该函数返回数据在指定时间内的连续活跃数。

函数语法

text

continuous_retention(expression, date expression, lowExpr, upperExpr, period)

参数说明
- expression：必填，要参与计算的字段。
- date expression：必填，留存的时间维度。图表中维度必须包含与 date expression 相同的时间维度，才可以用此指标。summarize 函数的非聚合参数中也必须包含与 date expression 相同的时间维度，才可以在聚合参数中使用这个函数。
- lowExpr：必填，留存/活跃时间的开始。
- upperExpr：必填，留存/活跃时间的结束，要比实际的结束时间多一天。
- period：必填，活跃周期，类型是String，可选值是：day、week、month、quarter、year。
返回值类型
数字
示例1

用计算指标计算username 在昨天和前天的连续活跃数。

用下面的高级表达式新增指标：

text

continuous_retention({username}, day({logindate}), dayadd(day({logindate}), -2), dayadd(day({logindate}), 0), 'day')

新建图表，维度选择{logindate}，然后拖入上面的指标做为度量。
下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "2019-01-05",
        0
      ],
      [
        "2019-01-06",
        0
      ],
      [
        "2019-01-07",
        3
      ],
      [
        "2019-01-09",
        0
      ]
    ],
    "schema": [
      {
        "fieldName": "u_6f28278382639341_0"
      },
      {
        "fieldName": "u_34393f485a5d2eb3_1"
      }
    ]
  }
}

示例2

用 HE 计算username 在昨天和前天的连续活跃率。

json

{
  "kind": "formula",
  "op": "summarize(dataset(1), day({logindate}), growth_rate(distinct_count({username}), continuous_retention({username}, day({logindate}), dayadd(day({logindate}), -2), dayadd(day({logindate}), 0), 'day')))"
}

下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "2019-01-05",
        null
      ],
      [
        "2019-01-06",
        null
      ],
      [
        "2019-01-07",
        0
      ],
      [
        "2019-01-09",
        null
      ]
    ],
    "schema": [
      {
        "fieldName": "hs_new_field_1"
      },
      {
        "fieldName": "hs_new_field_2"
      }
    ]
  }
}

custom_filters

自定义筛选器计算

函数语法

text

custom_filters(expression, [{field1},{field2}], condition)

参数说明
- expression: 必填，必须是基础聚合运算。
- [{field1},{field2}]：选填，null 表示不删除上文的过滤器，[] 表示删除上文中的所有过滤器，field1/field2 表示过滤器中使用了任意这些字段，那么这个过滤器就会被删除。
- condition: 选填，计算 expression 时需要新加的过滤条件。
返回值类型同 expression 的返回类型
示例1

用新增指标计算 engergy 求和，删除上文中的 logindate 相关的过滤器，添加新的时间过滤。

用下面的高级表达式新增指标：

text

custom_filters(sum({energy}),[{logindate}],{logindate}='2000-01-01')

date_accumulate

此函数返回一定时间范围内的数据进行累计计算的结果。只能在新增指标或者 API 查询中使用。

函数语法

text

date_accumulate(function1(function2(expression)), date expression1, reset period)

参数说明
- function1: 必填，累计计算的计算类型，可选值为：sum、avg、min、max。
- function2: 必填，数据的基础运算，必须是基础聚合运算，可选值为：sum、avg、min、max、percentile、count、distinct_count。
- expression: 必填，要参与计算的字段。
- date expression1: 必填，基础计算的时间维度。图表中维度必须包含与 date expression1 相同的时间维度，才可以用此指标。summarize 函数的非聚合参数中也必须包含与 date expression1 相同的时间维度，才可以在聚合参数中使用这个函数。
- reset period: 必填，累计计算的重复周期，计算时会在每个周期的起点清零并重新计算。可选值为：hour、day、week、month、quarter、year。
返回值类型数字
示例1

用新增指标计算每周的累计 engergy 平均值。

用下面的高级表达式新增指标：

text

date_accumulate(sum(avg({energy})), day({logindate}), 'week')

新建图表，维度选择{logindate}，计算方式选择按天，拖入{energy}平均值做为度量，然后拖入上面的指标做为度量。
下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "2019-01-05",
        16.8750000000000000,
        16.8750000000000000
      ],
      [
        "2019-01-06",
        9.6666666666666667,
        26.5416666666666667
      ],
      [
        "2019-01-07",
        20.0000000000000000,
        20.0000000000000000
      ],
      [
        "2019-01-09",
        27.0000000000000000,
        47.0000000000000000
      ]
    ],
    "schema": [
      {
        "fieldName": "u_6f28278382639341_0"
      },
      {
        "fieldName": "u_7cd2518b65642b48_1"
      },
      {
        "fieldName": "u_c3f773f19fcb0912_2"
      }
    ]
  }
}

示例2

用 HE 查询计算每周的累计 engergy 平均值。累计计算的时候只算 userType='U1' 的数据。

text

{"kind":"formula","op":"summarize(dataset(1), day({logindate}), avg({energy}), date_accumulate(sum(avg({energy}) filter (where {usertype} = 'U1')), day({logindate}), 'week'))"}

下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "2019-01-05",
        16.875,
        16.2
      ],
      [
        "2019-01-06",
        9.6666666666666667,
        22.95
      ],
      [
        "2019-01-07",
        20,
        20
      ],
      [
        "2019-01-09",
        27,
        47
      ]
    ],
    "schema": [
      {
        "fieldName": "hs_new_field_1"
      },
      {
        "fieldName": "hs_new_field_2"
      },
      {
        "fieldName": "hs_new_field_3"
      }
    ]
  }
}

date_compare

此函数返回数据相对于指定日期的环比对比值。

函数语法

text

date_compare(function(expression), date expression1, date expression2)

参数说明
- function: 必填，数据的基础运算，必须是基础聚合运算，可选值为：sum、avg、min、max、percentile、count、distinct_count。
- date expression1: 必填，基础计算的时间维度。图表中维度必须包含与 date expression1 相同的时间维度，才可以用此指标。summarize 函数的非聚合参数中也必须包含与 date expression1 相同的时间维度，才可以在聚合参数中使用这个函数。
- date expression2:必填，对比时间维度。
返回值类型
数字
示例1

用新增指标计算两天前 engergy求和的对比值。

用下面的高级表达式新增指标：

text

date_compare(sum({energy}), day({logindate}), add_day(day({logindate}), -2))

新建图表，维度选择{logindate}，计算方式选择按天，拖入{energy}求和做为度量，然后拖入上面的指标做为度量。
下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "2019-01-05",
        135,
        null
      ],
      [
        "2019-01-06",
        58,
        null
      ],
      [
        "2019-01-07",
        80,
        135
      ],
      [
        "2019-01-09",
        27,
        80
      ]
    ],
    "schema": [
      {
        "fieldName": "u_6f28278382639341_0"
      },
      {
        "fieldName": "u_7cd2518b65642b48_2"
      },
      {
        "fieldName": "u_c8f6e35a15596acf_3"
      }
    ]
  }
}

示例2

用 HE 计算两天前 engergy求和的增长率。

text

{"kind":"formula","op":"summarize(dataset(1), day({logindate}), sum({energy}), growth_rate(sum({energy}), date_compare(sum({energy}), day({logindate}), add_day(day({logindate}), -2))))"}

下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "2019-01-09",
        27,
        -0.6625
      ],
      [
        "2019-01-06",
        58,
        null
      ],
      [
        "2019-01-07",
        80,
        -0.40740740740740740741
      ],
      [
        "2019-01-05",
        135,
        null
      ]
    ],
    "schema": [
      {
        "fieldName": "hs_new_field_1"
      },
      {
        "fieldName": "hs_new_field_2"
      },
      {
        "fieldName": "hs_new_field_3"
      }
    ]
  }
}

date_shift

移动计算，此函数根据时间序列，逐项推移，依次对一定项数进行统计。

函数语法

text

date_shift(function1(function2(expression)), date expression, lowExpr, upperExpr)

参数说明
- function1: 必填，移动计算的计算类型，可选值为：sum、avg、min、max。
- function2: 必填，数据的基础运算，必须是基础聚合运算，可选值为：sum、avg、min、max、percentile、count、distinct_count。
- expression: 必填，要参与计算的字段。
- date expression1: 必填，基础计算的时间维度。图表中维度必须包含与 date expression1 相同的时间维度，才可以用此指标。summarize 函数的非聚合参数中也必须包含与 date expression1 相同的时间维度，才可以在聚合参数中使用这个函数。
- lowExpr: 必填，移动计算往前偏移的量，类型是number。
- upperExpr: 必填，移动计算往后偏移的量，类型是number。
返回值类型
数字
示例1

往前偏移一天，往后偏移一天，移动计算engergy求和的累加值。用新增指标计算。

用下面的高级表达式新增指标：

text

date_shift(sum(sum({energy})), day({logindate}), -1, 1)

新建图表，维度选择{logindate}，计算方式选择按天，拖入{energy}求和做为度量，然后拖入上面的指标做为度量。
下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "2019-01-05",
        135,
        193
      ],
      [
        "2019-01-06",
        58,
        273
      ],
      [
        "2019-01-07",
        80,
        138
      ],
      [
        "2019-01-09",
        27,
        27
      ]
    ],
    "schema": [
      {
        "fieldName": "u_6f28278382639341_0"
      },
      {
        "fieldName": "u_7cd2518b65642b48_2"
      },
      {
        "fieldName": "u_2fb8394ac0a23a02_3"
      }
    ]
  }
}

示例2

往前偏移一天，往后偏移一天，移动计算engergy求和的累加值。用 HE 计算。

text

{"kind":"formula","op":"summarize(dataset(1), day({logindate}), sum({energy}), date_shift(sum(sum({energy})), day({logindate}), -1, 1))"}```

下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "2019-01-09",
        27,
        27
      ],
      [
        "2019-01-06",
        58,
        273
      ],
      [
        "2019-01-07",
        80,
        138
      ],
      [
        "2019-01-05",
        135,
        193
      ]
    ],
    "schema": [
      {
        "fieldName": "hs_new_field_1"
      },
      {
        "fieldName": "hs_new_field_2"
      },
      {
        "fieldName": "hs_new_field_3"
      }
    ]
  }
}

lookupvalue

从其它非关联的数据中计算出结果，展示在当前图表中，只能用于新建指标

函数语法

text

lookupvalue(ARG1, ARG2, ARG3)

参数说明
- ARG1: 在非关联数据上要计算的聚合表达式，非关联数据集字段信息必须带上数据集 id
- ARG2: 非关联数据上与本图表可以关联的表达式，非关联数据集字段信息必须带上数据集 id
- ARG3: 本图表中用于关联的表达式，它必须和图表中的一个维度相同
返回值类型
任意类型
示例1

比如图表用了数据集"销售订单"，维度是 year({date})，需要同时展示出数据集"进货明细"表中每年的金额总和。指标表达式如下。请注意表达中使用的是数据集"进货明细"的 id

text

lookupvalue(SUM({{2}}.{金额}), year({{2}}.{date}), year({date}))

repetition_count

重复计算，此函数计算数据的重复次数。

函数语法

text

repetition_count(expression)

参数说明
- expression:必填，要参与计算的字段。
返回值类型
数字
示例1

用计算指标计算每种类型的 username 的重复出现次数。

用下面的高级表达式新增指标：

text

repetition_count({username})

新建图表，维度选择{logindate}，计算方式选择按天，然后拖入上面的指标做为度量。
下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "2019-01-05",
        0
      ],
      [
        "2019-01-06",
        0
      ],
      [
        "2019-01-07",
        2
      ],
      [
        "2019-01-09",
        0
      ]
    ],
    "schema": [
      {
        "fieldName": "u_6f28278382639341_0"
      },
      {
        "fieldName": "u_409214f201c6ce01_2"
      }
    ]
  }
}

示例2

用 HE 计算每种类型的 username 的重复出现次数。

text

{"kind":"formula","op":"summarize(dataset(1), {usertype}, repetition_count({username}))"}

下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "U2",
        2
      ],
      [
        "U1",
        14
      ],
      [
        "U3",
        2
      ]
    ],
    "schema": [
      {
        "fieldName": "usertype"
      },
      {
        "fieldName": "hs_new_field_1"
      }
    ]
  }
}

repetition

重复计算，按照条件，返回数据的重复数。

函数语法

text

repetition(expression, lowExpr, upperExpr)

参数说明
- expression: 必填，要参与计算的字段。
- lowExpr: 必填，最少重复次数，类型是 number。
- upperExpr: 必填，最大重复次数，类型是 number。
返回值类型
数字
示例1

用计算指标计算每种类型下 username 出现次数在两次到三次之前的重复数。

用下面的高级表达式新增指标：

text

repetition({username}, 2, 3)

新建图表，维度选择{userType}，然后拖入上面的指标做为度量。
下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "U1",
        4
      ],
      [
        "U2",
        1
      ],
      [
        "U3",
        1
      ]
    ],
    "schema": [
      {
        "fieldName": "u_452a834347a47a1e_0"
      },
      {
        "fieldName": "u_34393f485a5d2eb3_1"
      }
    ]
  }
}

示例2

用 HE 计算每种类型下 username 出现次数在两次到三次之前的重复数。

text

{"kind":"formula","op":"summarize(dataset(1), {usertype}, repetition({username}, 2, 3))"}

下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "U2",
        1
      ],
      [
        "U1",
        4
      ],
      [
        "U3",
        1
      ]
    ],
    "schema": [
      {
        "fieldName": "usertype"
      },
      {
        "fieldName": "hs_new_field_1"
      }
    ]
  }
}

retention

时间维度下的留存/活跃计算，该函数返回数据在指定时间内的留存数或者活跃数。

函数语法

text

retention(expression, date expression, lowExpr, upperExpr, includeStartExpr, includeEndExpr, excludeStartExpr, excludeEndExpr)

参数说明
- expression: 必填，要参与计算的字段。
- date expression: 必填，留存的时间维度。图表中维度必须包含与 date expression 相同的时间维度，才可以用此指标。summarize 函数的非聚合参数中也必须包含与 date expression 相同的时间维度，才可以在聚合参数中使用这个函数。
- lowExpr: 必填，留存/活跃时间的开始。
- upperExpr: 必填，留存/活跃时间的结束，要比实际的结束时间多一天。
- includeStartExpr: 非必填，计算的字段需要存在的时间段开始时间。
- includeEndExpr: 非必填，计算的字段需要存在的时间段结束时间。
- excludeStartExpr: 非必填，计算的字段不能存在的时间段开始时间。
- excludeEndExpr: 非必填，计算的字段不能存在的时间段结束时间。

includeStartExpr，includeEndExpr，excludeStartExpr，excludeEndExpr必须一起存在，或者一起消失，而且顺序要求严格。

返回值类型
数字
示例1

用计算指标计算username 在接下来的第一天和第二天的留存数。

用下面的高级表达式新增指标：

text

retention({username}, day({logindate}), dayadd(day({logindate}), 1), dayadd(day({logindate}), 3))

新建图表，维度选择{logindate}，然后拖入上面的指标做为度量。
下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "2019-01-05",
        6
      ],
      [
        "2019-01-06",
        3
      ],
      [
        "2019-01-07",
        0
      ],
      [
        "2019-01-09",
        0
      ]
    ],
    "schema": [
      {
        "fieldName": "u_6f28278382639341_0"
      },
      {
        "fieldName": "u_cbc569ab32ff31d1_2"
      }
    ]
  }
}

示例2

用 HE 计算username 在前一天前二天的活跃数。

json

{
  "kind": "formula",
  "op": "summarize(dataset(1), day({logindate}), retention({username}, day({logindate}), dayadd(day({logindate}), -2), dayadd(day({logindate}), 0)))"
}

下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "2019-01-09",
        0
      ],
      [
        "2019-01-06",
        6
      ],
      [
        "2019-01-07",
        3
      ],
      [
        "2019-01-05",
        0
      ]
    ],
    "schema": [
      {
        "fieldName": "hs_new_field_1"
      },
      {
        "fieldName": "hs_new_field_2"
      }
    ]
  }
}

示例3

用计算指标计算新username 在接下来的第一天和第二天的留存数。

用下面的高级表达式新增指标：

text

retention({username}, day({logindate}), dayadd(day({logindate}), 1), dayadd(day({logindate}), 3), null, null, null, day({logindate}))

新建图表，维度选择{logindate}，然后拖入上面的指标做为度量。
下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "2019-01-05",
        6
      ],
      [
        "2019-01-06",
        null
      ],
      [
        "2019-01-07",
        null
      ],
      [
        "2019-01-09",
        null
      ]
    ],
    "schema": [
      {
        "fieldName": "u_6f28278382639341_0"
      },
      {
        "fieldName": "u_cbc569ab32ff31d1_2"
      }
    ]
  }
}

此函数和图表轴里的时间维度配合，返回数据相对于指定日期的环比对比值。

函数语法

text

previous(function(expression), period, delta)

参数说明
- function: 必填，数据的基础运算，必须是基础聚合运算，可选值为：sum、avg、min、max、percentile、count、distinct_count。
- period: 选填，表示要进行比较的粒度，可选值为：year、quarter、month、week、day、hour。没有值的情况下，它会取图表中粒度最小的时间轴。
- delta: 选填，表示要比较的时间偏移量，类型为整数。
返回值类型
数字
示例1

用新增指标计算 engergy 求和的日环比对比值。

用下面的高级表达式新增指标：

text

previous(sum({energy}))

新建图表，维度选择{logindate}，计算方式选择按天，拖入{energy}求和做为度量，然后拖入上面的指标做为度量。
下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "2019-01-05",
        135,
        null
      ],
      [
        "2019-01-06",
        58,
        135
      ],
      [
        "2019-01-07",
        80,
        58
      ],
      [
        "2019-01-09",
        27,
        null
      ]
    ],
    "schema": [
      {
        "fieldName": "u_6f28278382639341_0"
      },
      {
        "fieldName": "u_7cd2518b65642b48_2"
      },
      {
        "fieldName": "u_c8f6e35a15596acf_3"
      }
    ]
  }
}

rollup_value

它可以基于部分维度计算度量，一般用于新建指标。

函数语法

text

rollup_value(ARG) OVER( [ PARTITION BY expr1 ] ] )

参数说明
- ARG: 聚合计算表达式
返回值类型
任意类型
示例1

计算所有 votes 的总和，它可用于任意图表中

text

rollup_value(sum({votes})) OVER ()

示例2

按照 month 分组后，计算组内 votes 的总和，它能够用于维度中有 month 的图表中

text

rollup_value(sum({votes})) OVER (partition by {month})

static_continuous_retention

非时间维度的连续活跃计算，该函数返回数据在指定时间段间的连续活跃数。

函数语法

text

static_continuous_retention(expression, date expression, start date, end date, compare start date, compare end date, period)

参数说明
- expression: 必填，要参与计算的字段。
- date expression: 必填，计算活跃的时间字段。
- start date: 必填，要计算的开始时间，类型是时间。
- end date: 必填，要计算的结束时间，类型是时间。比实际的结束时间要晚一天。
- compare start date: 必填，要计算的留存周期的开始时间，类型是时间。
- compare end date: 必填，要计算的留存周期的结束时间，类型是时间。比实际的留存周期结束时间要晚一天。
- period: 必填，活跃周期，类型是String，可选值是：day、week、month、quarter、year。
返回值类型
数字
示例1

用计算指标计算今天在线的 username，在前一年到两年里的连续活跃数，活跃周期为年。

用下面的高级表达式新增指标：

text

static_continuous_retention({username}, {logindate}, day(now()), dayadd(day(now()), 1), yearadd(year(now()), -2), yearadd(year(now()), 0), 'year')

新建图表，维度选择{usertype}，然后拖入上面的指标做为度量。
下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "U1",
        0
      ],
      [
        "U2",
        0
      ],
      [
        "U3",
        0
      ]
    ],
    "schema": [
      {
        "fieldName": "u_452a834347a47a1e_0"
      },
      {
        "fieldName": "u_c126c85c957b406e_2"
      }
    ]
  }
}

static_continuous_retention_rate

非时间维度的连续活跃计算，该函数返回数据在指定时间段间的连续活跃率。

函数语法

text

static_continuous_retention_rate(expression, date expression, start date, end date, compare start date, compare end date, period)

参数说明
- expression: 必填，要参与计算的字段。
- date expression: 必填，计算活跃的时间字段。
- start date: 必填，要计算的开始时间，类型是时间。
- end date: 必填，要计算的结束时间，类型是时间。比实际的结束时间要晚一天。
- compare start date: 必填，要计算的留存周期的开始时间，类型是时间。
- compare end date: 必填，要计算的留存周期的结束时间，类型是时间。比实际的留存周期结束时间要晚一天。
- period: 必填，活跃周期，类型是String，可选值是：day、week、month、quarter、year。
返回值类型
数字
示例1

用 HE 计算今天在线的 username，在前一年到两年里的连续活跃数，活跃周期为年。

text

{"kind":"formula","op":"summarize(dataset(1), {usertype}, static_continuous_retention({username}, {logindate}, day(now()), dayadd(day(now()), 1), yearadd(year(now()), -2), yearadd(year(now()), 0), 'year'))"}

下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "U2",
        0
      ],
      [
        "U1",
        0
      ],
      [
        "U3",
        0
      ]
    ],
    "schema": [
      {
        "fieldName": "usertype"
      },
      {
        "fieldName": "hs_new_field_1"
      }
    ]
  }
}

static_retention

非时间维度的留存/活跃计算，该函数返回数据在指定时间段间的留存数。

函数语法

text

static_retention(expression, date expression, start date, end date, compare start date, compare end date, includeStartExpr, includeEndExpr, excludeStartExpr, excludeEndExpr)

参数说明
- expression: 必填，要参与计算的字段。
- date expression: 必填，计算活跃的时间字段。
- start date: 必填，要计算的开始时间，类型是时间。
- end date: 必填，要计算的结束时间，类型是时间。比实际的结束时间要晚一天。
- compare start date: 必填，要计算的留存周期的开始时间，类型是时间。
- compare end date: 必填，要计算的留存周期的结束时间，类型是时间。比实际的留存周期结束时间要晚一天。
- includeStartExpr: 非必填，计算的字段需要存在的时间段开始时间。
- includeEndExpr: 非必填，计算的字段需要存在的时间段结束时间。
- excludeStartExpr: 非必填，计算的字段不能存在的时间段开始时间。
- excludeEndExpr: 非必填，计算的字段不能存在的时间段结束时间。

includeStartExpr，includeEndExpr，excludeStartExpr，excludeEndExpr必须一起存在，或者一起消失，而且顺序要求严格。

返回值类型
数字
示例1

用计算指标计算在 2019-01-05 到 2019-01-06时间段内在线的 username，留存到接下来的1到3天的数量。

用下面的高级表达式新增指标：

text

static_retention({username}, {logindate}, '2019-01-05', '2019-01-07', '2019-01-07', '2019-01-10')

新建图表，维度选择{usertype}，然后拖入上面的指标做为度量。
下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "U1",
        4
      ],
      [
        "U2",
        0
      ],
      [
        "U3",
        0
      ]
    ],
    "schema": [
      {
        "fieldName": "u_452a834347a47a1e_0"
      },
      {
        "fieldName": "u_55c18b8d38923c85_2"
      }
    ]
  }
}

示例2

用 HE 计算在 2019-01-07 到 2019-01-09时间段内在线的 username，在2019-01-05的活跃数量。

json

{
  "kind": "formula",
  "op": "summarize(dataset(1), {usertype}, static_retention({username}, {logindate}, '2019-01-07', '2019-01-10', '2019-01-05', '2019-01-06'))"
}

下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "U2",
        0
      ],
      [
        "U1",
        4
      ],
      [
        "U3",
        0
      ]
    ],
    "schema": [
      {
        "fieldName": "usertype"
      },
      {
        "fieldName": "hs_new_field_1"
      }
    ]
  }
}

示例3

用计算指标计算在 2019-01-05 到 2019-01-06时间段内在线的老 username，留存到接下来的1到3天的数量。

用下面的高级表达式新增指标：

text

static_retention({username}, {logindate}, '2019-01-05', '2019-01-07', '2019-01-07', '2019-01-10', null, '2019-01-05', null, null)

新建图表，维度选择{usertype}，然后拖入上面的指标做为度量。
下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "U1",
        4
      ],
      [
        "U2",
        0
      ],
      [
        "U3",
        0
      ]
    ],
    "schema": [
      {
        "fieldName": "u_452a834347a47a1e_0"
      },
      {
        "fieldName": "u_55c18b8d38923c85_2"
      }
    ]
  }
}

static_retention_rate

非时间维度的留存/活跃计算，该函数返回数据在指定时间段间的留存率。

函数语法

text

static_retention_rate(expression, date expression, start date, end date, compare start date, compare end date)

参数说明
- expression: 必填，要参与计算的字段。
- date expression: 必填，计算活跃的时间字段。
- start date: 必填，要计算的开始时间，类型是时间。
- end date: 必填，要计算的结束时间，类型是时间。比实际的结束时间要晚一天。
- compare start date: 必填，要计算的留存周期的开始时间，类型是时间。
- compare end date: 必填，要计算的留存周期的结束时间，类型是时间。比实际的留存周期结束时间要晚一天。
返回值类型
数字
示例1

用计算指标计算在 2019-01-05 到 2019-01-06时间段内在线的 username，在接下来的1到3天的留存率。

用下面的高级表达式新增指标：

text

static_retention_rate({username}, {logindate}, '2019-01-05', '2019-01-07', '2019-01-07', '2019-01-10')

新建图表，维度选择{usertype}，然后拖入上面的指标做为度量。
下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "U1",
        0.80000000000000000000
      ],
      [
        "U2",
        0E-20
      ],
      [
        "U3",
        0E-20
      ]
    ],
    "schema": [
      {
        "fieldName": "u_452a834347a47a1e_0"
      },
      {
        "fieldName": "u_6ef7c5c463a74495_1"
      }
    ]
  }
}

示例2

用 HE 计算在 2019-01-07 到 2019-01-09时间段内在线的 username，在2019-01-05的活跃率。

json

{
  "kind": "formula",
  "op": "summarize(dataset(1), {usertype}, static_retention_rate({username}, {logindate}, '2019-01-07', '2019-01-10', '2019-01-05', '2019-01-06'))"
}

下面是计算结果：

json

{
  "data": {
    "data": [
      [
        "U2",
        null
      ],
      [
        "U1",
        1
      ],
      [
        "U3",
        null
      ]
    ],
    "schema": [
      {
        "fieldName": "usertype"
      },
      {
        "fieldName": "hs_new_field_1"
      }
    ]
  }
}

top_n

保留某列在指定分组和排序下的前n个值，其余值统一为特殊值

函数语法

text

top_n(N, field1, constant1) over([ PARTITION BY expr1 ] ORDER BY expr2 [ DESC ])

参数说明
- N: 必填，需要保留的值的个数。
- field1: 必填，要保留值的字段名。
- constant1: 必填，非保留值要统一表示为的值，它需要和 field1 的字段类型相同。
- expr1: 选填，分组字段，如果有分组字段，就表示在该分组下去计算 field1 的保留值。
- expr2: 必填，对 field1 的排序规则，通常它是 field1 本身或者是其它字段的聚合值。
返回值类型
同 field1 的字段类型
示例1

以 userType 为分组，保留按照 count({energy}) 排名前2的username，其余的用 "其它" 表示。

text

{"kind":"formula","op":"summarize(dataset(2),{usertype} as t1, top_n(2, {username}, '其它') over(PARTITION BY {usertype} order by count({energy}) asc) as test)"}

SDK

ChatBot

数据集成

数据填报

创建数据集

数据集加工

函数列表

仪表盘创作

图表类控件

图表高级计算

功能类控件

展示类控件

应用设置

智能查数助手

模型供应商

高级计算函数 ​

bottom_n ​

calculate ​

calculatep ​

calculatex ​

continuous_retention ​

custom_filters ​

date_accumulate ​

date_compare ​

date_shift ​

lookupvalue ​

repetition_count ​

repetition ​

retention ​

previous ​

rollup_value ​

static_continuous_retention ​

static_continuous_retention_rate ​

static_retention ​

static_retention_rate ​

top_n ​

高级计算函数

bottom_n

calculate

calculatep

calculatex

continuous_retention

custom_filters

date_accumulate

date_compare

date_shift

lookupvalue

repetition_count

repetition

retention

previous

rollup_value

static_continuous_retention

static_continuous_retention_rate

static_retention

static_retention_rate

top_n