mirror of
https://github.com/apache/zeppelin
synced 2026-05-24 09:38:26 +00:00
docs: Add doc for Transformation
This commit is contained in:
1ambda
parent
52db37bbad
commit
c510af171c
2 changed files with 275 additions and 1 deletions
|
|
@ -120,7 +120,8 @@
|
|||
<li class="title"><span><b>Helium Framework</b><span></li>
|
||||
<li><a href="{{BASE_PATH}}/development/writingzeppelinapplication.html">Writing Zeppelin Application (Experimental)</a></li>
|
||||
<li><a href="{{BASE_PATH}}/development/writingzeppelinspell.html">Writing Zeppelin Spell (Experimental)</a></li>
|
||||
<li><a href="{{BASE_PATH}}/development/writingzeppelinvisualization.html">Writing Zeppelin Visualization (Experimental)</a></li>
|
||||
<li><a href="{{BASE_PATH}}/development/writingzeppelinvisualization.html">Writing Zeppelin Visualization: Basic (Experimental)</a></li>
|
||||
<li><a href="{{BASE_PATH}}/development/writingzeppelinvisualization_transformation.html">Writing Zeppelin Visualization: Transformation (Experimental)</a></li>
|
||||
<li role="separator" class="divider"></li>
|
||||
<li class="title"><span><b>Advanced</b><span></li>
|
||||
<li><a href="{{BASE_PATH}}/install/virtual_machine.html">Zeppelin on Vagrant VM</a></li>
|
||||
|
|
|
|||
273
docs/development/writingzeppelinvisualization_transformation.md
Normal file
273
docs/development/writingzeppelinvisualization_transformation.md
Normal file
|
|
@ -0,0 +1,273 @@
|
|||
---
|
||||
layout: page
|
||||
title: "Transformations for Zeppelin Visualization (Experimental)"
|
||||
description: "Description for Transformations"
|
||||
group: development
|
||||
---
|
||||
<!--
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
-->
|
||||
{% include JB/setup %}
|
||||
|
||||
# Transformations for Zeppelin Visualization (Experimental)
|
||||
|
||||
<div id="toc"></div>
|
||||
|
||||
## Overview
|
||||
|
||||
Transformations
|
||||
|
||||
- **renders** setting which allows users to set columns and
|
||||
- **transforms** table rows according to the configured columns.
|
||||
|
||||
Zeppelin provides 4 types of transformations.
|
||||
|
||||
## 1. PassthroughTransformation
|
||||
|
||||
See [passthrough.js](https://github.com/apache/zeppelin/blob/master/zeppelin-web/src/app/tabledata/passthrough.js)
|
||||
|
||||
## 2. ColumnselectorTransformation
|
||||
|
||||
See [columnselector.js](https://github.com/apache/zeppelin/blob/master/zeppelin-web/src/app/tabledata/columnselector.js)
|
||||
|
||||
## 3. PivotTransformation
|
||||
|
||||
See [pivot.js](https://github.com/apache/zeppelin/blob/master/zeppelin-web/src/app/tabledata/pivot.js)
|
||||
|
||||
## 4. AdvancedTransformation
|
||||
|
||||
`AdvancedTransformation` has more detailed options while providing existing features of `PivotTransformation` and `ColumnselectorTransformation`
|
||||
|
||||
- multiple sub charts
|
||||
- configurable chart axes
|
||||
- parameter widgets: `input`, checkbox`, `option`, `textarea`
|
||||
- parsing parameters automatically based on their types
|
||||
- expand / fold axis and parameter panels
|
||||
- multiple transformation methods while supporting lazy converting
|
||||
- re-initialize the whole configuration based on spec hash.
|
||||
|
||||
### Spec
|
||||
|
||||
`AdvancedTransformation` requires `spec` which includes axis and parameter details for charts.
|
||||
|
||||
Let's create 2 sub-charts called `line` and `no-group`. Each sub chart can have different axis and parameter depending on their requirements.
|
||||
|
||||
<br/>
|
||||
|
||||
```js
|
||||
class AwesomeVisualization extends Visualization {
|
||||
constructor(targetEl, config) {
|
||||
super(targetEl, config)
|
||||
|
||||
const spec = {
|
||||
charts: {
|
||||
'line': {
|
||||
transform: { method: 'object', },
|
||||
sharedAxis: false, /** set if you want to share axes between sub charts, default is `false` */
|
||||
axis: {
|
||||
'xAxis': { dimension: 'multiple', axisType: 'key', },
|
||||
'yAxis': { dimension: 'multiple', axisType: 'aggregator'},
|
||||
'category': { dimension: 'multiple', axisType: 'group', },
|
||||
},
|
||||
parameter: {
|
||||
'xAxisUnit': { valueType: 'string', defaultValue: '', description: 'unit of xAxis', },
|
||||
'yAxisUnit': { valueType: 'string', defaultValue: '', description: 'unit of yAxis', },
|
||||
'lineWidth': { valueType: 'int', defaultValue: 0, description: 'width of line', },
|
||||
},
|
||||
},
|
||||
|
||||
'no-group': {
|
||||
transform: { method: 'object', },
|
||||
sharedAxis: false,
|
||||
axis: {
|
||||
'xAxis': { dimension: 'single', axisType: 'key', },
|
||||
'yAxis': { dimension: 'multiple', axisType: 'value', },
|
||||
},
|
||||
parameter: {
|
||||
'xAxisUnit': { valueType: 'string', defaultValue: '', description: 'unit of xAxis', },
|
||||
'yAxisUnit': { valueType: 'string', defaultValue: '', description: 'unit of yAxis', },
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
this.transformation = new AdvancedTransformation(config, spec)
|
||||
}
|
||||
|
||||
...
|
||||
|
||||
// `render` will be called whenever `axis` or `parameter` are changed
|
||||
render(data) {
|
||||
const { chart, parameter, column, transformer, } = data
|
||||
|
||||
if (chart === 'line') {
|
||||
const transformed = transformer()
|
||||
// draw line chart
|
||||
} else if (chart === 'no-group') {
|
||||
const transformed = transformer()
|
||||
// draw no-group chart
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
### Spec: `axis`
|
||||
|
||||
| Field Name | Available Values (type) | Description |
|
||||
| --- | --- | --- |
|
||||
|`dimension` | `single` | Axis can contains only 1 column |
|
||||
|`dimension` | `multiple` | Axis can contains multiple columns |
|
||||
|`axisType` | `key` | Column(s) in this axis will be used as `key` like in `PivotTransformation`. These columns will be served in `column.key` |
|
||||
|`axisType` | `aggregator` | Column(s) in this axis will be used as `value` like in `PivotTransformation`. These columns will be served in `column.aggregator` |
|
||||
|`axisType` | `group` | Column(s) in this axis will be used as `group` like in `PivotTransformation`. These columns will be served in `column.group` |
|
||||
|`axisType` | (string) | Any string value can be used here. These columns will be served in `column.custom` |
|
||||
|`valueType` | (string) | Describe the value type just for annotation |
|
||||
|`maxAxisCount` | (int) | The maximum column count that this axis can contains. (unlimited if `undefined`) |
|
||||
|
||||
<br/>
|
||||
|
||||
Here is an example.
|
||||
|
||||
```js
|
||||
axis: {
|
||||
'xAxis': { dimension: 'multiple', axisType: 'key', },
|
||||
'yAxis': { dimension: 'multiple', axisType: 'aggregator'},
|
||||
'category': { dimension: 'multiple', axisType: 'group', maxAxisCount: 2, valueType: 'string', },
|
||||
},
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
#### Spec: `sharedAxis`
|
||||
|
||||
If you set `sharedAxis: false` for sub charts, then their axes are persisted in global space (shared). It's useful for when you creating multiple sub charts sharing their axes but have different parameters. For example,
|
||||
|
||||
- `basic-column`, `stacked-column`, `percent-column`
|
||||
- `pie` and `donut`
|
||||
|
||||
<br/>
|
||||
|
||||
Here is an example.
|
||||
|
||||
```js
|
||||
const spec = {
|
||||
charts: {
|
||||
'column': {
|
||||
transform: { method: 'array', },
|
||||
sharedAxis: true,
|
||||
axis: { ... },
|
||||
parameter: { ... },
|
||||
},
|
||||
|
||||
'stacked': {
|
||||
transform: { method: 'array', },
|
||||
sharedAxis: true,
|
||||
axis: { ... }
|
||||
parameter: { ... },
|
||||
},
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
### Spec: `parameter`
|
||||
|
||||
| Field Name | Available Values (type) | Description |
|
||||
| --- | --- | --- |
|
||||
|`valueType` | `string` | Parameter which has string value |
|
||||
|`valueType` | `int` | Parameter which has int value |
|
||||
|`valueType` | `float` | Parameter which has float value |
|
||||
|`valueType` | `boolean` | Parameter which has boolean value used with `checkbox` widget usually |
|
||||
|`valueType` | `JSON` | Parameter which has JSON value used with `textarea` widget usually. `defaultValue` should be `""` (empty string). This ||`defaultValue` | (any) | Default value of this parameter. `JSON` type should have `""` (empty string) |
|
||||
|`description` | (string) | Description of this parameter. This value will be parsed as HTML for pretty output |
|
||||
|`widget` | `input` | Use [input](https://developer.mozilla.org/en/docs/Web/HTML/Element/input) widget. This is the default widget (if `widget` is undefined)|
|
||||
|`widget` | `checkbox` | Use [checkbox](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox) widget. |
|
||||
|`widget` | `textarea` | Use [textarea](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea) widget. |
|
||||
|`widget` | `option` | Use [select + option](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select) widget. This parameter should have `optionValues` field as well. |
|
||||
|`optionValues` | (Array<string>) | Available option values used with the `option` widget |
|
||||
|
||||
<br/>
|
||||
|
||||
Here is an example.
|
||||
|
||||
```js
|
||||
parameter: {
|
||||
// string type, input widget
|
||||
'xAxisUnit': { valueType: 'string', defaultValue: '', description: 'unit of xAxis', },
|
||||
|
||||
// boolean type, checkbox widget
|
||||
'inverted': { widget: 'checkbox', valueType: 'boolean', defaultValue: false, description: 'invert x and y axes', },
|
||||
|
||||
// string type, option widget with `optionValues`
|
||||
'graphType': { widget: 'option', valueType: 'string', defaultValue: 'line', description: 'graph type', optionValues: [ 'line', 'smoothedLine', 'step', ], },
|
||||
|
||||
// HTML in `description`
|
||||
'dateFormat': { valueType: 'string', defaultValue: '', description: 'format of date (<a href="https://docs.amcharts.com/3/javascriptcharts/AmGraph#dateFormat">doc</a>) (e.g YYYY-MM-DD)', },
|
||||
|
||||
// JSON type, textarea widget
|
||||
'yAxisGuides': { widget: 'textarea', valueType: 'JSON', defaultValue: '', description: 'guides of yAxis ', },
|
||||
```
|
||||
|
||||
<br/>
|
||||
|
||||
### Spec: `transform`
|
||||
|
||||
| Field Name | Available Values (type) | Description |
|
||||
| --- | --- | --- |
|
||||
|`method` | `object` | designed for rows requiring object manipulation |
|
||||
|`method` | `array` | designed for rows requiring array manipulation |
|
||||
|`method` | `drill-down` | designed for drill-down charts |
|
||||
|`method` | `raw` | will return the original `tableData.rows` |
|
||||
|
||||
<br/>
|
||||
|
||||
Whatever you specified as `transform.method`, the `transformer` value will be always function for lazy computation.
|
||||
|
||||
```js
|
||||
// advanced-transformation.util#getTransformer
|
||||
|
||||
if (transformSpec.method === 'raw') {
|
||||
transformer = () => { return rows; }
|
||||
} else if (transformSpec.method === 'array') {
|
||||
transformer = () => {
|
||||
...
|
||||
return { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Here is actual usage.
|
||||
|
||||
```js
|
||||
class AwesomeVisualization extends Visualization {
|
||||
constructor(...) { /** setup your spec */ }
|
||||
|
||||
...
|
||||
|
||||
// `render` will be called whenever `axis` or `parameter` are changed
|
||||
render(data) {
|
||||
const { chart, parameter, column, transformer, } = data
|
||||
|
||||
if (chart === 'line') {
|
||||
const transformed = transformer()
|
||||
// draw line chart
|
||||
} else if (chart === 'no-group') {
|
||||
const transformed = transformer()
|
||||
// draw no-group chart
|
||||
}
|
||||
}
|
||||
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Loading…
Reference in a new issue