覆盖查询参数

当你需要根据实际场景修改嵌入仪表盘或者嵌入图表的查询条件时，你可以通过在 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://data.bytedance.net/aeolus/#/external/dashboard/247931?appId=1001028&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://data.bytedance.net/aeolus"        dashboardId="247931"        appId="1001028"        query={`OrderDate between '20210101' and '20210301' and Profit >= 100`}      />    );  }} ReactDOM.render(<BIComponent />, document.querySelector("body"));

完整示例

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

https://data.bytedance.net/aeolus/#/dashboard/247931?appId=1001028

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

示例一

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

该配置表示查询 Category 为 Furniture，且 Region 为 Central 或 South 的数据。
你可以复制如下链接地址并在浏览器访问进行体验。

https://data.bytedance.net/aeolus/#/dashboard/247931?appId=1001028&query=Category = 'Furniture' and Region in ('Central','South')

示例二

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

该配置表示查询 Category 不为 Furniture，且 ShipMode 为 First Class，且 ProductName 包含 Desktop 的数据。
你可以复制如下链接地址并在浏览器访问进行体验。

https://data.bytedance.net/aeolus/#/dashboard/247931?appId=1001028&query=Category != 'Furniture' and ShipMode = 'First Class' and ProductName like '%Desktop%'

示例三

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

该配置表示查询 OrderDate 在 2021-01-01 与 2021-03-01之间，且 Profit 大于 100的数据。
你可以复制如下链接地址并在浏览器访问进行体验。

https://data.bytedance.net/aeolus/#/dashboard/247931?appId=1001028&query=OrderDate between '20210101' and '20210301' and Profit >= 100

配置规则

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

单个查询语句语法

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

field (查询组件名称)

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

• 当field名称为纯数字时，如123，需要用方括号将其括起，如：[123]
• 当field名称中存在特殊字符时(除去中英文/数字/下划线之外的其他字符，如$test filter包含美元符和空格符)，需要用方括号将其括起，如：[$test filter]
• 当field名称中存在特殊字符需要用方括号将其括起，并且field名称本身也包含[或]方符号时，需要使用\识别，如名称为test [demo] filter包含方括号和空格符，在语句中则可以这样表示：[test \[demo\] filter]

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: 配置项，非必传参数，不传时以默认值为准，具体信息如下

  	说明	取值列表
  unit	单位(默认值"day")	"minute"(分钟) 、 "hour"(小时) 、 "day"(天) 、 "week"(周) 、 "month"(月) 、 "year"(年) 、 "bimonthly"(双月) 、 "quarter"(季)
  offset	时间偏移单位(默认值-1)	-1(不包含当前时间单位周期) 、 0(包含当前时间单位周期)（例如：unit 取值为为week，则 offset 为-1 意为不包含本周，offset 为 0 意为包含本周）
  until	截止到(默认"yesterday")	"now"(此时此刻) 、 "yesterday"(昨天) 、 "today"(今天)、"periodEnd"(根据当前时间单位截止到该单位周期末)（例如：unit 取值为为week，则 until 取periodEnd意为截止到本周末，注意：until 仅当 offset 取值为 0 时赋值才有意义）

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(后一天)
  
  【注意】函数中的options为 json，因此字符串需要用""括起。

清空查询函数

clear

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