091cece232
* add filter clause to es_query_parser.js * update tests to consider the filter clause * update docs to show the new filter clause Co-authored-by: Oleg Ivasenko <oleg.ivasenko@devolo.de>
355 lines
11 KiB
Plaintext
355 lines
11 KiB
Plaintext
[[vega-graph]]
|
|
== Vega
|
|
|
|
experimental[]
|
|
|
|
Build custom visualizations from multiple data sources using Vega
|
|
and Vega-Lite.
|
|
|
|
* *Vega* — A declarative format to create visualizations using JSON.
|
|
Generate interactive displays using D3.
|
|
|
|
* *Vega-Lite* — An easier format to use than Vega that enables more rapid
|
|
data analysis. Compiles into Vega.
|
|
|
|
For more information about Vega and Vega-Lite, refer to
|
|
<<vega-useful-links, Resources and examples>>.
|
|
|
|
[float]
|
|
[[create-vega-viz]]
|
|
=== Create Vega visualizations
|
|
|
|
You create Vega visualizations by using the text editor, which is
|
|
preconfigured with the options you need.
|
|
|
|
[role="screenshot"]
|
|
image::images/vega_lite_default.png[]
|
|
|
|
[float]
|
|
[[vega-schema]]
|
|
==== Change the Vega version
|
|
|
|
The default visualization uses Vega-Lite version 2. To use Vega version 4, edit
|
|
the `schema`.
|
|
|
|
Go to `$schema`, enter `https://vega.github.io/schema/vega/v4.json`, then click
|
|
*Update*.
|
|
|
|
[float]
|
|
[[vega-type]]
|
|
==== Change the visualization type
|
|
|
|
The default visualization is a line chart. To change the visualization type,
|
|
change the `mark` value. The supported visualization types are listed in the
|
|
text editor.
|
|
|
|
Go to `mark`, change the value to a different visualization type, then click
|
|
*Update*.
|
|
|
|
[float]
|
|
[[vega-sizing-and-positioning]]
|
|
==== Change the layout
|
|
|
|
By default, Vega visualizations use the `autosize = { type: 'fit', contains: 'padding' }` layout.
|
|
`fit` uses all available space, ignores `width` and `height` values,
|
|
and respects the padding values. To override this behavior, change the
|
|
`autosize` value.
|
|
|
|
[[vega-querying-elasticsearch]]
|
|
=== Query {es}
|
|
|
|
experimental[] Vega https://vega.github.io/vega/docs/data/[data] elements
|
|
use embedded and external data with a `"url"` parameter. {kib} adds support for
|
|
direct {es} queries by overloading
|
|
the `"url"` value.
|
|
|
|
NOTE: With Vega, you dynamically load your data by setting signals as data URLs.
|
|
Since {kib} is unable to support dynamically loaded data, all data is fetched
|
|
before it's passed to the Vega renderer.
|
|
|
|
For example, count the number of documents in all indices:
|
|
|
|
[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: _all
|
|
// The body element may contain "aggs" and "query" subfields
|
|
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).
|
|
|
|
[[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"}
|
|
----
|
|
|
|
To enable Elastic 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 "default". Use false to disable base layer.
|
|
"mapStyle": false,
|
|
|
|
// 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.
|
|
|
|
Vega visualization ignore the `autosize`, `width`, `height`, and `padding`
|
|
values, using `fit` model with zero padding.
|
|
|
|
[[vega-debugging]]
|
|
=== Debugging Vega
|
|
|
|
[[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 main data set.
|
|
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.
|
|
|
|
[[vega-data]]
|
|
==== Data
|
|
|
|
experimental[] If you are using an {es} query, make sure your resulting data is
|
|
what you expected. The easiest way to view it is by using the "networking"
|
|
tab in the browser debugging tools (for example, F12). Modify the graph slightly
|
|
so that it makes a search request, and view the response from the
|
|
server. Another approach is to use
|
|
https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Dev Tools]. Place the index name into the first line:
|
|
`GET <INDEX_NAME>/_search`, then add your query as the following lines
|
|
(just the value of the `"query"` field).
|
|
|
|
If you need to share your graph with someone, copy the
|
|
raw data response to https://gist.github.com/[gist.github.com], possibly
|
|
with a `.json` extension, use the `[raw]` button, and use that url
|
|
directly in your graph.
|
|
|
|
To restrict Vega from using non-ES data sources, add `vega.enableExternalUrls: false`
|
|
to your kibana.yml file.
|
|
|
|
[[vega-notes]]
|
|
[[vega-useful-links]]
|
|
=== Resources and examples
|
|
|
|
experimental[] To learn more about Vega and Vega-List, refer to the resources and examples.
|
|
|
|
==== 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.
|
|
|
|
==== 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]
|
|
|
|
==== 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, 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"`.
|
|
|
|
[[vega-additional-configuration-options]]
|
|
==== Additional configuration options
|
|
|
|
These options are specific to the {kib}. link:#vega-with-a-map[Map support] has
|
|
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 VegaLite warnings
|
|
hideWarnings: true
|
|
// Vega renderer to use: `svg` or `canvas` (default)
|
|
renderer: canvas
|
|
}
|
|
}
|
|
/* the rest of Vega code */
|
|
}
|
|
----
|