---
order: 5
navTitle: 组件数据集
---
# 组件数据集

组件数据集描述组件如何发起数据查询。

通常，只有查询类组件才需要配置组件数据集，如柱形图、列表等，下拉框、按钮、文本等则无需配置组件数据集。一个组件通常只有一个数据集。

和页面的查询数据集类似，组件数据集可以定义单行或多行数据集，查询明细或分组统计。一个数据集的查询结果对应一个`DataView`，`IVisualComponent`使用`DataView`渲染组件数据。

组件配置`properties`中定义的属性默认在全局单行数据集或上级多行数据集中查询和计算。例如：

1. 画布中的按钮，标题属性在全局单行数据集计算。
2. 浮动面板中的按钮，标题属性在浮动面板的多行数据集中计算，因为每一行的按钮标题计算结果可能不同。

组件也可以在`datasets`中配置自己的数据集，并定义组件中的哪些属性在数据集中查询和计算。以柱形图为例：

1. 柱形图按数据区的`x`分组，按`y`选择数据。
2. 柱形图的`标题`和`显示`属性作为图形属性在上级数据集中计算。

![柱形图配置](../../images/component-datasets-bar.png "=479x500")

组件数据集支持多种配置，一个组件可以配置多个数据集。组件数据集包含如下配置：

- `conditions`，查询条件
- `single`，单行统计查询
- `table`，列表查询
- `group`，分组查询
- `matrix`，交叉表查询
- `query`，自定义查询
- `queryTotal`，是否查询合计行
- `paging`，是否分页
- `pageSize`，分页大小
- `expand`，分组属性是否可按层次展开
- `queryTotalRowCount`，是否查询总行数

```json
{
    "datasets": [{
        "conditions": [...],
        "single": {...},
        "table": {...},
        "group": {...},
        "matrix": {...},
        "queryTotal": false,
        "paging": false,
        "pageSize": 10,
        "expand": false,
        "queryTotalRowCount": false,
        "query": {...}
    }],
    "dataDefinitions": {...},
    "marks": [...]
}
```

:::tip 安全提示

组件数据集约束了组件能够发起的查询，在查看界面中，用户无法越过组件配置和页面设计。以柱形图为例，当用户拖入`销售单位`到`X`，`销售数量`字段到`Y`，那么查看界面中柱形图就只会发起按`销售单位`分组，选择`销售数量`的查询，无法通过修改ajax参数等方式越过该限制。
:::

## dataset

### conditions

`conditions`用于确定查询发起的条件。可以定义多组条件，当尝试拖入属性栏数据区的字段满足`conditions`中定义的条件时，字段才被允许放入。

在条件中，针对一个数据区可以指定允许放入字段的最大和最小数量，如果没有指定，则可以放入任意数量的字段。当所有条件都不满足时，不发起查询。

![数据区](../../images/component-datasets-datadefinitions.png "=200x218")

```json
{
    "conditions": [{
        "x": {
            "min": 1,
            "max": 1
        },
        "y": {
            "min": 1
        }
    }, {
        "x": {
            "min": 2,
            "max": 2
        },
        "y": {
            "min": 1,
            "max": 1
        }
    }]
}
```

- `max`，允许放入字段的最大个数。如果未指定则可以放入任意个数的字段。
- `min`，允许放入字段的最小个数。如果未指定则不放入字段也可以发起查询。

### single

单行统计查询。拖入维度时会被转换为度量。通常用于KPI等指标查看类型的组件。

*示例*

```json
{
    "dataDefinitions": {
        "measures": {
            "kind": "measure",
            "preferredTypes": ["number"]
        }
    },
    "datasets": [{
        //至多拖入2个字段
        "conditions": [{
            "measures": {
                "max": 2
            }
        }],
        "single": "measures"
    }]
}
```

### table

列表查询。拖入的字段查询明细数据。通常用于列表等明细查询组件。

*示例*

```json
{
    "dataDefinitions": {
        "columns": {}
    },
    "datasets": [{
        //至少拖入一个字段
        "conditions": [{
            "columns": {
                "min": 1
            }
        }],
        "table": {
            "name": "columns"
        }
    }]
}
```

### group

分组查询。

- `group`，分组的字段。
- `select`，选择的字段。

*示例*

