---
url: /v6.2/embed/url-where.md
---
# 发布页面嵌入数据过滤指南

在访问或者嵌入衡石智能分析平台仪表盘/图表的时候，可以在 URL 中添加参数，实现和仪表盘/图表中过滤器类似的功能。下面列举示例介绍，并做详细解释。

## 示例

我们使用一个简单的仪表盘来演示通过 URL 参数 `where` 来过滤数据。

首先如下图所示我们创作了一个[仪表盘](https://preview.hengshi.com/share/app/S23C1AA81F984C9822B354838730D3AF2/dashboard/1)，使用来自 `movie` 表的数据创作了一张 `表格` 图表，使用了 `prime_genre` 字段做维度，`votes` 字段做度量。

![img](/images/topic/develop/embed-url-where-sample-dashboard.png)

假设在应用发布后或公开链接的 url 中我们想要通过 `where` 参数来过滤 `movie` 数据集中 `prime_genre` 字段值为 `剧情` 或 `动作` 的数据，可以如下设置：

其中 `where` 参数的值是一个 HQL 语句，解码后内容为：

```js
[
    {
        "kind": "formula",
        "op": "in({{movie}}.{prime_genre}, ['剧情', '动作'])"
    }
]
```

打开上述链接如下图所示，通过这种方式，我们可以在 URL 中传递过滤条件实现动态过滤数据的能力。

![img](/images/topic/develop/embed-url-where-sample-dashboard-verify.png)

> \[!IMPORTANT] 说明
> 格式为 `{url}?where={where}`, 注意 where 参数的值需要 JSON.stringify 及 URL 编码后传递，`where=` 字符本身不需要被编码。
> 您可以使用下方工具来方便的生成 URL 编码后的 where 参数值及完成 URL。

## 使用数据包的数据

如果图表使用数据来自数据包，需要在 `where` 条件中携带数据包的 ID，示例如下：

```js{5}
[
    {
        "kind": "formula",
        "op": "in({{movie}}.{prime_genre}, ['剧情', '动作'])"
        "appId": 123
    }
]
```

## URL 编码

## HQL 简介

HQL 是一种通过结构化数据进行业务数据查询的语言，是衡石独创的计算过程描述语言 HENGSHI SENSE Query Language (HQL) ，主要目的是解决数据分析领域中的重要问题，提供一种统一的、跨数据库的数据查询语言，详情请参考[API 文档](https://api.hengshi.com/dashboard.html)。

HQL 支持多种数据类型，如布尔值、整数/浮点数和字符串等。它还提供了条件判断函数 if 和 casewhen，以及包括算术、比较和逻辑运算等多种运算符。并且支持大部分 SQL 原生函数，同时也支持部分自定义函数。此外，还内置了一些用于复杂计算的高级函数，如连续活跃率、(活跃/留存)率、同环比率等。

### 数据类型

HQL 的数据类型定义如下：

* 布尔值（Boolean），有 2 个值分别是：true 和 false。
* null，一个表明 null 值的特殊关键字。与 SQL 等数据库语言一样，是大小写不敏感的，因此 null 与 Null、NULL或变体是相同的。
* 数字（Integer/Number），整数或浮点数，例如： 42 或者 3.14159。
* 字符串（String），字符串是一串表示文本值的字符序列，例如："Howdy"。

### 条件判断

条件判断指的是根据指定的条件所返回的结果（真或假或其他预定义的），来执行特定的语句。HQL 支持两种条件判断函数：if 和 casewhen。

#### if

if 函数用于根据条件判断返回一个值，语法如下：

```
if(condition, trueValue, falseValue)
```

if 函数有一个同样用法的别称： `ifelse()`

#### casewhen

casewhen 函数用于根据条件判断返回一个值，语法如下：

```
casewhen(value1, condition1, value2, condition2, ..., valueOfElse)
```

### 运算符

HQL 拥有如下类型的运算符

* 括号：`()`，又叫做分组操作符。
* 不包含：`not in`
* 指数运算、求余： `^`, `%`
* 乘法、除法： `*`, `/`
* 加法、减法： `+`, `-`
* 比较运算符： `>=`, `<=`, `=`, `!=`, `<>`, `>`, `<`
* 逻辑运算符： `or`, `and`

### 表达式

表达式是一组代码的集合，用于计算并返回一个值。HQL 支持如下类型的表达式：

* 变量：支持 数据集、字段、参数、用户属性 4 种，例如：`{{datasetNameOrId}}`、 `{fieldName}`、 `{{%parameterName}}`、 `{{$userAttributeName}}`。
* 字符串：得出一个字符串，例如，"Fred" 或 "234"。通常使用字符串相关函数 `concat('Fr', 'ed')`、`concat('2', '34')`。
* 算术：得出一个数字，例如： 42、3.14159。通常使用算术运算 `{number_field_a} + {number_field_b}`。
* 逻辑值：得出 true 或者 false 。例如： `if(42 > 3, true, false)`。
* 基本表达式。

## 编写 HQL 过滤条件

假设数据集中有一个 `price` 数字类型的字段，想要过滤值大于 20 的数据，那么可以编写如下 HQL 过滤条件：

```js
where = [
    {
        "kind": "function",
        "op": ">",
        "args": [
            {
                "kind":"field",
                "op": "price",
            },
            {
                "kind": "constant",
                "op": 20
            }
        ]
    }
]
```

当然, 也可以缩写成:

```js
where = [
    {
        "kind": "formula",
        "op": "{price} > 20"
    }
]
```

假设数据集中有一个 `time` 日期类型的字段，想要过滤时间大于 2018-12-31 的数据，那么可以编写如下 HQL 过滤条件：

```js
where = [
  {
    "kind": "function",
    "op": ">",
    "args": [
      "time",
      {
        "kind":"constant",
        "op":"2018-12-31",
        "type": "date"
      }
    ]
  }
]
```

或者可以使用 formula 简写为

```js
where = [
    {
        "kind": "formula",
        "op": "{time} > '2018-12-31'"
    }
]
```

HQL 的函数和运算符非常丰富，可以满足各种复杂的过滤条件。具体的函数可以参考 [HQL 函数列表](https://api.hengshi.com/function_reference.html)。