[DOCS] New tutorial for exploring Kibana with sample data set (#21699) (#22070)

docs/getting-started.asciidoc

@@ -3,14 +3,17 @@
 
 [partintro]
 --
-Ready to get some hands-on experience with Kibana?
-This tutorial shows you how to:
 
-* Load a sample data set into Elasticsearch
-* Define an index pattern
-* Discover and explore the sample data
-* Visualize the data
-* Assemble visualizations into a dashboard
+Ready to get some hands-on experience with {kib}? There are two ways to start:
+
+* <<tutorial-sample-data, Explore {kib} using the Flights dashboard>>
++
+Load the Flights sample data and dashboard with one click and start 
+interacting with {kib} visualizations in seconds.
+
+* <<tutorial-build-dashboard, Build your own dashboard>> 
++
+Manually load a data set and build your own visualizations and dashboard.
 
 Before you begin, make sure you've <<install, installed Kibana>> and established
 a {kibana-ref}/connect-to-elasticsearch.html[connection to Elasticsearch].
@@ -22,6 +25,22 @@ If you are running our https://cloud.elastic.co[hosted Elasticsearch Service]
 on Elastic Cloud, you can access Kibana with a single click.
 --
 
+include::getting-started/tutorial-sample-data.asciidoc[]
+
+include::getting-started/tutorial-sample-filter.asciidoc[]
+
+include::getting-started/tutorial-sample-query.asciidoc[]
+
+include::getting-started/tutorial-sample-discover.asciidoc[]
+
+include::getting-started/tutorial-sample-edit.asciidoc[]
+
+include::getting-started/tutorial-sample-inspect.asciidoc[]
+
+include::getting-started/tutorial-sample-remove.asciidoc[]
+
+include::getting-started/tutorial-full-experience.asciidoc[]
+
 include::getting-started/tutorial-load-dataset.asciidoc[]
 
 include::getting-started/tutorial-define-index.asciidoc[]
@@ -32,4 +51,6 @@ include::getting-started/tutorial-visualizing.asciidoc[]
 
 include::getting-started/tutorial-dashboard.asciidoc[]
 
+include::getting-started/tutorial-inspect.asciidoc[]
+
 include::getting-started/wrapping-up.asciidoc[]

docs/getting-started/tutorial-dashboard.asciidoc

@@ -1,14 +1,14 @@
 [[tutorial-dashboard]]
-== Putting it Together in a Dashboard
+=== Displaying your visualizations in a dashboard
 
 A dashboard is a collection of visualizations that you can arrange and share.
-Here you'll build a dashboard that contains the visualizations you saved during
+You'll build a dashboard that contains the visualizations you saved during
 this tutorial.
 
 . Open *Dashboard*.
 . Click *Create new dashboard*.
 . Click *Add*.
-. Click *Bar Example*, *Map Example*, *Markdown Example*, and *Pie Example*.
+. Add *Bar Example*, *Map Example*, *Markdown Example*, and *Pie Example*.
 
 
 Your sample dashboard look like this:

docs/getting-started/tutorial-define-index.asciidoc

@@ -1,5 +1,5 @@
 [[tutorial-define-index]]
-== Defining Your Index Patterns
+=== Defining your index patterns
 
 Index patterns tell Kibana which Elasticsearch indices you want to explore.
 An index pattern can match the name of a single index, or include a wildcard
@@ -10,7 +10,7 @@ series of indices in the format `logstash-YYYY.MMM.DD`. To explore all
 of the log data from May 2018, you could specify the index pattern
 `logstash-2018.05*`.
 
-Create patterns for the Shakespeare data set, which has an
+You'll create patterns for the Shakespeare data set, which has an
 index named `shakespeare,` and the accounts data set, which has an index named
 `bank.` These data sets don't contain time-series data.
 

docs/getting-started/tutorial-discovering.asciidoc

@@ -1,12 +1,16 @@
 [[tutorial-discovering]]
-== Discovering Your Data
+=== Discovering your data
 
 Using the Discover application, you can enter
 an {ref}/query-dsl-query-string-query.html#query-string-syntax[Elasticsearch
 query] to search your data and filter the results.
 
