* Update VEGA docs for v8.0 * Update docs/user/dashboard/vega-reference.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
504 lines
17 KiB
Text
504 lines
17 KiB
Text
[[vega-reference]]
|
|
==== Vega reference
|
|
|
|
Learn more about {kib} extension, additional *Vega* resources, and examples.
|
|
|
|
[float]
|
|
[[reference-for-kibana-extensions]]
|
|
===== Reference for {kib} extensions
|
|
|
|
{kib} has extended Vega and Vega-Lite with extensions that support:
|
|
|
|
* Automatic sizing
|
|
* Default theme to match {kib}
|
|
* Writing {es} queries using the time range and filters from dashboards
|
|
* experimental[] Using the Elastic Map Service in Vega maps
|
|
* Additional tooltip styling
|
|
* Advanced setting to enable URL loading from any domain
|
|
* Debugging support using the {kib} inspector or browser console
|
|
* (Vega only) Expression functions which can update the time range and dashboard filters
|
|
|
|
[float]
|
|
[[vega-sizing-and-positioning]]
|
|
====== Automatic sizing
|
|
|
|
Most users will want their Vega visualizations to take the full available space, so unlike
|
|
Vega examples, `width` and `height` are not required parameters in {kib} because your
|
|
spec will be merged with the default {kib} settings in most cases:
|
|
|
|
```
|
|
autosize: {
|
|
type: fit
|
|
contains: padding
|
|
}
|
|
width: container
|
|
height: container
|
|
```
|
|
|
|
These default settings are *not* applied if:
|
|
|
|
* <<vega-with-a-map, Your spec uses `type=map`>>
|
|
* Your spec is Vega-Lite and contains a facet, row, column, repeat, or concat operator. In these
|
|
cases, providing `width` and `height` will affect the child size.
|
|
|
|
To set the width or height manually, set `autosize: none` and provide the exact pixel sizes, including
|
|
padding for the title, legend and axes.
|
|
|
|
```
|
|
autosize: none
|
|
width: 600
|
|
height: 200
|
|
padding: {
|
|
top: 20
|
|
bottom: 20
|
|
left: 55
|
|
right: 150
|
|
}
|
|
```
|
|
|
|
To learn more, read about
|
|
https://vega.github.io/vega/docs/specification/#autosize[Vega autosize]
|
|
and https://vega.github.io/vega-lite/docs/size.html[Vega-Lite autosize].
|
|
|
|
NOTE: Autosize in Vega-Lite has https://vega.github.io/vega-lite/docs/size.html#limitations[several limitations]
|
|
which can affect the height and width of your visualization, but these limitations do not exist in Vega.
|
|
If you need full control, convert your spec to Vega using the <<vega-browser-debugging-console, browser console>>
|
|
`VEGA_DEBUG.vega_spec` output.
|
|
To disable these warnings, you can <<vega-additional-configuration-options, add extra options to your spec>>.
|
|
|
|
[float]
|
|
[[vega-theme]]
|
|
====== Default theme to match {kib}
|
|
|
|
{kib} registers a default https://vega.github.io/vega/docs/schemes/[Vega color scheme]
|
|
with the id `elastic`, and sets a default color for each `mark` type.
|
|
Override it by providing a different `stroke`, `fill`, or `color` (Vega-Lite) value.
|
|
|
|
[float]
|
|
[[vega-queries]]
|
|
====== Writing {es} queries in Vega
|
|
|
|
{kib} extends the Vega https://vega.github.io/vega/docs/data/[data] elements
|
|
with support for direct {es} queries specified as `url`.
|
|
|
|
{kib} is **unable to support dynamically loaded data**,
|
|
which would otherwise work in Vega. All data is fetched before it's passed to
|
|
the Vega renderer.
|
|
|
|
To define an {es} query in Vega, set the `url` to an object. {kib} parses
|
|
the object looking for special tokens that allow your query to integrate with {kib}.
|
|
|
|
Tokens include the following:
|
|
|
|
* `%context%: true`: Set at the top level, and replaces the `query` section with filters from dashboard
|
|
* `%timefield%: <name>`: Set at the top level, integrates the query with the dashboard time filter
|
|
* `{%timefilter%: true}`: Replaced by an {es} range query with upper and lower bounds
|
|
* `{%timefilter%: "min" | "max"}`: Replaced only by the upper or lower bounds
|
|
* `{%timefilter: true, shift: -1, unit: 'hour'}`: Generates a time range query one hour in the past
|
|
* `{%autointerval%: true}`: Replaced by the string which contains the automatic {kib} time interval, such as `1h`
|
|
* `{%autointerval%: 10}`: Replaced by a string which is approximately dividing the time into 10 ranges, allowing
|
|
you to influence the automatic interval
|
|
* `"%dashboard_context-must_clause%"`: String replaced by object containing filters
|
|
* `"%dashboard_context-filter_clause%"`: String replaced by an object containing filters
|
|
* `"%dashboard_context-must_not_clause%"`: String replaced by an object containing filters
|
|
|
|
NOTE: Vega supports the `interval` parameter, which is unsupported {es} 8.0.0 and later. To use intervals, use `fixed_interval` or `calendar_interval` instead.
|
|
|
|
For example, the following query counts the number of documents in a specific index:
|
|
|
|
[source,yaml]
|
|
----
|
|
// An object instead of a string for the URL value
|
|
// is treated as a context-aware Elasticsearch query.
|
|
url: {
|
|
// Specify the time filter.
|
|
%timefield%: @timestamp
|
|
// Apply dashboard context filters when set
|
|
%context%: true
|
|
|
|
// Which indexes to search
|
|
index: kibana_sample_data_logs
|
|
// The body element may contain "aggs" and "query" keys
|
|
body: {
|
|
aggs: {
|
|
time_buckets: {
|
|
date_histogram: {
|
|
// Use date histogram aggregation on @timestamp field
|
|
field: @timestamp <1>
|
|
// interval value will depend on the time filter
|
|
// Use an integer to set approximate bucket count
|
|
interval: { %autointerval%: true }
|
|
// Make sure we get an entire range, even if it has no data
|
|
extended_bounds: {
|
|
min: { %timefilter%: "min" }
|
|
max: { %timefilter%: "max" }
|
|
}
|
|
// Use this for linear (e.g. line, area) graphs
|
|
// Without it, empty buckets will not show up
|
|
min_doc_count: 0
|
|
}
|
|
}
|
|
}
|
|
// Speed up the response by only including aggregation results
|
|
size: 0
|
|
}
|
|
}
|
|
----
|
|
|
|
<1> `@timestamp` — Filters the time range and breaks it into histogram
|
|
buckets.
|
|
|
|
The full result includes the following structure:
|
|
|
|
[source,yaml]
|
|
----
|
|
{
|
|
"aggregations": {
|
|
"time_buckets": {
|
|
"buckets": [{
|
|
"key_as_string": "2015-11-30T22:00:00.000Z",
|
|
"key": 1448920800000,<1>
|
|
"doc_count": 28
|
|
}, {
|
|
"key_as_string": "2015-11-30T23:00:00.000Z",
|
|
"key": 1448924400000, <1>
|
|
"doc_count": 330
|
|
}, ...
|
|
----
|
|
|
|
<1> `"key"` — The unix timestamp you can use without conversions by the
|
|
Vega date expressions.
|
|
|
|
For most visualizations, you only need the list of bucket values. To focus on
|
|
only the data you need, use `format: {property: "aggregations.time_buckets.buckets"}`.
|
|
|
|
Specify a query with individual range and dashboard context. The query is
|
|
equivalent to `"%context%": true, "%timefield%": "@timestamp"`,
|
|
except that the time range is shifted back by 10 minutes:
|
|
|
|
[source,yaml]
|
|
----
|
|
{
|
|
body: {
|
|
query: {
|
|
bool: {
|
|
must: [
|
|
// This string will be replaced
|
|
// with the auto-generated "MUST" clause
|
|
"%dashboard_context-must_clause%"
|
|
{
|
|
range: {
|
|
// apply timefilter (upper right corner)
|
|
// to the @timestamp variable
|
|
@timestamp: {
|
|
// "%timefilter%" will be replaced with
|
|
// the current values of the time filter
|
|
// (from the upper right corner)
|
|
"%timefilter%": true
|
|
// Only work with %timefilter%
|
|
// Shift current timefilter by 10 units back
|
|
shift: 10
|
|
// week, day (default), hour, minute, second
|
|
unit: minute
|
|
}
|
|
}
|
|
}
|
|
]
|
|
must_not: [
|
|
// This string will be replaced with
|
|
// the auto-generated "MUST-NOT" clause
|
|
"%dashboard_context-must_not_clause%"
|
|
]
|
|
filter: [
|
|
// This string will be replaced
|
|
// with the auto-generated "FILTER" clause
|
|
"%dashboard_context-filter_clause%"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
NOTE: When using `"%context%": true` or defining a value for `"%timefield%"` the body cannot contain a query. To customize the query within the VEGA specification (e.g. add an additional filter, or shift the timefilter), define your query and use the placeholders as in the example above. The placeholders will be replaced by the actual context of the dashboard or visualization once parsed.
|
|
|
|
The `"%timefilter%"` can also be used to specify a single min or max
|
|
value. The date_histogram's `extended_bounds` can be set
|
|
with two values - min and max. Instead of hardcoding a value, you may
|
|
use `"min": {"%timefilter%": "min"}`, which will be replaced with the
|
|
beginning of the current time range. The `shift` and `unit` values are
|
|
also supported. The `"interval"` can also be set dynamically, depending
|
|
on the currently picked range: `"interval": {"%autointerval%": 10}` will
|
|
try to get about 10-15 data points (buckets).
|
|
|
|
[float]
|
|
[[vega-esmfiles]]
|
|
===== Access Elastic Map Service files
|
|
|
|
experimental[] Access the Elastic Map Service files via the same mechanism:
|
|
|
|
[source,yaml]
|
|
----
|
|
url: {
|
|
// "type" defaults to "elasticsearch" otherwise
|
|
%type%: emsfile
|
|
// Name of the file, exactly as in the Region map visualization
|
|
name: World Countries
|
|
}
|
|
// The result is a geojson file, get its features to use
|
|
// this data source with the "shape" marks
|
|
// https://vega.github.io/vega/docs/marks/shape/
|
|
format: {property: "features"}
|
|
----
|
|
|
|
[float]
|
|
[[vega-with-a-map]]
|
|
==== Vega with a Map
|
|
|
|
experimental[] To enable *Maps*, the graph must specify `type=map` in the host configuration:
|
|
|
|
[source,yaml]
|
|
----
|
|
{
|
|
"config": {
|
|
"kibana": {
|
|
"type": "map",
|
|
|
|
// Initial map position
|
|
"latitude": 40.7, // default 0
|
|
"longitude": -74, // default 0
|
|
"zoom": 7, // default 2
|
|
|
|
// Defaults to 'true', disables the base map layer.
|
|
"mapStyle": false,
|
|
|
|
// When 'mapStyle' is 'undefined' or 'true', sets the EMS-layer for the map.
|
|
// May either be: "road_map", "road_map_desaturated", "dark_map".
|
|
// If 'emsTileServiceId' is 'undefined', it falls back to the auto-switch-dark-light behavior.
|
|
"emsTileServiceId": "road_map",
|
|
|
|
// default 0
|
|
"minZoom": 5,
|
|
|
|
// defaults to the maximum for the given style,
|
|
// or 25 when base is disabled
|
|
"maxZoom": 13,
|
|
|
|
// Defaults to 'true', shows +/- buttons to zoom in/out
|
|
"zoomControl": false,
|
|
|
|
// Defaults to 'false', disables mouse wheel zoom. If set to
|
|
// 'true', map may zoom unexpectedly while scrolling dashboard
|
|
"scrollWheelZoom": false,
|
|
|
|
// When false, repaints on each move frame.
|
|
// Makes the graph slower when moving the map
|
|
"delayRepaint": true, // default true
|
|
}
|
|
},
|
|
/* the rest of Vega JSON */
|
|
}
|
|
----
|
|
|
|
The visualization automatically injects a `"projection"`, which you can use to
|
|
calculate the position of all geo-aware marks.
|
|
Additionally, you can use `latitude`, `longitude`, and `zoom` signals.
|
|
These signals can be used in the graph, or can be updated to modify the
|
|
position of the map.
|
|
|
|
experimental[] You can use the *Vega* https://vega.github.io/vega/docs/data/[data] element to access https://www.elastic.co/elastic-maps-service[Elastic Maps Service (EMS)] vector shapes of administrative boundaries in your Vega map by setting `url.data` to `emsFile`:
|
|
|
|
[source,yaml]
|
|
----
|
|
url: {
|
|
// "type" defaults to "elasticsearch" otherwise
|
|
%type%: emsfile
|
|
// Name of the file, exactly as in the Region map visualization
|
|
name: World Countries
|
|
}
|
|
// The result is a geojson file, get its features to use
|
|
// this data source with the "shape" marks
|
|
// https://vega.github.io/vega/docs/marks/shape/
|
|
format: {property: "features"}
|
|
----
|
|
|
|
[float]
|
|
[[vega-tooltip]]
|
|
====== Additional tooltip styling
|
|
|
|
{kib} has installed the https://vega.github.io/vega-lite/docs/tooltip.html[Vega tooltip plugin],
|
|
so tooltips can be defined in the ways documented there. Beyond that, {kib} also supports
|
|
a configuration option for changing the tooltip position and padding:
|
|
|
|
```js
|
|
{
|
|
config: {
|
|
kibana: {
|
|
tooltips: {
|
|
position: 'top',
|
|
padding: 15,
|
|
textTruncate: true,
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
[float]
|
|
[[vega-url-loading]]
|
|
====== Enable URL loading from any domain
|
|
|
|
*Vega* can load data from any URL. To enable, set `vis_type_vega.enableExternalUrls: true` in `kibana.yml`,
|
|
then restart {kib}.
|
|
|
|
[float]
|
|
[[vega-inspector]]
|
|
====== Vega Inspector
|
|
Use the contextual *Inspect* tool to gain insights into different elements.
|
|
|
|
[float]
|
|
[[inspect-elasticsearch-requests]]
|
|
====== Inspect {es} requests
|
|
|
|
*Vega* uses the {ref}/search-search.html[{es} search API] to get documents and aggregation
|
|
results from {es}. To troubleshoot these requests, click *Inspect*, which shows the most recent requests.
|
|
In case your specification has more than one request, you can switch between the views using the *View* dropdown.
|
|
|
|
[role="screenshot"]
|
|
image::images/vega_tutorial_inspect_requests.png[]
|
|
|
|
[float]
|
|
[[vega-debugging]]
|
|
===== Vega debugging
|
|
|
|
With the *Vega debug* view, you can inspect the *Data sets* and *Signal Values* runtime data.
|
|
|
|
The runtime data is read from the
|
|
https://vega.github.io/vega/docs/api/debugging/#scope[runtime scope].
|
|
|
|
[role="screenshot"]
|
|
image::images/vega_tutorial_inspect_data_sets.png[]
|
|
|
|
To debug more complex specs, access to the `view` variable. For more information, refer to
|
|
the <<vega-browser-debugging-console, Vega browser debugging process>>.
|
|
|
|
[float]
|
|
[[asking-for-help-with-a-vega-spec]]
|
|
====== Asking for help with a Vega spec
|
|
|
|
Because of the dynamic nature of the data in {es}, it is hard to help you with
|
|
*Vega* specs unless you can share a dataset. To do this, click *Inspect*, select the *Vega debug* view,
|
|
then select *Spec*.
|
|
|
|
[role="screenshot"]
|
|
image::images/vega_tutorial_getting_help.png[]
|
|
|
|
To copy the response, click *Copy to clipboard*. Paste the copied data to
|
|
https://gist.github.com/[gist.github.com], possibly with a .json extension. Use the [raw] button,
|
|
and share that when asking for help.
|
|
|
|
[float]
|
|
[[vega-browser-debugging-console]]
|
|
===== Browser debugging console
|
|
|
|
experimental[] Use browser debugging tools (for example, F12 or Ctrl+Shift+J in Chrome) to
|
|
inspect the `VEGA_DEBUG` variable:
|
|
|
|
* `view` — Access to the Vega View object. See https://vega.github.io/vega/docs/api/debugging/[Vega Debugging Guide]
|
|
on how to inspect data and signals at runtime. For Vega-Lite,
|
|
`VEGA_DEBUG.view.data('source_0')` gets the pre-transformed data, and `VEGA_DEBUG.view.data('data_0')`
|
|
gets the encoded data. For Vega, it uses the data name as defined in your Vega spec.
|
|
|
|
* `vega_spec` — Vega JSON graph specification after some modifications by {kib}. In case
|
|
of Vega-Lite, this is the output of the Vega-Lite compiler.
|
|
|
|
* `vegalite_spec` — If this is a Vega-Lite graph, JSON specification of the graph before
|
|
Vega-Lite compilation.
|
|
|
|
[float]
|
|
[[vega-expression-functions]]
|
|
===== (Vega only) Expression functions which can update the time range and dashboard filters
|
|
|
|
{kib} has extended the Vega expression language with these functions.
|
|
These functions will trigger new data to be fetched, which by default will reset Vega signals.
|
|
To keep signal values set `restoreSignalValuesOnRefresh: true` in the Vega config.
|
|
|
|
```js
|
|
/**
|
|
* @param {object} query Elastic Query DSL snippet, as used in the query DSL editor
|
|
* @param {string} [index] as defined in Kibana, or default if missing
|
|
*/
|
|
kibanaAddFilter(query, index)
|
|
|
|
/**
|
|
* @param {object} query Elastic Query DSL snippet, as used in the query DSL editor
|
|
* @param {string} [index] as defined in Kibana, or default if missing
|
|
*/
|
|
kibanaRemoveFilter(query, index)
|
|
|
|
kibanaRemoveAllFilters()
|
|
|
|
/**
|
|
* Update dashboard time filter to the new values
|
|
* @param {number|string|Date} start
|
|
* @param {number|string|Date} end
|
|
*/
|
|
kibanaSetTimeFilter(start, end)
|
|
```
|
|
|
|
[float]
|
|
[[vega-additional-configuration-options]]
|
|
===== Additional configuration options
|
|
|
|
[source,yaml]
|
|
----
|
|
{
|
|
config: {
|
|
kibana: {
|
|
// Placement of the Vega-defined signal bindings.
|
|
// Can be `left`, `right`, `top`, or `bottom` (default).
|
|
controlsLocation: top
|
|
// Can be `vertical` or `horizontal` (default).
|
|
controlsDirection: vertical
|
|
// If true, hides most of Vega and Vega-Lite warnings
|
|
hideWarnings: true
|
|
// Vega renderer to use: `svg` or `canvas` (default)
|
|
renderer: canvas
|
|
// Defaults to 'false', restores Vega signal values on refresh
|
|
restoreSignalValuesOnRefresh: false
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
[float]
|
|
[[vega-notes]]
|
|
[[resources-and-examples]]
|
|
==== Resources and examples
|
|
|
|
To learn more about Vega and Vega-Lite, refer to the resources and examples.
|
|
|
|
[float]
|
|
[[vega-editor]]
|
|
===== Vega editor
|
|
The https://vega.github.io/editor/[Vega Editor] includes examples for Vega & Vega-Lite, but does not support any
|
|
{kib}-specific features like {es} requests and interactive base maps.
|
|
|
|
[float]
|
|
[[vega-lite-resources]]
|
|
===== Vega-Lite resources
|
|
* https://vega.github.io/vega-lite/tutorials/getting_started.html[Tutorials]
|
|
* https://vega.github.io/vega-lite/docs/[Docs]
|
|
* https://vega.github.io/vega-lite/examples/[Examples]
|
|
|
|
[float]
|
|
[[vega-resources]]
|
|
===== Vega resources
|
|
* https://vega.github.io/vega/tutorials/[Tutorials]
|
|
* https://vega.github.io/vega/docs/[Docs]
|
|
* https://vega.github.io/vega/examples/[Examples]
|
|
|
|
TIP: When you use the examples in {kib}, you may
|
|
need to modify the "data" section to use absolute URL. For example,
|
|
replace `"url": "data/world-110m.json"` with
|
|
`"url": "https://vega.github.io/editor/data/world-110m.json"`.
|