-
Notifications
You must be signed in to change notification settings - Fork 8.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Vega doc changes #63889
Vega doc changes #63889
Changes from 3 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,81 +1,78 @@ | ||
[[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[] Build custom visualizations from multiple data sources using Vega | ||
and Vega-Lite. | ||
|
||
Currently Vega version 4.3 and Vega-Lite version 2.6 are supported. | ||
* *Vega* — A declarative format to create visualizations using JSON. | ||
Generate interactive displays using D3. | ||
|
||
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-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, Useful links>>. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Suggest renaming this section Vega resources |
||
|
||
[[vega-quick-demo]] | ||
=== Getting Started with Vega | ||
[float] | ||
[[create-vega-viz]] | ||
=== Create Vega visualizations | ||
|
||
* 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]. | ||
You create Vega visualizations by using the text editor. The text editor is | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is there a way to write this para without back-to-back "text editor"? You create Vega visualizations by using the text editor, which is preconfigured with the options you need. |
||
preconfigured with the options you need to create your Vega visualizations. | ||
|
||
[role="screenshot"] | ||
image::images/vega_lite_default.png[] | ||
|
||
[[vega-vs-vegalite]] | ||
=== Vega vs Vega-Lite | ||
[float] | ||
[[vega-schema]] | ||
==== Change the Vega version | ||
|
||
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. | ||
The default visualization uses Vega-Lite version 2. To use Vega version 4, edit | ||
the `schema`. | ||
|
||
For example: | ||
Go to `$schema`, enter `https://vega.github.io/schema/vega/v4.json`, then click | ||
*Update*. | ||
|
||
* Vega-Lite v2: `$schema: https://vega.github.io/schema/vega-lite/v2.json` | ||
* Vega v4: `$schema: https://vega.github.io/schema/vega/v4.json` | ||
[float] | ||
[[vega-type]] | ||
==== Change the visualization type | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This section was a little confusing. The two paragraphs are very similar. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The actions are similar, which is why the sections are similar. |
||
|
||
The `schema` URL is only used for identification, and does not need to be accessible by {kib}. | ||
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. | ||
|
||
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]. | ||
Go to `mark`, change the value to a different visualization type, then click | ||
*Update*. | ||
|
||
You can use https://vega.github.io/editor/[this editor] to convert Vega-Lite into | ||
Vega. | ||
|
||
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 | ||
Vega https://vega.github.io/vega/docs/data/[data] elements | ||
use embedded and external data with a `"url"` parameter. {kib} adds support for | ||
the direct {es} queries by overloading | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. the direct > direct? |
||
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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Since > Because There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Since and because are synonymous. |
||
before it's passed to the Vega renderer. | ||
|
||
For example, count the number of documents in all indexes: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. indexes > 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 | ||
|
@@ -88,8 +85,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 | ||
|
@@ -109,7 +106,10 @@ url: { | |
} | ||
---- | ||
|
||
The full result has this kind of structure: | ||
<1> `@timestamp` — Filters the time range and breaks it into histogram | ||
buckets. | ||
|
||
The full result includes the following structure: | ||
|
||
[source,yaml] | ||
---- | ||
|
@@ -118,23 +118,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"` — 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] | ||
---- | ||
|
@@ -185,9 +186,9 @@ on the currently picked range: `"interval": {"%autointerval%": 10}` will | |
try to get about 10-15 data points (buckets). | ||
|
||
[[vega-esmfiles]] | ||
=== Elastic Map Files | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There are two sections related to Elastic Maps, and both are very short. Can they be combined? |
||
=== Access Elastic Map Service files | ||
|
||
It is possible to access Elastic Map Service's files via the same mechanism | ||
Access the Elastic Map Service files via the same mechanism: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What does same mechanism refer to? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This PR is to rewrite the introduction and minimally correct the grammar in subsequent sections. I didn't write these pieces, so I'm not sure. |
||
|
||
[source,yaml] | ||
---- | ||
|
@@ -204,9 +205,9 @@ format: {property: "features"} | |
---- | ||
|
||
[[vega-with-a-map]] | ||
=== Vega with a Map | ||
=== Use Vega with Elastic Maps | ||
|
||
Kibana's default map can be used as a base of the Vega graph. To enable, | ||
Use Elastic Maps as the base of the Vega visualization. To enable, | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Maybe a little more context? To enable Elastic Maps, the Vega graph must specify .... |
||
the graph must specify `type=map` in the host configuration: | ||
|
||
[source,yaml] | ||
|
@@ -247,40 +248,42 @@ 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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Debugging a Vega visualization? |
||
|
||
[[vega-browser-debugging-console]] | ||
==== Browser Debugging console | ||
==== Browser debugging console | ||
|
||
Use browser debugging tools (e.g. F12 or Ctrl+Shift+J in Chrome) to | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. e.g. > for example |
||
inspect the `VEGA_DEBUG` variable: | ||
* `view` - access to the Vega View object. See https://vega.github.io/vega/docs/api/debugging/[Vega Debugging Guide] | ||
* `view` — Access to the Vega View object. See https://vega.github.io/vega/docs/api/debugging/[Vega Debugging Guide] | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is formatted as a bulleted list, but shows up as a paragraph in the formatted version. |
||
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 | ||
* `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 | ||
* `vegalite_spec` — 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 | ||
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 "networking" | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. networking > the networking |
||
tab in the browser debugging tools (e.g. 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 | ||
raw data response to https://gist.github.com/[gist.github.com], possibly | ||
|
@@ -292,9 +295,9 @@ to your kibana.yml file. | |
|
||
[[vega-notes]] | ||
[[vega-useful-links]] | ||
=== Useful Links | ||
=== Useful links | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. How about renaming as "Vega resources" or "Vega resources and examples" Suggest also moving the Elastic blog posts above Vega-Lite resources. |
||
|
||
==== 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. | ||
|
||
|
@@ -323,13 +326,13 @@ 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` | ||
{kib} uses `fit`. Remove all `autosize`, `width`, and `height` | ||
values. See link:#sizing-and-positioning[sizing and positioning]. | ||
|
||
[[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 {kb}. link:#vega-with-a-map[Map support] has | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. {kb} > {kib} |
||
additional configuration options. | ||
|
||
[source,yaml] | ||
|
@@ -351,21 +354,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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I recall a discussion where we prefer to use the banner on the first page of feature that is experimental and then use the inline tag for inner pages.