Skip to content
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] Tutorials should be updated to include new inspector #83797

Merged
merged 7 commits into from
Nov 24, 2020
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 24 additions & 57 deletions docs/user/dashboard/tutorials.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -76,8 +76,6 @@ Now that you've created your *Lens* visualization, add it to a <<dashboard,dashb
[[vega-lite-tutorial-create-your-first-visualizations]]
=== Create your first visualization with Vega-Lite

experimental[]

In this tutorial, you will learn about how to edit Vega-Lite in {kib} to create
a stacked area chart from an {es} search query. It will give you a starting point
for a more comprehensive
Expand All @@ -88,7 +86,7 @@ In this tutorial, you will build a stacked area chart from one of the {kib} samp
sets.

[role="screenshot"]
image::visualize/images/vega_lite_tutorial_1.png[]
image::visualize/images/vega_lite_tutorial_1.png[Vega-Lite tutorial stacked area chart]

Before beginning this tutorial, install the <<add-sample-data, eCommerce sample data>>
set.
Expand All @@ -98,7 +96,7 @@ line chart which shows the total number of documents across all your indices
within the time range.

[role="screenshot"]
image::visualize/images/vega_lite_default.png[]
image::visualize/images/vega_lite_default.png[Vega-Lite tutorial default visualization]

The text editor contains a Vega-Lite spec written in https://hjson.github.io/[HJSON],
which is similar to JSON but optimized for human editing. HJSON supports:
Expand Down Expand Up @@ -134,7 +132,7 @@ Click "Update". The result is probably not what you expect. You should see a fla
line with 0 results.

You've only changed the index, so the difference must be the query is returning
no results. You can try the <<vega-browser-debugging-console, Vega debugging process>>,
no results. You can try the <<vega-debugging, Vega debugging process>>,
but intuition may be faster for this particular problem.

In this case, the problem is that you are querying the field `@timestamp`,
Expand Down Expand Up @@ -332,38 +330,29 @@ your spec:

If you copy and paste that into your Vega-Lite spec, and click "Update",
you will see a warning saying `Infinite extent for field "key": [Infinity, -Infinity]`.
Let's use our <<vega-browser-debugging-console, Vega debugging skills>> to understand why.
Let's use our <<vega-inspector, Vega debugging skills>> to understand why.

Vega-Lite generates data using the names `source_0` and `data_0`. `source_0` contains
the results from the {es} query, and `data_0` contains the visually encoded results
which are shown in the chart. To debug this problem, you need to compare both.

To look at the source, open the browser dev tools console and type
`VEGA_DEBUG.view.data('source_0')`. You will see:
To inspect data sets, go to *Inspect* and select *View: Vega debug*. You will see:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To inspect data sets, go to *Inspect* and select *View: Vega debug*. You will see:
To inspect data sets, go to *Inspect* and select *View: Vega debug*. You will see a menu with different data sources:


```js
[{
doc_count: 454
key: "Men's Clothing"
time_buckets: {buckets: Array(57)}
Symbol(vega_id): 12822
}, ...]
```
[role="screenshot"]
image::visualize/images/vega_lite_tutorial_3.png[Vega-Lite tutorial Inspector Data sets]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
image::visualize/images/vega_lite_tutorial_3.png[Vega-Lite tutorial Inspector Data sets]
image::visualize/images/vega_lite_tutorial_3.png[Data set selector showing root, source_0, data_0, and marks]


To compare to the visually encoded data, open the browser dev tools console and type
`VEGA_DEBUG.view.data('data_0')`. You will see:
To look closer at the source, select the matching option in the dropdown. It looks like:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To look closer at the source, select the matching option in the dropdown. It looks like:
To look closer at the raw data in Vega, select the option for `source_0` in the dropdown:


```js
[{
doc_count: 454
key: NaN
time_buckets: {buckets: Array(57)}
Symbol(vega_id): 13879
}]
```
[role="screenshot"]
image::visualize/images/vega_lite_tutorial_4.png[Vega-Lite tutorial Data sets source]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
image::visualize/images/vega_lite_tutorial_4.png[Vega-Lite tutorial Data sets source]
image::visualize/images/vega_lite_tutorial_4.png[Table for data_0 with columns key, doc_count and array of time_buckets]


To compare to the visually encoded data, change dropdown selection to `data_0`. You will see:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To compare to the visually encoded data, change dropdown selection to `data_0`. You will see:
To compare to the visually encoded data, change the dropdown selection to `data_0`. You will see:


[role="screenshot"]
image::visualize/images/vega_lite_tutorial_5.png[Vega-Lite tutorial Data sets data]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
image::visualize/images/vega_lite_tutorial_5.png[Vega-Lite tutorial Data sets data]
image::visualize/images/vega_lite_tutorial_5.png[Table for data_0 where the key is NaN instead of a string]


