DataWind 支持通过 URL 参数覆盖嵌入仪表盘或图表的查询条件，实现自定义数据筛选效果。本文为您详细介绍 query 参数的语法规则和使用方法，帮助您灵活控制数据展示内容。

当你需要根据实际场景修改嵌入仪表盘或者嵌入图表的查询条件时，你可以通过在 URL 中传入查询配置以覆盖原有查询条件。

• 嵌入仪表盘时，你可以覆盖仪表盘的公共筛选器、查询容器中公共筛选器。请将对应的筛选字段添加为仪表盘的公共筛选器，使用筛选器名称进行匹配覆盖。
• 嵌入单个图表时，你可以覆盖图表筛选项。请在可视化查询模块为图表添加对应字段到筛选中，使用字段名称进行匹配覆盖。
• 如果希望在嵌入仪表盘时覆盖指定图表的筛选项，请将该筛选项添加为仪表盘的公共筛选器。

在 iframe 中使用

在 iframe 的 url 中传入 query 参数来配置覆盖筛选器。

import React from 'react'
import ReactDOM from 'react-dom'
import '@aeolus/sdk'
 
class BIComponent extends React.Component {
  render() {
    return (
      <iframe
        src={`https://console.volcengine.com/bi/datawind-open/#/external/dashboard/*****?appId=********&inline=true&query=OrderDate between '20210101' and '20210301' and Profit >= 100`}
      />
    )
  }
}
 
ReactDOM.render(<BIComponent />, document.querySelector('body'))

在 SDK 中使用

在 SDK 组件中，可以传入 query 参数来配置覆盖筛选器。

import React from 'react'
import ReactDOM from 'react-dom'
import '@aeolus/sdk'
 
class BIComponent extends React.Component {
  render() {
    return (
      <aeolus-dashboard
        urlPrefix="https://console.volcengine.com/bi/datawind-open"
        dashboardId="*****"
        appId="******"
        query={`OrderDate between '20210101' and '20210301' and Profit >= 100`}
      />
    )
  }
}
 
ReactDOM.render(<BIComponent />, document.querySelector('body'))

以下面的仪表盘链接为例，可以看到该仪表盘已经配置了 4 个公共筛选器 Category、ShipMode、Region、OrderDate。

https://console.volcengine.com/bi/datawind-open/#/dashboard/******?appId=*******

你或许已经注意到 ShipMode 和 OrderDate 与图表数据集字段并不一致，真实的数据集字段为 Ship Mode 和 Order Date。进行覆盖筛选器配置时，需要使用公共筛选器名称进行覆盖，而不是数据集字段。特别地，公共筛选器中不可以存在空格，否则在进行覆盖时无法识别。

示例一

&query=Category = 'Furniture' and Region in ('Central','South')

该配置表示查询 Category 为 Furniture，且 Region 为 Central 或 South 的数据。

示例二

&query=Category != 'Furniture' and ShipMode = 'First Class' and ProductName like '%Desktop%'

该配置表示查询 Category 不为 Furniture，且 ShipMode 为 First Class，且 ProductName 包含 Desktop 的数据。

示例三

&query=OrderDate between '20210101' and '20210301' and Profit >= 100

该配置表示查询 OrderDate 在 2021-01-01 与 2021-03-01之间，且 Profit 大于 100的数据。

完整的查询配置以&query=开头，由单个或多个查询语句组成。

单个查询语句语法

field op value scope?
每个查询语句的基本语法由field、op、value以及可选的scope构成：

field (查询组件名称)

嵌入仪表盘时为公共筛选器名称或查询容器中公共筛选器名称，嵌入图表时为图表上添加的筛选字段名称。
对应下图中，test则为该查询组件的名称：

op (查询操作符)

可以根据实际场景使用in、like等操作符，具体操作符清单见后文中的基本查询操作符。

value (查询值)

可以为数字或字符串。
如果查询值为字符串，需要使用单引号'*'包裹。如'Shanghai'。
多个值时需要用小括号括起，如('Jiangsu', 'Zhejiang')。
示例如下（当前查询组件名为 test）：
&query=test in ('北京','上海')

scope (可选项，指定查询范围)

当需要指定查询范围时，可以通过 scope 来指定，例如限制筛选器覆盖指定 sheet 页：
field op value scope sheetId = *

多个查询语句语法

当有多个查询语句，需通过and连接符连接，表示配置是且的关系。DataWind 不支持覆盖筛选器之间为或关系。
语法如下：
field1 op1 value1 and field2 op2 value2
如果遇到需要判断优先级的情况，可以使用圆括号()括起， 如 (test1 in ('Jiangsu', 'Zhejiang') scope sheetId = 123) and test2 like '%abc%'

查询操作符

基本查询操作符

日期/日期时间查询操作符

查询函数

日期/日期时间查询函数

对于部分日期类型的查询，我们还提供了最近、最近有数、高级时间等函数来描述这类较复杂的场景。
查询函数说明如下：

latestDate

用于描述动态日期-最近*天(周/月/双月/季度/年)。

• 语法

latestDate(field, data, options?)

• 示例

latestDate(field, 1)
latestDate(field, 2, {unit: "week", offset: 0, until: "periodEnd" })

• 参数说明

-- field: 查询组件名称
-- data: 动态日期取值
-- options: 配置项，非必传参数，不传时以默认值为准，具体信息如下

latestSyncDate

用于描述动态日期-最近有数*天(周/月/双月/季度/年)，仅支持分区字段。

• 语法

latestSyncDate(field, data, options?)

• 示例

latestSyncDate(field, 1)
latestSyncDate(field, 2, {unit: "week"})

• 参数说明

-- field: 查询组件名称
-- data: 动态日期取值
-- options: 配置项，非必传参数，不传时以默认值为准，具体信息如下：
unit 取值参考 latestDate。

advancedDate

用于用于描述高级日期-动态日期，需要结合 between、>=、<= 等操作符使用。

• 语法

advancedDate(data, options?)

• 示例

field between '2022-11-15' and advancedDate(1, {unit: "day", offset: -1})
field >= advancedDate(1, {unit: "day", offset: -1})

• 参数说明

-- data: 动态日期取值
-- options: 配置项，非必传参数，不传时以默认值为准，具体信息如下：

unit: 单位(默认值"day"),  offset: 时间偏移单位(默认值-1)

unit 取值参考 latestDate。
offset 取值列表：-1(前一天) 、 1(后一天)

Array 查询函数

arrayHas

数组函数，用于描述数组中包含某些元素。

• 语法

arrayHas(field, data)

• 示例

arrayHas(field, ('a', 'b'))

• 参数说明

-- field: 查询组件名称
-- data: 数组值

notArrayHas

数组函数，用于描述数组中不包含某些元素。

• 语法

notArrayHas(field, data)

• 示例

notArrayHas(field, ('a', 'b'))

• 参数说明

-- field: 查询组件名称
-- data: 数组值

清空查询函数

clear

如需要清空某查询组件，可以通过 clear 函数进行清空，语法如下：
clear(field)