```json
{
    "dataDefinitions": {
        "dimensions": {
            "kind": "dimension"
        },
        "measures": {
            "kind": "measure"
        }
    },
    "datasets": [{
        //至少拖入一个至多拖入两个维度，至少拖入一个度量
        "conditions": [{
            "dimensions": {
                "min": 1,
                "max": 2
            },
            "measures": {
                "min": 1
            }
        }],
        "group": {
            "group": ["dimensions"],
            "select": ["measures"]
        }
    }]
}
```

### matrix

交叉表查询。

- `rowGroup`，行分组的字段。
- `colGroup`，列分组的字段。
- `select`，选择的字段。

*示例*

```json
{
    "dataDefinitions": {
        "row": {
            "kind": "dimension"
        },
        "col": {
            "kind": "dimension"
        },
        "measures": {
            "kind": "measure"
        }
    },
    "datasets": [{
        "conditions": [{
            "row": {
                "min": 1
            },
            "col": {
                "min": 1
            },
            "measures": {
                "min": 1
            }
        }],
        "matrix": {
            "rowGroup": ["row"],
            "colGroup": ["col"],
            "select": ["measures"]
        }
    }]
}
```

### queryTotal

是否查询合计行，默认为`false`，可以指定一个属性控制是否查询合计的值。如果有多个分组字段，则每一级都查询合计。

*示例*

```json
{
    "datasets": [{
        // 需要查询合计行
        "queryTotal": true
    }]
}
```

```json
{
    "datasets": [{
        // 表示是否需要查询合计行由`queryTotalEnable`属性控制
        "queryTotal": "queryTotalEnable"
    }]
}
```

### paging

是否分页，默认为`false`，可以指定哪一个属性控制`paging`的值。

*示例*

```json
{
    "datasets": [{
        // 需要分页
        "paging": true
    }]
}
```

```json
{
    "datasets": [{
        // 表示是否需要分页由`pagingEnable`属性控制
        "paging": "pagingEnable"
    }]
}
```

### pageSize

分页大小，默认为`10`，可以指定哪一个属性控制`pageSize`的值。

*示例*

```json
{
    "datasets": [{
        // 分页大小为100
        "pageSize": 100
    }]
}
```

```json
{
    "datasets": [{
        // 表示分页大小由`pageSize`属性控制
        "pageSize": "pageSize"
    }]
}
```

### expand

分组属性是否可按层次展开，默认为`false`，可以指定哪一个属性控制`expand`的值。

*示例*

```json
{
    "datasets": [{
        // 分组属性需要按层次展开
        "expand": true
    }]
}
```

```json
{
    "datasets": [{
        // 表示是否需要按层次展开由`expandEnable`属性控制
        "expand": "expandEnable"
    }]
}
```

### queryTotalRowCount

是否查询总行数，默认为false，可以指定哪一个属性控制`queryTotalRowCount`的值。

*示例*

```json
{
    "datasets": [{
        // 需要查询总行数
        "queryTotalRowCount": true
    }]
}
```

```json
{
    "datasets": [{
        // 表示是否查询总行数由`queryTotalRowCountEnable`属性控制
        "queryTotalRowCount": "queryTotalRowCountEnable"
    }]
}
```

### query

自定义查询。当组件需要自己构造查询，但又不希望使用数据区的属性面板时，可以采用自定义查询的方式定义如何发起查询。

例如SuperPage中的地图图层、列表、浮动面板等，这些组件采用了和仪表板数据区不同的数据集定义方式，无法使用`数据区`的配置方式，需要配置自定义查询。

*配置*

- `datasetProperty`，指定查询要查询的数据集属性名，通常是`dataset`属性。
- `atomicQuery`，是否明细查询，默认为`true`。设置为`false`时表示分组查询，可以指定一个[条件表达式](../../references/component-conditionexp.md)，用于动态控制。
- `groupProperty`，分组属性设置，可以指定单个或多个分组属性。设置`groupProperty`时`atomicQuery`会被默认设置为`false`。
- `dimOption`，补全维项设置。
- `properties`，当前查询包含的属性，没有指定的属性会默认放到当前组件的上级组件构造的查询中。

系统中配置自定义查询的组件通常有两类：

