Skip to content

Commit

Permalink
Vega doc changes (elastic#63889)
Browse files Browse the repository at this point in the history 
* Vega doc changes

* Final changes

* Review comments
  • Loading branch information
@KOTungseth
KOTungseth committed Apr 20, 2020
1 parent 8535a30 commit 5e47366
Show file tree
Hide file tree
Showing 2 changed files with 100 additions and 124 deletions.
Binary file added docs/images/vega_lite_default.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
224 changes: 100 additions & 124 deletions docs/visualize/vega.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -1,81 +1,80 @@
[[vega-graph]]
== Vega Graphs
experimental[]
== Vega

You can build https://vega.github.io/vega/examples/[Vega] and
https://vega.github.io/vega-lite/examples/[Vega-Lite] data visualizations
into Kibana, either standalone, or on top of a map. To see Vega in action,
watch this
https://www.youtube.com/watch?v=lQGCipY3th8[short introduction video].
experimental[]

Currently Vega version 4.3 and Vega-Lite version 2.6 are supported.
Build custom visualizations from multiple data sources using Vega
and Vega-Lite.

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.
* *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.

[[vega-quick-demo]]
=== Getting Started with Vega
For more information about Vega and Vega-Lite, refer to
<<vega-useful-links, Resources and examples>>.

* To experiment using sample data, first click the {kib} logo in the upper left hand corner
and then click the link next to *Sample Data*.
* Once you have data loaded, go to *Visualize*, click *+*, and select *Vega* to see an example graph.
*Note*: The default graph is written in Vega-Lite, but you can build visualizations
in either language. See <<vega-vs-vegalite, Vega vs. Vega-Lite>> for more information.
* Try changing `mark` from `line` to `point`, `area`, `bar`, `circle`,
or `square`. Check out the
https://vega.github.io/vega-lite/docs/mark.html#mark-def[Vega-Lite docs] for more information.
* Explore other available https://vega.github.io/vega/examples/[Vega] or
https://vega.github.io/vega-lite/examples/[Vega-Lite] visualizations.
*Note*: You might need to make URLs absolute, for example, replace
`"url": "data/world-110m.json"` with
`"url": "https://vega.github.io/editor/data/world-110m.json"`.
See <<vega-using-vega-and-vegalite-examples, Vega and Vega-Lite examples>>.
* For more information on getting started, check out this https://www.elastic.co/blog/getting-started-with-vega-visualizations-in-kibana[blog post].
[float]
[[create-vega-viz]]
=== Create Vega visualizations

You create Vega visualizations by using the text editor, which is
preconfigured with the options you need.

[[vega-vs-vegalite]]
=== Vega vs Vega-Lite
[role="screenshot"]
image::images/vega_lite_default.png[]

The Vega visualization in {kib} supports both Vega and Vega-Lite. You can use the
`schema` value to define which language you would like to use and its minimum
required version.
[float]
[[vega-schema]]
==== Change the Vega version

For example:
The default visualization uses Vega-Lite version 2. To use Vega version 4, edit
the `schema`.

* Vega-Lite v2: `$schema: https://vega.github.io/schema/vega-lite/v2.json`
* Vega v4: `$schema: https://vega.github.io/schema/vega/v4.json`
Go to `$schema`, enter `https://vega.github.io/schema/vega/v4.json`, then click
*Update*.

The `schema` URL is only used for identification, and does not need to be accessible by {kib}.
[float]
[[vega-type]]
==== Change the visualization type

Vega-Lite is a simplified version of Vega; it automates some constructions and has
much shorter specifications than Vega. Vega-Lite is automatically converted into
Vega before rendering, but it has some limitations, and there are some visualizations
that can be expressed in Vega that cannot be expressed in Vega-Lite. You can learn more
in the https://vega.github.io/vega-lite/[Vega-Lite documentation].
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.

You can use https://vega.github.io/editor/[this editor] to convert Vega-Lite into
Vega.
Go to `mark`, change the value to a different visualization type, then click
*Update*.

When you create a Vega visualization in {kib}, you can edit the `schema`
value in the dev tools to the left of the graph to define which of the two expression
languages you would like to use.
[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]]
=== Querying Elasticsearch
=== Query {es}