The issue seems to be that the `key` property is not being converted the right way,
which makes sense because the `key` is now `Men's Clothing` instead of a timestamp.
which makes sense because the `key` is now category (`Men's Clothing`, `Women's Clothing`, etc.) instead of a timestamp.

To fix this, try updating the `encoding` of your Vega-Lite spec to:

Expand All @@ -382,19 +371,11 @@ To fix this, try updating the `encoding` of your Vega-Lite spec to:
}
```

This will show more errors, and you can inspect `VEGA_DEBUG.view.data('data_0')` to
This will show more errors, and you can inspect `data_0` to
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This will show more errors, and you can inspect `data_0` to
This will show more errors, so you need to debug. Click *Inspect*, switch the view to *Vega Debug*, and switch to look at the visually encoded data in `data_0` to

understand why. This now shows:

```js
[{
doc_count: 454
key: "Men's Clothing"
time_buckets: {buckets: Array(57)}
time_buckets.buckets.doc_count: undefined
time_buckets.buckets.key: null
Symbol(vega_id): 14094
}]
```
[role="screenshot"]
image::visualize/images/vega_lite_tutorial_6.png[Vega-Lite tutorial Data sets updated data]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
image::visualize/images/vega_lite_tutorial_6.png[Vega-Lite tutorial Data sets updated data]
image::visualize/images/vega_lite_tutorial_6.png[Table for data_0 showing that the column time_buckets.buckets.key is undefined]


It looks like the problem is that the `time_buckets` inner array is not being
DianaDerevyankina marked this conversation as resolved.
Show resolved Hide resolved
extracted by Vega. The solution is to use a Vega-lite
Expand All @@ -411,23 +392,10 @@ Add this section in between the `data` and `encoding` section:
```

This does not yet produce the results you expect. Inspect the transformed data
by typing `VEGA_DEBUG.view.data('data_0')` into the console again:
by selecting `data_0` in *Data sets* again:

```js
[{
doc_count: 453
key: "Men's Clothing"
time_bucket.buckets.doc_count: undefined
time_buckets: {buckets: Array(57)}
time_buckets.buckets: {
key_as_string: "2020-06-30T15:00:00.000Z",
key: 1593529200000,
doc_count: 2
}
time_buckets.buckets.key: null
Symbol(vega_id): 21564
}]
```
[role="screenshot"]
image::visualize/images/vega_lite_tutorial_7.png[Vega-Lite tutorial Data sets transformed data]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
image::visualize/images/vega_lite_tutorial_7.png[Vega-Lite tutorial Data sets transformed data]
image::visualize/images/vega_lite_tutorial_7.png[Table showing data_0 with multiple pages of results, but undefined values in the column time_buckets.buckets.key]


The debug view shows `undefined` values where you would expect to see numbers, and
the cause is that there are duplicate names which are confusing Vega-Lite. This can
Expand Down Expand Up @@ -564,7 +532,7 @@ Now that you've enabled a selection, try moving the mouse around the visualizati
and seeing the points respond to the nearest position:

[role="screenshot"]
image::visualize/images/vega_lite_tutorial_2.png[]
image::visualize/images/vega_lite_tutorial_2.png[Vega-Lite tutorial selection enabled]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
image::visualize/images/vega_lite_tutorial_2.png[Vega-Lite tutorial selection enabled]
image::visualize/images/vega_lite_tutorial_2.png[Vega-Lite tutorial selection enabled]
The selection is controlled by a Vega signal, and can be viewed using the <<vega-inspector, Vega Inspector>>.


The final result of this tutorial is this spec:

Expand Down Expand Up @@ -683,8 +651,6 @@ The final result of this tutorial is this spec:
[[vega-tutorial-update-kibana-filters-from-vega]]
=== Update {kib} filters from Vega

experimental[]

In this tutorial you will build an area chart in Vega using an {es} search query,
and add a click handler and drag handler to update {kib} filters.
This tutorial is not a full https://vega.github.io/vega/tutorials/[Vega tutorial],
Expand Down Expand Up @@ -935,6 +901,7 @@ The first step is to add a new `signal` to track the X position of the cursor:
}]
}
```
To learn more about inspecting signals, explore the <<vega-inspector, Vega Inspector>>.

Now add a new `mark` to indicate the current cursor position:

Expand Down
Binary file added docs/visualize/images/vega_lite_tutorial_3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/visualize/images/vega_lite_tutorial_4.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/visualize/images/vega_lite_tutorial_5.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/visualize/images/vega_lite_tutorial_6.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/visualize/images/vega_lite_tutorial_7.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.