-. Open *Discover*. The `shakes*` pattern is the current index pattern.
-. Click the caret to the right of `shakes*`, and select `ba*`.
+. Open *Discover*. 
++
+The current index pattern appears below the filter bar, in this case `shakes*`.
+You might need to click *New* in the menu bar to refresh the data.
+
+. Click the caret to the right of the current index pattern, and select `ba*`.  
 . In the search field, enter the following string:
 +
 [source,text]
@@ -19,8 +23,8 @@ excess of 47,500. It returns results for account numbers 8, 32, 78, 85, and 97.
 image::images/tutorial-discover-2.png[]
 
 By default, all fields are shown for each matching document. To choose which
-fields to display, hover the mouse over the the list of *Available Fields*
-and then click *add* next to each field you want include.
+fields to display, hover the pointer over the the list of *Available Fields*
+and then click *add* next to each field you want include as a column in the table.
 
 For example, if you add the `account_number` field, the display changes to a list of five
 account numbers.

docs/getting-started/tutorial-full-experience.asciidoc

@@ -0,0 +1,12 @@
+[[tutorial-build-dashboard]]
+== Building your own dashboard
+
+Ready to load some data and build a dashboard? This tutorial shows you how to:
+
+* Load a data set into Elasticsearch
+* Define an index pattern
+* Discover and explore the data
+* Visualize the data
+* Add visualizations to a dashboard
+* Inspect the data behind a visualization
+

docs/getting-started/tutorial-inspect.asciidoc

@@ -0,0 +1,24 @@
+[[tutorial-inspect]]
+=== Inspecting the data
+
+Seeing visualizations of your data is great, 
+but sometimes you need to look at the actual data to
+understand what's really going on. You can inspect the data behind any visualization
+and view the {es} query used to retrieve it.
+
+. In the dashboard, hover the pointer over the pie chart.
+. Click the icon in the upper right. 
+. From the *Options* menu, select *Inspect*.
++
+[role="screenshot"]
+image::images/tutorial-full-inspect1.png[]
+
+You can also look at the query used to fetch the data for the visualization. 
+
+. Open the *View:Data* menu and select *Requests*. 
+. Click the tabs to look at the request statistics, the Elasticsearch request, 
+and the response in JSON. 
+. To close the Inspector, click X in the upper right.
++
+[role="screenshot"]
+image::images/tutorial-full-inspect2.png[]

docs/getting-started/tutorial-load-dataset.asciidoc

@@ -1,5 +1,5 @@
 [[tutorial-load-dataset]]
-== Loading Sample Data
+=== Loading sample data
 
 This tutorial requires three data sets:
 
@@ -16,6 +16,8 @@ Two of the data sets are compressed. To extract the files, use these commands:
 unzip accounts.zip
 gunzip logs.jsonl.gz
 
+==== Structure of the data sets
+
 The Shakespeare data set has this structure:
 
 [source,json]
@@ -54,11 +56,18 @@ The logs data set has dozens of different fields. Here are the notable fields fo
     "@timestamp": "date"
 }
 
+==== Set up mappings
+
 Before you load the Shakespeare and logs data sets, you must set up {ref}/mapping.html[_mappings_] for the fields.
 Mappings divide the documents in the index into logical groups and specify the characteristics
 of the fields. These characteristics include the searchability of the field
 and whether it's _tokenized_, or broken up into separate words.
 
+NOTE: If security is enabled, you must have the `all` Kibana privilege to run this tutorial.
+You must also have the `create`, `manage` `read`, `write,` and `delete` 
+index privileges. See {xpack-ref}/security-privileges.html[Security Privileges] 
+for more information.
+
 In Kibana *Dev Tools > Console*, set up a mapping for the Shakespeare data set:
 
 [source,js]
@@ -149,6 +158,8 @@ PUT /logstash-2015.05.20
 
 The accounts data set doesn't require any mappings.
 
