You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Currently Vega version 4.3 and Vega-Lite version 2.6 are supported.
6
+
Build custom visualizations from multiple data sources using Vega
7
+
and Vega-Lite.
12
8
13
-
NOTE: In Vega it is possible to load data dynamically, e.g. by setting signals as data urls. This is not supported in Kibana as all data is fetched at once prior to passing it to the Vega renderer.
9
+
* *Vega* — A declarative format to create visualizations using JSON.
10
+
Generate interactive displays using D3.
14
11
12
+
* *Vega-Lite* — An easier format to use than Vega that enables more rapid
13
+
data analysis. Compiles into Vega.
15
14
16
-
[[vega-quick-demo]]
17
-
=== Getting Started with Vega
15
+
For more information about Vega and Vega-Lite, refer to
16
+
<<vega-useful-links, Resources and examples>>.
18
17
19
-
* To experiment using sample data, first click the {kib} logo in the upper left hand corner
20
-
and then click the link next to *Sample Data*.
21
-
* Once you have data loaded, go to *Visualize*, click *+*, and select *Vega* to see an example graph.
22
-
*Note*: The default graph is written in Vega-Lite, but you can build visualizations
23
-
in either language. See <<vega-vs-vegalite, Vega vs. Vega-Lite>> for more information.
24
-
* Try changing `mark` from `line` to `point`, `area`, `bar`, `circle`,
25
-
or `square`. Check out the
26
-
https://vega.github.io/vega-lite/docs/mark.html#mark-def[Vega-Lite docs] for more information.
27
-
* Explore other available https://vega.github.io/vega/examples/[Vega] or
Go to `$schema`, enter `https://vega.github.io/schema/vega/v4.json`, then click
36
+
*Update*.
47
37
48
-
The `schema` URL is only used for identification, and does not need to be accessible by {kib}.
38
+
[float]
39
+
[[vega-type]]
40
+
==== Change the visualization type
49
41
50
-
Vega-Lite is a simplified version of Vega; it automates some constructions and has
51
-
much shorter specifications than Vega. Vega-Lite is automatically converted into
52
-
Vega before rendering, but it has some limitations, and there are some visualizations
53
-
that can be expressed in Vega that cannot be expressed in Vega-Lite. You can learn more
54
-
in the https://vega.github.io/vega-lite/[Vega-Lite documentation].
42
+
The default visualization is a line chart. To change the visualization type,
43
+
change the `mark` value. The supported visualization types are listed in the
44
+
text editor.
55
45
56
-
You can use https://vega.github.io/editor/[this editor] to convert Vega-Lite into
57
-
Vega.
46
+
Go to `mark`, change the value to a different visualization type, then click
47
+
*Update*.
58
48
59
-
When you create a Vega visualization in {kib}, you can edit the `schema`
60
-
value in the dev tools to the left of the graph to define which of the two expression
61
-
languages you would like to use.
49
+
[float]
50
+
[[vega-sizing-and-positioning]]
51
+
==== Change the layout
62
52
53
+
By default, Vega visualizations use the `autosize = { type: 'fit', contains: 'padding' }` layout.
54
+
`fit` uses all available space, ignores `width` and `height` values,
55
+
and respects the padding values. To override this behavior, change the
56
+
`autosize` value.
63
57
64
58
[[vega-querying-elasticsearch]]
65
-
=== Querying Elasticsearch
59
+
=== Query {es}
66
60
67
-
By default, Vega's https://vega.github.io/vega/docs/data/[data] element
68
-
can use embedded and external data with a `"url"` parameter. Kibana adds support for the direct Elasticsearch queries by overloading
61
+
experimental[] Vega https://vega.github.io/vega/docs/data/[data] elements
62
+
use embedded and external data with a `"url"` parameter. {kib} adds support for
63
+
direct {es} queries by overloading
69
64
the `"url"` value.
70
65
71
-
Here is an example of an Elasticsearch query that counts the number of documents in all indexes. The query uses *@timestamp* field to filter the time range, and break it into histogram buckets.
66
+
NOTE: With Vega, you dynamically load your data by setting signals as data URLs.
67
+
Since {kib} is unable to support dynamically loaded data, all data is fetched
68
+
before it's passed to the Vega renderer.
69
+
70
+
For example, count the number of documents in all indices:
72
71
73
72
[source,yaml]
74
73
----
75
-
// An object instead of a string for the url value
74
+
// An object instead of a string for the URL value
76
75
// is treated as a context-aware Elasticsearch query.
77
76
url: {
78
-
// Specify the time filter (upper right corner) with this field
77
+
// Specify the time filter.
79
78
%timefield%: @timestamp
80
79
// Apply dashboard context filters when set
81
80
%context%: true
@@ -88,8 +87,8 @@ url: {
88
87
time_buckets: {
89
88
date_histogram: {
90
89
// Use date histogram aggregation on @timestamp field
91
-
field: @timestamp
92
-
// interval value will depend on the daterange picker
90
+
field: @timestamp <1>
91
+
// interval value will depend on the time filter
93
92
// Use an integer to set approximate bucket count
94
93
interval: { %autointerval%: true }
95
94
// Make sure we get an entire range, even if it has no data
@@ -109,7 +108,10 @@ url: {
109
108
}
110
109
----
111
110
112
-
The full result has this kind of structure:
111
+
<1> `@timestamp` — Filters the time range and breaks it into histogram
112
+
buckets.
113
+
114
+
The full result includes the following structure:
113
115
114
116
[source,yaml]
115
117
----
@@ -118,23 +120,24 @@ The full result has this kind of structure:
118
120
"time_buckets": {
119
121
"buckets": [{
120
122
"key_as_string": "2015-11-30T22:00:00.000Z",
121
-
"key": 1448920800000,
123
+
"key": 1448920800000,<1>
122
124
"doc_count": 28
123
125
}, {
124
126
"key_as_string": "2015-11-30T23:00:00.000Z",
125
-
"key": 1448924400000,
127
+
"key": 1448924400000, <1>
126
128
"doc_count": 330
127
129
}, ...
128
130
----
129
131
130
-
Note that `"key"` is a unix timestamp, and can be used without conversions by the
132
+
<1> `"key"` — The unix timestamp you can use without conversions by the
131
133
Vega date expressions.
132
134
133
-
For most graphs we only need the list of the bucket values, so we use `format: {property: "aggregations.time_buckets.buckets"}` expression to focus on just the data we need.
135
+
For most visualizations, you only need the list of bucket values. To focus on
136
+
only the data you need, use `format: {property: "aggregations.time_buckets.buckets"}`.
134
137
135
-
Query may be specified with individual range and dashboard context as
136
-
well. This query is equivalent to `"%context%": true, "%timefield%": "@timestamp"`,
137
-
except that the timerange is shifted back by 10 minutes:
138
+
Specify a query with individual range and dashboard context. The query is
139
+
equivalent to `"%context%": true, "%timefield%": "@timestamp"`,
140
+
except that the time range is shifted back by 10 minutes:
138
141
139
142
[source,yaml]
140
143
----
@@ -185,9 +188,9 @@ on the currently picked range: `"interval": {"%autointerval%": 10}` will
185
188
try to get about 10-15 data points (buckets).
186
189
187
190
[[vega-esmfiles]]
188
-
=== Elastic Map Files
191
+
=== Access Elastic Map Service files
189
192
190
-
It is possible to access Elastic Map Service's files via the same mechanism
193
+
experimental[] Access the Elastic Map Service files via the same mechanism:
191
194
192
195
[source,yaml]
193
196
----
@@ -203,11 +206,8 @@ url: {
203
206
format: {property: "features"}
204
207
----
205
208
206
-
[[vega-with-a-map]]
207
-
=== Vega with a Map
208
-
209
-
Kibana's default map can be used as a base of the Vega graph. To enable,
210
-
the graph must specify `type=map` in the host configuration:
209
+
To enable Elastic Maps, the graph must specify `type=map` in the host
210
+
configuration:
211
211
212
212
[source,yaml]
213
213
----
@@ -247,42 +247,47 @@ the graph must specify `type=map` in the host configuration:
247
247
}
248
248
----
249
249
250
-
This visualization will automatically inject a projection called
251
-
`"projection"`. Use it to calculate positioning of all geo-aware marks.
252
-
Additionally, you may use `latitude`, `longitude`, and `zoom` signals.
250
+
The visualization automatically injects a `"projection"`, which you can use to
251
+
calculate the position of all geo-aware marks.
252
+
Additionally, you can use `latitude`, `longitude`, and `zoom` signals.
253
253
These signals can be used in the graph, or can be updated to modify the
254
-
positioning of the map.
254
+
position of the map.
255
+
256
+
Vega visualization ignore the `autosize`, `width`, `height`, and `padding`
257
+
values, using `fit` model with zero padding.
255
258
256
259
[[vega-debugging]]
257
-
=== Debugging
260
+
=== Debugging Vega
258
261
259
262
[[vega-browser-debugging-console]]
260
-
==== Browser Debugging console
263
+
==== Browser debugging console
261
264
262
-
Use browser debugging tools (e.g. F12 or Ctrl+Shift+J in Chrome) to
265
+
experimental[] Use browser debugging tools (for example, F12 or Ctrl+Shift+J in Chrome) to
263
266
inspect the `VEGA_DEBUG` variable:
264
-
* `view` - access to the Vega View object. See https://vega.github.io/vega/docs/api/debugging/[Vega Debugging Guide]
265
-
on how to inspect data and signals at runtime. For Vega-Lite, `VEGA_DEBUG.view.data('source_0')` gets the main data set.
266
-
For Vega, it uses the data name as defined in your Vega spec.
267
-
* `vega_spec` - Vega JSON graph specification after some modifications by Kibana. In case
267
+
+
268
+
* `view` — Access to the Vega View object. See https://vega.github.io/vega/docs/api/debugging/[Vega Debugging Guide]
269
+
on how to inspect data and signals at runtime. For Vega-Lite, `VEGA_DEBUG.view.data('source_0')` gets the main data set.
270
+
For Vega, it uses the data name as defined in your Vega spec.
271
+
272
+
* `vega_spec` — Vega JSON graph specification after some modifications by {kib}. In case
268
273
of Vega-Lite, this is the output of the Vega-Lite compiler.
269
-
* `vegalite_spec` - If this is a Vega-Lite graph, JSON specification of the graph before
274
+
275
+
* `vegalite_spec` — If this is a Vega-Lite graph, JSON specification of the graph before
270
276
Vega-Lite compilation.
271
277
272
278
[[vega-data]]
273
279
==== Data
274
280
275
-
If you are using Elasticsearch query, make sure your resulting data is
276
-
what you expected. The easiest way to view it is by using "networking"
277
-
tab in the browser debugging tools (e.g. F12). Modify the graph slightly
281
+
experimental[] If you are using an {es} query, make sure your resulting data is
282
+
what you expected. The easiest way to view it is by using the "networking"
283
+
tab in the browser debugging tools (for example, F12). Modify the graph slightly
278
284
so that it makes a search request, and view the response from the
0 commit comments