1. 组件上配置了数据集和相关查询属性，查询属性在组件数据集中发起查询，其它属性加入到上级数据集中。大部分组件都属于这一类，如下拉框、图层等。
2. 组件上配置了数据集，组件有下级子组件，子组件上配置了查询属性，查询属性在组件数据集中发起查询，其它属性加入到上级数据集中。如列表、浮动面板等。

#### 配置数据集和查询字段

以系统内置的区块图层为例：

1. 区块图层自己发起查询，配置了位置属性，按该属性分组，查询`提示信息`属性和`交互`。

```json
{
    "datasets": [
        {
            "query": {
                "groupProperty": ["locationField"],
                "actions": true,// 指定组件上的交互在customQuery中计算
                "properties": {
                    "basic": ["@tooltip"]
                }
            }
        }
    ]
}
```

#### 配置数据集和子组件

配置数据集和子组件时，组件上的属性默认会加入到上级数据集，子组件中查询属性默认加入到上级组件构造的数据集，如果不需要加入到上级组件构造的数据集，需要配置`excludeProperties`。

以系统内置的列表组件为例：

1. 列表组件以`dataset`属性作为数据集，设置了`hierarchy`时按`hierarchy`选择的层次展开数据，列表自身的属性默认加入到上级数据集。
2. 列表子组件中查询属性默认加入到列表构造的数据集中，列的`visibleCondition`属性需要加到列表的上级数据集，需要配置`excludeProperties`。

```json
{
    "list":{
        "datasets": [{
            "query": {
                "datasetProperty": "dataset",
                "atomicQuery": "hierarchy != null",
                "groupProperty": "hierarchy",
                "queryTotalRowCountProperty": "totalCountVisible"
            }
        }]
    }
}
```

列上的属性默认是加在列表的组件数据集中查询的，但是列的`visibleCondition`属性不能在列表构造的数据集中查询，此时需要配置`excludeProperties`，配置后此属性会放到列表的上级组件构造的数据集中计算。

```json
{
    "column": {
        "parentDataset": {
            "actions": true, // 指定列上的交互在列表的数据集中查询和计算
            "excludeProperties": {
                "basic": ["visibleCondition"]
            }
        }
    }
}
```

## dataDefinitions

`dataDefinitions`用于定义数据区属性。每一个数据区都可以拖入字段或输入表达式。当使用`group`、`table`和`single`时，需要结合`dataDefinitions`配置。

设计器属性面板中配置的数据区属性[dataDefinition](../../references/component-ppteditor.md#dataDefinition)会使用该配置生成界面。

`dataDefinitions`支持的配置属性如下：

- `name`，名称
- `kind`，允许拖入字段的类别，不指定时默认为`dimensionOrMeasure`
  - `dimension`，维度
  - `measure`，度量
  - `dimensionOrMeasure`，维度或度量
- `preferredTypes`，支持的字段数据类型数组
  - `string`，字符型
  - `date`，日期型
  - `number`，数值型
  - `geoType`，地理角色
- `markable`，是否支持标记，有且只能有1个数据区配置为`true`

以系统内置的柱形图为例，数据区`x`可以拖入维度；数据区`y`可以拖入指标且可以被标记，配置如下：

```json
{
    "dataDefinitions": {
        "x": {
            "kind": "dimension"
        },
        "y": {
            "kind": "measure",
            "markable": true
        }
    }
}
```

## marks

支持的标记类型。在数据区配置`markable`为true表示标记该数据区中的字段；否则表示对组件进行标记。

支持的标记类型：

- `color`，颜色标记
- `shape`，形状标记
- `size`，大小标记
- `label`，标签
- `tooltip`，提示信息
- `lob`，其它

以系统内置的柱形图配置为例：

```json
{
    "marks": ["color", "shape", "size", "label", "tooltip", "lob"]
}
```

标记支持配置：

- `kind`，允许拖入字段的类别，不指定时默认为`dimensionOrMeasure`
  - `dimension`，维度
  - `measure`，度量
  - `dimensionOrMeasure`，维度或度量
- `preferredTypes`，支持的字段数据类型数组
  - `string`，字符型
  - `date`，日期型
  - `number`，数值型
  - `geoType`，地理角色
- `properties`，自定义的[属性栏配置](../../references/component-ppteditor.md)