+==== Load the data sets
+
 At this point, you're ready to use the Elasticsearch {ref}/docs-bulk.html[bulk]
 API to load the data sets:
 

docs/getting-started/tutorial-sample-data.asciidoc

@@ -0,0 +1,32 @@
+[[tutorial-sample-data]]
+== Explore {kib} using the Flight dashboard
+
+You’re new to {kib} and want to try it out. With one click, you can install
+the Flights sample data and start interacting with Kibana. 
+
+The Flights data set contains data for four airlines.  
+You can load the data and preconfigured dashboard from the {kib} home page. 
+
+. On the home page, click the link next to  *Sample data*. 
+. On the *Sample flight data* card, click *Add*.
+. Click *View data*.
+
+You’re taken to the *Global Flight* dashboard, a collection of charts, graphs, 
+maps, and other visualizations of the the data in the `kibana_sample_data_flights` index.
+
+[role="screenshot"]
+image::images/tutorial-sample-dashboard.png[]
+
+In this tutorial, you’ll learn to:
+
+* Filter the data
+* Query the data
+* Discover the data
+* Edit a visualization
+* Inspect the data behind the scenes
+
+NOTE: If security is enabled, you must have the `all` Kibana privilege.
+You must also have access to the `kibana_sample_data_flights` index with 
+the `read`, `write,` and `manage` privileges. See {xpack-ref}/security-privileges.html[Security Privileges] 
+for more information.
+

docs/getting-started/tutorial-sample-discover.asciidoc

@@ -0,0 +1,27 @@
+[[tutorial-sample-discover]]
+=== Using Discover
+
+In the Discover application, the Flight data is presented in a table. You can 
+interactively explore the data, including searching and filtering.
+
+* In the side navigation, select *Discover*.
+
+The current index pattern appears below the filter bar. An
+<<index-patterns, index pattern>> tells {kib} which {es} indices you want to 
+explore.
+
+The `kibana_sample_data_flights` index contains a time field. A histogram
+shows the distribution of documents over time. 
+
+[role="screenshot"]
+image::images/tutorial-sample-discover1.png[]
+
+By default, all fields are shown for each matching document. To choose which fields to display, 
+hover the pointer over the the list of *Available Fields* and then click *add* next 
+to each field you want include as a column in the table.
+
+For example, if you add the `DestAirportID` and `DestWeather` fields, 
+the display includes columns for those two fields:
+
+[role="screenshot"]
+image::images/tutorial-sample-discover2.png[]

docs/getting-started/tutorial-sample-edit.asciidoc

@@ -0,0 +1,45 @@
+[[tutorial-sample-edit]]
+=== Editing a visualization
+
+You have edit permissions for the *Global Flight* dashboard so you can change 
+the appearance and behavior of the visualizations. For example, you might want 
+to see which airline has the lowest average fares.
+
+. Go to the *Global Flight* dashboard. 
+. In the menu bar, click *Edit*.
+. In the *Average Ticket Price* visualization, click the gear icon in 
+the upper right.
+. From the *Options* menu, select *Edit visualization*.
+
+==== Edit a metric visualization 
+
+*Average Ticket Price* is a metric visualization.
+To specify which groups to display 
+in this visualization, you use an {es} {ref}/search-aggregations.html[bucket aggregation]. 
+This aggregation sorts the documents that match your search criteria into different 
+categories, or buckets.
+
+. In the *Buckets* pane, select *Split Group*.
+. In the *Aggregation* dropdown menu, select *Terms*.
+. In the *Field* dropdown, select *Carrier*.
+. Set *Descending* to four.
+. Click *Apply changes* image:images/apply-changes-button.png[].
+
+You now see the average ticket price for all four airlines.
+
+[role="screenshot"]
+image::images/tutorial-sample-edit1.png[]
+
+==== Save the changes
+
+. In the menu bar, click *Save*.
+. Leave the visualization name unchanged and click *Save*.
+. Go to the *Global Flight* dashboard. 
+. Resize the panel for the *Average Ticket Price* visualization by dragging the
+handle in the lower right.  
+You can also rearrange the visualizations by clicking the header and dragging.
+. In the menu bar, click *Save* and then confirm the save.
++
+[role="screenshot"]
+image::images/tutorial-sample-edit2.png[]
+