By default, Vega's https://vega.github.io/vega/docs/data/[data] element
can use embedded and external data with a `"url"` parameter. Kibana adds support for the direct Elasticsearch queries by overloading
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.

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.
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
// An object instead of a string for the URL value
// is treated as a context-aware Elasticsearch query.
url: {
// Specify the time filter (upper right corner) with this field
// Specify the time filter.
%timefield%: @timestamp
// Apply dashboard context filters when set
%context%: true
Expand All @@ -88,8 +87,8 @@ url: {
time_buckets: {
date_histogram: {
// Use date histogram aggregation on @timestamp field
field: @timestamp
// interval value will depend on the daterange picker
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
Expand All @@ -109,7 +108,10 @@ url: {
}
----

The full result has this kind of structure:
<1> `@timestamp` &mdash; Filters the time range and breaks it into histogram
buckets.

The full result includes the following structure:

[source,yaml]
----
Expand All @@ -118,23 +120,24 @@ The full result has this kind of structure:
"time_buckets": {
"buckets": [{
"key_as_string": "2015-11-30T22:00:00.000Z",
"key": 1448920800000,
"key": 1448920800000,<1>
"doc_count": 28
}, {
"key_as_string": "2015-11-30T23:00:00.000Z",
"key": 1448924400000,
"key": 1448924400000, <1>
"doc_count": 330
}, ...
----

Note that `"key"` is a unix timestamp, and can be used without conversions by the
<1> `"key"` &mdash; The unix timestamp you can use without conversions by the
Vega date expressions.

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.
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"}`.

Query may be specified with individual range and dashboard context as
well. This query is equivalent to `"%context%": true, "%timefield%": "@timestamp"`,
except that the timerange is shifted back by 10 minutes:
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]
----
Expand Down Expand Up @@ -185,9 +188,9 @@ on the currently picked range: `"interval": {"%autointerval%": 10}` will
try to get about 10-15 data points (buckets).

[[vega-esmfiles]]
=== Elastic Map Files
=== Access Elastic Map Service files

It is possible to access Elastic Map Service's files via the same mechanism
experimental[] Access the Elastic Map Service files via the same mechanism:

[source,yaml]
----
Expand All @@ -203,11 +206,8 @@ url: {
format: {property: "features"}
----

[[vega-with-a-map]]
=== Vega with a Map

Kibana's default map can be used as a base of the Vega graph. To enable,
the graph must specify `type=map` in the host configuration:
To enable Elastic Maps, the graph must specify `type=map` in the host
configuration:

[source,yaml]
----
Expand Down Expand Up @@ -247,42 +247,47 @@ the graph must specify `type=map` in the host configuration:
}
----

This visualization will automatically inject a projection called
`"projection"`. Use it to calculate positioning of all geo-aware marks.
Additionally, you may use `latitude`, `longitude`, and `zoom` signals.
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
positioning of the map.
position of the map.

Vega visualization ignore the `autosize`, `width`, `height`, and `padding`
values, using `fit` model with zero padding.

[[vega-debugging]]
=== Debugging
=== Debugging Vega

[[vega-browser-debugging-console]]
==== Browser Debugging console
==== Browser debugging console

Use browser debugging tools (e.g. F12 or Ctrl+Shift+J in Chrome) to
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 Kibana. In case
+
* `view` &mdash; 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` &mdash; 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

* `vegalite_spec` &mdash; If this is a Vega-Lite graph, JSON specification of the graph before
Vega-Lite compilation.

[[vega-data]]
==== Data

If you are using Elasticsearch query, make sure your resulting data is
what you expected. The easiest way to view it is by using "networking"
tab in the browser debugging tools (e.g. F12). Modify the graph slightly
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[Kibana
Dev Tools] tab - place the index name into the first line:
`GET <INDEX_NAME>/_search`, and add your query as the following lines
(just the value of the `"query"` field)
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, you may want to copy the
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.
Expand All @@ -292,9 +297,11 @@ to your kibana.yml file.

[[vega-notes]]
[[vega-useful-links]]
=== Useful Links
=== Resources and examples

experimental[] To learn more about Vega and Vega-List, refer to the resources and examples.

==== 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.

Expand All @@ -308,28 +315,15 @@ The https://vega.github.io/editor/[Vega Editor] includes examples for Vega & Veg
* https://vega.github.io/vega/docs/[Docs]
* https://vega.github.io/vega/examples/[Examples]

==== Elastic blog posts
* https://www.elastic.co/blog/getting-started-with-vega-visualizations-in-kibana[Getting Started with Vega Visualizations in Kibana]
* https://www.elastic.co/blog/custom-vega-visualizations-in-kibana[Custom Vega Visualizations in Kibana]
* https://www.elastic.co/blog/sankey-visualization-with-vega-in-kibana[Sankey Visualization with Vega in Kibana]


[[vega-using-vega-and-vegalite-examples]]
==== Using Vega and Vega-Lite examples

When using https://vega.github.io/vega/examples/[Vega] and
https://vega.github.io/vega-lite/examples/[VegaLite] examples, you may
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"`. Also,
regular Vega examples use `"autosize": "pad"` layout model, whereas
Kibana uses `fit`. Remove all `autosize`, `width`, and `height`
values. See link:#sizing-and-positioning[sizing and positioning].
`"url": "https://vega.github.io/editor/data/world-110m.json"`.

[[vega-additional-configuration-options]]
==== Additional configuration options

These options are specific to the Kibana. link:#vega-with-a-map[Map support] has
These options are specific to the {kib}. link:#vega-with-a-map[Map support] has
additional configuration options.

[source,yaml]
Expand All @@ -351,21 +345,3 @@ additional configuration options.
/* the rest of Vega code */
}
----

[[vega-sizing-and-positioning]]
==== Sizing and positioning

[[vega-and-vegalite]]
===== Vega and Vega-Lite

By default, Kibana Vega graphs will use
`autosize = { type: 'fit', contains: 'padding' }` layout model for Vega
and Vega-Lite graphs. The `fit` model uses all available space, ignores
`width` and `height` values, but respects the padding values. You may
override this behaviour by specifying a different `autosize` value.

[[vega-on-a-map]]
===== Vega on a map

All Vega graphs will ignore `autosize`, `width`, `height`, and `padding`
values, using `fit` model with zero padding.

0 comments on commit 5e47366

Please sign in to comment.