docs/getting-started/tutorial-sample-filter.asciidoc

@@ -0,0 +1,23 @@
+[[tutorial-sample-filter]]
+=== Filtering the data
+
+Many visualizations in the *Global Flight* dashboard are interactive. You can 
+apply filters to modify the view of the data across all visualizations.
+
+. In the *Controls* visualization, set an *Origin City* and a *Destination City*.
+. Click *Apply changes*.
++
+The `OriginCityName` and the `DestCityName` fields are filtered to match 
+the data you specified. 
++
+For example, this dashboard shows the data for flights from London to Newark
+and Pittsburgh. 
++
+[role="screenshot"]
+image::images/tutorial-sample-filter.png[]
++
+. To remove the filters, in the *Controls* visualization, click *Clear form*, and then
+*Apply changes*.
+
+You can also add filters manually.  In the filter bar, click *Add a Filter*
+and specify the data you want to view.

docs/getting-started/tutorial-sample-inspect.asciidoc

@@ -0,0 +1,24 @@
+[[tutorial-sample-inspect]]
+=== Inspecting the data
+
+Seeing visualizations of your data is great, 
+but sometimes you need to look at the actual data to
+understand what's really going on. You can inspect the data behind any visualization
+and view the {es} query used to retrieve it.
+
+. Hover the pointer over the *Flight Count and Average Ticket Price* visualization.
+. Click the icon in the upper right. 
+. From the *Options* menu, select *Inspect*.
++
+[role="screenshot"]
+image::images/tutorial-sample-inspect1.png[]
+
+You can also look at the query used to fetch the data for the visualization. 
+
+. Open the *View: Data* menu and select *Requests*. 
+. Click the tabs to look at the request statistics, the Elasticsearch request, 
+and the response in JSON. 
+. To close the editor, click X in the upper right.
++
+[role="screenshot"]
+image::images/tutorial-sample-inspect2.png[]

docs/getting-started/tutorial-sample-query.asciidoc

@@ -0,0 +1,30 @@
+[[tutorial-sample-query]]
+=== Querying the data
+
+You can enter an {es} query to narrow the view of the data.
+
+. To find all flights out of Rome, submit this query:
++
+[source,text]
+OriginCityName:Rome   
+
+. For a more complex query with AND and OR, try this:
++
+[source,text]
+OriginCityName:Rome AND (Carrier:JetBeats OR "Kibana Airlines")
++
+The dashboard updates to show data for the flights out of Rome on JetBeats and 
+{kib} Airlines.  
++
+[role="screenshot"]
+image::images/tutorial-sample-query.png[]
+
+. When you are finished exploring the dashboard, remove the query by 
+clearing the contents in the query bar and pressing Enter.
+
+In general, filters are faster than queries. For more information, see {ref}/query-filter-context.html[Query and filter context].
+
+TIP: {kib} has an experimental autocomplete feature that can 
+help jumpstart your queries. To turn on this feature, click *Options* on the 
+right of the query bar and opt in. With autocomplete enabled, 
+search suggestions are displayed when you start typing your query.  

docs/getting-started/tutorial-sample-remove.asciidoc

@@ -0,0 +1,18 @@
+[[tutorial-sample-remove]]
+=== Wrapping up
+
+When you’re done experimenting with the sample data set, you can remove it. 
+
+. Go to the {kib} home page and click the link next to  *Sample data*. 
+. On the *Sample flight data* card, click *Remove*.
+
+Now that you have a handle on the {kib} basics, you might be interested in:
+
+* <<tutorial-build-dashboard, Building your own dashboard>>.  You’ll learn how to load your own 
+data, define an index pattern, and create visualizations and dashboards. 
+* <<visualize>>. You’ll find information about all the visualization types 
+{kib} has to offer.
+* <<dashboard>>. You have the ability to share a dashboard, or embed the dashboard in a web page.
+* <<discover>>. You'll learn more about searching data and filtering by field.
+
+

docs/getting-started/tutorial-visualizing.asciidoc

@@ -1,5 +1,5 @@
 [[tutorial-visualizing]]
-== Visualizing Your Data
+=== Visualizing your data
 
 In the Visualize application, you can shape your data using a variety
 of charts, tables, and maps, and more. You'll create four
@@ -19,7 +19,7 @@ gain insight into the account balances in the bank account data.
 [role="screenshot"]
 image::images/tutorial-visualize-wizard-step-2.png[]
 
-=== Pie Chart
+=== Pie chart
 
 Initially, the pie contains a single "slice."
 That's because the default search matched all documents.
@@ -73,15 +73,17 @@ in a ring around the balance ranges.
 [role="screenshot"]
 image::images/tutorial-visualize-pie-3.png[]
 
-To save this chart so you can use it later, click *Save* in the top menu bar
-and enter `Pie Example`.
+To save this chart so you can use it later:
 
-=== Bar Chart
+* Click *Save* in the top menu bar and enter `Pie Example`.
+
+=== Bar chart
 
 You'll use a bar chart to look at the Shakespeare data set and compare
 the number of speaking parts in the plays.
 
-Create a *Vertical Bar* chart and set the search source to `shakes*`.
+* Create a *Vertical Bar* chart and set the search source to `shakes*`.
+
 Initially, the chart is a single bar that shows the total count
 of documents that match the default wildcard query.
 
@@ -120,32 +122,12 @@ that play.
 
 Notice how the individual play names show up as whole phrases, instead of
 broken into individual words. This is the result of the mapping
-you did at the beginning of the tutorial, when your marked the `play_name` field
+you did at the beginning of the tutorial, when you marked the `play_name` field
 as `not analyzed`.
 
-
-////
-You might
-also be curious to see which plays make the greatest demands on an
-individual actor. Let's show the maximum number of speeches for a given part.
-
-. Click *Add metrics* to add a Y-axis aggregation.
-. Set *Aggregation* to `Max` and *Field* to `speech_number`.
-. Click *Metrics & Axes* and then change *Mode* from `stacked` to `normal`.
-. Click  *Apply changes* image:images/apply-changes-button.png[].
-
-[role="screenshot"]
-image::images/tutorial-visualize-bar-3.png[]
-
-The play Love's Labours Lost has an unusually high maximum speech number compared to the other plays.
-
-Note how the *Number of speaking parts* Y-axis starts at zero, but the bars don't begin to differentiate until 18. To
-make the differences stand out, starting the Y-axis at a value closer to the minimum, go to Options and select
-*Scale Y-Axis to data bounds*.
-////
 *Save* this chart with the name `Bar Example`.
 
-=== Coordinate Map
+=== Coordinate map
 
 Using a coordinate map, you can visualize geographic information in the log file sample data.
 
@@ -175,18 +157,6 @@ You can navigate the map by clicking and dragging.  The controls
 on the top left of the map enable you to zoom the map and set filters.
 Give them a try.
 
-////
-- Zoom image:images/viz-zoom.png[] buttons,
-- *Fit Data Bounds*
-image:images/viz-fit-bounds.png[] button to zoom to the lowest level that
-includes all the points.
-- Include or exclude a rectangular area
-by clicking the *Latitude/Longitude Filter* image:images/viz-lat-long-filter.png[]
-button and drawing a bounding box on the map. Applied filters are displayed
-below the query bar. Hovering over a filter displays controls to toggle,
-pin, invert, or delete the filter.
-
-////
 [role="screenshot"]
 image::images/tutorial-visualize-map-3.png[]
 

docs/getting-started/wrapping-up.asciidoc

@@ -1,5 +1,5 @@
 [[wrapping-up]]
-== Wrapping Up
+=== Wrapping up
 
 Now that you have a handle on the basics, you're ready to start exploring
 your own data with Kibana.