Adds maps documentation #2376

kolchfa-aws · 2023-01-11T16:59:50Z

Fixes #897

Checklist

[x ] By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and subject to the Developers Certificate of Origin.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

Signed-off-by: Fanit Kolchina <[email protected]>

junqiu-lei · 2023-01-11T20:52:09Z

_dashboards/maps.md

+
+To get started, perform the following steps:
+
+1. On the top menu bar, go to **OpenSearch Dashboards > Maps**.


It now changed the place to under Plugins. opensearch-project/dashboards-maps#196

VijayanB · 2023-01-11T22:22:53Z

_dashboards/maps.md

+
+# Maps
+
+With OpenSearch Dashboards, you can create maps to visualize your geographical data. OpenSearch lets you construct map visualizations with multiple layers, combining data across different indexes. You can build each layer from a different data source either directly or using simple or ML-powered aggregations. Additionally, you can configure maps to show specific data at different zoom levels. OpenSearch maps are powered by the OpenSearch maps service, which uses vector tiles to render maps. 


what is ML-powered aggregations?

@VijayanB The feature review doc had "ML-enabled aggregations". Is that a better term? Or is it not applicable altogether?

Signed-off-by: Fanit Kolchina <[email protected]>

VijayanB · 2023-01-11T22:34:56Z

_dashboards/maps.md

+You can add either **data layers** or **reference layers** to the map:
+- **Data layers** let you visualize data from various data sources. 
+
+- **Reference layers** serve as basemaps. To use your own or a third-party map as a basemap, [add it as a **Custom map**](#adding-a-custom-map).


We renamed it to "Base layer"

VijayanB · 2023-01-11T22:36:28Z

_dashboards/maps.md

+
+1. In the **Custom type** dropdown, select **Tile Map Service (TMS)**. 
+1. Enter the TMS URL.
+1. (Optional) In **TMS attribution**, enter a TMS attribution for the basemap. For example, if you're using Maptiler, enter `Maptiler`. The name `Maptiler` will be displayed in the lower-right corner of the map.


We don't have to give Maptiler as an example, we can use something else "custom-map"

VijayanB · 2023-01-11T22:38:09Z

_dashboards/maps.md

+
+To change the default map settings, select **Default map** in the **Layers** panel. Under **Layer settings**, you can change the layer name and description and configure zoom levels and opacity for your layer:
+
+- **Zoom levels**: If you want to make a layer visible only on a certain range of zoom levels, you can specify the zoom levels for this layer either by entering them in the text boxes or by sliding the range slider to the desired values.


Shall we call out like, by default layer is visible in all zoom levels, you can update this range if you want otherwise.

VijayanB · 2023-01-11T22:40:25Z

_dashboards/maps.md

+
+## Adding a document layer
+
+Adding document layers lets you visualize your data. You can use a single index or multiple indexes as a data source for a visualization. 


We support one index pattern per document layer. Users can create multiple layers if they want to view multiple index pattern. I am not sure whether "You can use a single index or multiple indexes as a data source for a visualization." means same.

VijayanB · 2023-01-11T22:40:57Z

_dashboards/maps.md

+
+Adding document layers lets you visualize your data. You can use a single index or multiple indexes as a data source for a visualization. 
+
+OpenSearch supports displaying documents that contain both geopoint and geoshape fields on a map.


Suggested change

OpenSearch supports displaying documents that contain both geopoint and geoshape fields on a map.

Document layer supports displaying documents that contain both geo_point and geo_shape fields on a map.

Should the suggestion read "The document layer..."?

VijayanB · 2023-01-11T22:41:54Z

_dashboards/maps.md

+OpenSearch supports displaying documents that contain both geopoint and geoshape fields on a map.
+{: .note}
+
+The following example assumes that you have the `opensearch_dashboards_sample_data_flights` dataset installed. 


if not, do we have a link on how to install this sample dataset?

Added steps in this document

VijayanB · 2023-01-11T22:43:01Z

_dashboards/maps.md

+
+1. In the **Layers** panel, select the **Add layer** button.
+1. From the **Add layer** dialog, select **Data layer > Documents**.
+1. In **Data source**, select `opensearch_dashboards_sample_data_flights`. Alternatively, you can enter another index name or index pattern to visualize.


Suggested change

1. In **Data source**, select `opensearch_dashboards_sample_data_flights`. Alternatively, you can enter another index name or index pattern to visualize.

1. In **Data source**, select `opensearch_dashboards_sample_data_flights`. Alternatively, you can enter another index pattern to visualize.

VijayanB · 2023-01-11T22:44:00Z

_dashboards/maps.md

+1. In the **Layers** panel, select the **Add layer** button.
+1. From the **Add layer** dialog, select **Data layer > Documents**.
+1. In **Data source**, select `opensearch_dashboards_sample_data_flights`. Alternatively, you can enter another index name or index pattern to visualize.
+1. In **Geospatial field**, select a data field to be displayed in the visualization. In this example, select `DestLocation`.


Suggested change

1. In **Geospatial field**, select a data field to be displayed in the visualization. In this example, select `DestLocation`.

1. In **Geospatial field**, select a geospatial field (geo_point or geo_shape) to be displayed in the visualization. In this example, select `DestLocation`.

VijayanB · 2023-01-11T22:46:17Z

_dashboards/maps.md

+
+## Using tooltips to visualize additional data
+
+The map layers show geopoint and geoshape document fields as locations on the map. To add more information to the locations, you can use tooltips. For example, you may want to to show flight delay, destination weather, and destination country in the Flight destination layer. Perform the following steps to configure tooltips to show additional data:


Suggested change

The map layers show geopoint and geoshape document fields as locations on the map. To add more information to the locations, you can use tooltips. For example, you may want to to show flight delay, destination weather, and destination country in the Flight destination layer. Perform the following steps to configure tooltips to show additional data:

The Document layer show geo_point and geo_shape document fields as locations on the map. To add more information to the locations, you can use tooltips. For example, you may want to to show flight delay, destination weather, and destination country in the Flight destination layer. Perform the following steps to configure tooltips to show additional data:

Signed-off-by: Fanit Kolchina <[email protected]>

vagimeli

LGTM; minimal comments

_dashboards/maps.md

vagimeli · 2023-01-11T23:52:56Z

_dashboards/maps.md

+
+Adding document layers lets you visualize your data. You can use a single index or multiple indexes as a data source for a visualization. 
+
+OpenSearch supports displaying documents that contain both geopoint and geoshape fields on a map.


Should the suggestion read "The document layer..."?

vagimeli · 2023-01-11T23:54:13Z

_dashboards/maps.md

+1. In the **Layers** panel, select the **Add layer** button.
+1. From the **Add layer** dialog, select **Data layer > Documents**.
+1. In **Data source**, select `opensearch_dashboards_sample_data_flights`. Alternatively, you can enter another index pattern to visualize.
+1. In **Geospatial field**, select a geospatial field (geopoint or geoshape) to be displayed in the visualization. In this example, select `DestLocation`.


Do the fields need to be written the same as in the line 65 suggestion, if change is accepted?

I'll discuss with @natebower whether to use underscores in the field names.

vagimeli · 2023-01-11T23:56:19Z

_dashboards/maps.md

+
+## Filtering data
+
+To show a subset of the data in the index, filter the data. The following example filters the Flight destination data to see only United States destinations:


Lowercase "Flight" or capitalize it in line 87. Is the term referring the to proper name Flight destination?

I think lowercase works here. The name of the layer is Flight destination, but here I can refer to the generic concept.

vagimeli · 2023-01-11T23:59:13Z

_dashboards/maps.md

+
+## Using tooltips to visualize additional data
+
+Document layers show geopoint and geoshape document fields as locations on the map. To add more information to the locations, you can use tooltips. For example, you may want to to show flight delay, destination weather, and destination country in the Flight destination layer. Perform the following steps to configure tooltips to show additional data:


Confirm geopoint and geoshape spelling is consistent throughout. Confirm "Flight destination" spelling is consistent throughout.

After a conversation with @natebower, we're going with geopoint and geoshape since it is the simplest option that is easiest to use in multiple contexts.

In this line, I am referring to the layer name, and the layer name was capitalized, so Flight destination has correct capitalization here.

Would it make sense to bold the name of the layer so that it's clear that it's not just a capitalization error? If yes, apply globally. Also, it looks like either "data" or "information" should follow "country".

vagimeli · 2023-01-12T00:05:55Z

_dashboards/maps.md

+1. In the **Layers** panel, select **Flight destination**.
+1. Select **Tooltips**. 
+1. Select the **Show tooltips** checkbox.
+1. In the **Tooltip fields** dropdown, select the fields that you'd like to display. In this example, select `FlightDelay`, `DestWeather`, and `DestCountry`.


Change "dropdown" to "dropdown list" (per TERMS.md)

Signed-off-by: Fanit Kolchina <[email protected]>

JeffHuss

LGTM nice work!

natebower

@kolchfa-aws Please see my comments and changes and let me know if you have any questions. Thanks!

natebower · 2023-01-12T17:19:18Z

_dashboards/maps.md

+
+To change the default map settings, select **Default map** in the **Layers** panel. Under **Layer settings**, you can change the layer name and description and configure zoom levels and opacity for your layer:
+
+- **Zoom levels**: By default, a layer is visible at all zoom levels. If you want to make a layer visible only on a certain range of zoom levels, you can specify the zoom levels either by entering them in the text boxes or by sliding the range slider to the desired values.


"only for a certain range"?

natebower · 2023-01-12T17:23:16Z

_dashboards/maps.md

+
+1. In the **Custom type** dropdown list, select **Tile Map Service (TMS)**. 
+1. Enter the TMS URL.
+1. (Optional) In **TMS attribution**, enter a TMS attribution for the basemap. For example, if you're using a custom basemap, you can add its name to display in the lower-right corner of the map.


A word should follow "display". "display it"?

natebower · 2023-01-12T17:24:05Z

_dashboards/maps.md

+1. (Optional) In **TMS attribution**, enter a TMS attribution for the basemap. For example, if you're using a custom basemap, you can add its name to display in the lower-right corner of the map.
+1. Select the **Settings** tab to edit the layer settings.
+1. Enter the layer name in **Name**.
+1. (Optional) Enter layer description in **Description**.


Suggested change

1. (Optional) Enter layer description in **Description**.

1. (Optional) Enter the layer description in **Description**.

natebower · 2023-01-12T17:30:08Z

_dashboards/maps.md

+1. Select the **Settings** tab to edit layer settings.
+1. Enter `Flight destination` in **Name**.
+1. Select the **Update** button.
+1. To see more data, in the upper-right corner select the calendar icon dropdown list, then under **Quick select** choose **Last 15 days**. 


Suggested change

1. To see more data, in the upper-right corner select the calendar icon dropdown list, then under **Quick select** choose **Last 15 days**.

1. To see more data, in the upper-right corner, select the calendar icon dropdown list. Then under **Quick select**, choose **Last 15 days**.

natebower · 2023-01-12T17:31:39Z

_dashboards/maps.md

+1. Select the **Update** button.
+1. To see more data, in the upper-right corner select the calendar icon dropdown list, then under **Quick select** choose **Last 15 days**. 
+
+You should see the flight destination data similar to the following image:


Suggested change

You should see the flight destination data similar to the following image:

You should see the flight destination data, as in the following image.

natebower · 2023-01-12T17:41:20Z

_dashboards/maps.md

+
+## Refreshing data for a real-time dataset
+
+If you want to visualize a real-time dataset, after adding layers to the map use the following steps to set the refresh interval:


Suggested change

If you want to visualize a real-time dataset, after adding layers to the map use the following steps to set the refresh interval:

If you want to visualize a real-time dataset, after adding layers to the map, perform the following steps to set the refresh interval:

natebower · 2023-01-12T17:44:38Z

_dashboards/maps.md

+
+## Saving a map
+
+To save a map with all layers that you set up, perform the following steps:


Either "all the layers" or "every layer".

natebower · 2023-01-12T17:46:47Z

_dashboards/maps.md

+
+To save a map with all layers that you set up, perform the following steps:
+
+1. Select the **Save** button in the upper-right corner. This brings up the **Save map** dialog.


Let's not use the phrasal verb "brings up". How about something like "The Save map dialog appears."?

natebower · 2023-01-12T17:47:11Z

_dashboards/maps.md

+To save a map with all layers that you set up, perform the following steps:
+
+1. Select the **Save** button in the upper-right corner. This brings up the **Save map** dialog.
+1. In the **Title** textbox, enter the map name.


Suggested change

1. In the **Title** textbox, enter the map name.

1. In the **Title** text box, enter the map name.

natebower · 2023-01-12T17:47:26Z

_dashboards/maps.md

+
+1. Select the **Save** button in the upper-right corner. This brings up the **Save map** dialog.
+1. In the **Title** textbox, enter the map name.
+1. (Optional) In the **Description** textbox, enter map description.


Suggested change

1. (Optional) In the **Description** textbox, enter map description.

1. (Optional) In the **Description** text box, enter the map description.

Signed-off-by: Fanit Kolchina <[email protected]>

VijayanB · 2023-01-14T02:07:21Z

LGTM. Please retake snapshot since some of them are outdated. Thanks.

Signed-off-by: Fanit Kolchina <[email protected]>

* Adds maps documentation Signed-off-by: Fanit Kolchina <[email protected]> * Rewrites Signed-off-by: Fanit Kolchina <[email protected]> * Changed entry point for maps Signed-off-by: Fanit Kolchina <[email protected]> * Incorporated tech review comments Signed-off-by: Fanit Kolchina <[email protected]> * More tech review comments Signed-off-by: Fanit Kolchina <[email protected]> * Adds steps to install sample data Signed-off-by: Fanit Kolchina <[email protected]> * Minor edit Signed-off-by: Fanit Kolchina <[email protected]> * Incorporated doc review comments Signed-off-by: Fanit Kolchina <[email protected]> * Incorporated editorial comments Signed-off-by: Fanit Kolchina <[email protected]> * Updated the add layer dialog Signed-off-by: Fanit Kolchina <[email protected]> * Simplified adding sample dataset Signed-off-by: Fanit Kolchina <[email protected]> * Minor change Signed-off-by: Fanit Kolchina <[email protected]> * Added new images Signed-off-by: Fanit Kolchina <[email protected]> Signed-off-by: Fanit Kolchina <[email protected]>

This reverts commit 21f0d00.

Adds maps documentation

930c936

Signed-off-by: Fanit Kolchina <[email protected]>

kolchfa-aws requested a review from a team as a code owner January 11, 2023 16:59

kolchfa-aws self-assigned this Jan 11, 2023

Rewrites

85cbfa0

Signed-off-by: Fanit Kolchina <[email protected]>

kolchfa-aws added 3 - Tech review PR: Tech review in progress v2.5.0 'Issues and PRs related to version v2.5.0' labels Jan 11, 2023

junqiu-lei reviewed Jan 11, 2023

View reviewed changes

VijayanB reviewed Jan 11, 2023

View reviewed changes

Changed entry point for maps

9015558

Signed-off-by: Fanit Kolchina <[email protected]>

VijayanB reviewed Jan 11, 2023

View reviewed changes

hdhalter added the release-notes PR: Include this PR in the automated release notes label Jan 11, 2023

kolchfa-aws added 4 commits January 11, 2023 18:21

Incorporated tech review comments

93f68f0

Signed-off-by: Fanit Kolchina <[email protected]>

More tech review comments

387b32d

Signed-off-by: Fanit Kolchina <[email protected]>

Adds steps to install sample data

49b0d56

Signed-off-by: Fanit Kolchina <[email protected]>

Minor edit

83afcbf

Signed-off-by: Fanit Kolchina <[email protected]>

vagimeli approved these changes Jan 12, 2023

View reviewed changes

Incorporated doc review comments

2cb36de

Signed-off-by: Fanit Kolchina <[email protected]>

JeffHuss approved these changes Jan 12, 2023

View reviewed changes

natebower reviewed Jan 12, 2023

View reviewed changes

kolchfa-aws added 3 commits January 12, 2023 17:27

Incorporated editorial comments

2950354

Signed-off-by: Fanit Kolchina <[email protected]>

Updated the add layer dialog

416c5e8

Signed-off-by: Fanit Kolchina <[email protected]>

Simplified adding sample dataset

76ed338

Signed-off-by: Fanit Kolchina <[email protected]>

Minor change

6093c78

Signed-off-by: Fanit Kolchina <[email protected]>

hdhalter added 6 - Done but waiting to merge PR: The work is done and ready to merge and removed 3 - Tech review PR: Tech review in progress labels Jan 13, 2023

Added new images

04675e4

Signed-off-by: Fanit Kolchina <[email protected]>

VijayanB approved these changes Jan 14, 2023

View reviewed changes

kolchfa-aws merged commit 4760827 into main Jan 17, 2023

vagimeli added a commit that referenced this pull request Jan 26, 2023

Revert "Adds maps documentation (#2376)"

cf64b30

This reverts commit 21f0d00.

Naarcha-AWS deleted the Fix897-maps branch March 28, 2024 23:24


		To get started, perform the following steps:

		1. On the top menu bar, go to OpenSearch Dashboards > Maps.


		# Maps

		With OpenSearch Dashboards, you can create maps to visualize your geographical data. OpenSearch lets you construct map visualizations with multiple layers, combining data across different indexes. You can build each layer from a different data source either directly or using simple or ML-powered aggregations. Additionally, you can configure maps to show specific data at different zoom levels. OpenSearch maps are powered by the OpenSearch maps service, which uses vector tiles to render maps.


		To change the default map settings, select Default map in the Layers panel. Under Layer settings, you can change the layer name and description and configure zoom levels and opacity for your layer:

		- Zoom levels: If you want to make a layer visible only on a certain range of zoom levels, you can specify the zoom levels for this layer either by entering them in the text boxes or by sliding the range slider to the desired values.


		## Adding a document layer

		Adding document layers lets you visualize your data. You can use a single index or multiple indexes as a data source for a visualization.


		Adding document layers lets you visualize your data. You can use a single index or multiple indexes as a data source for a visualization.

		OpenSearch supports displaying documents that contain both geopoint and geoshape fields on a map.

	OpenSearch supports displaying documents that contain both geopoint and geoshape fields on a map.
	Document layer supports displaying documents that contain both geo_point and geo_shape fields on a map.

	1. In Data source, select `opensearch_dashboards_sample_data_flights`. Alternatively, you can enter another index name or index pattern to visualize.
	1. In Data source, select `opensearch_dashboards_sample_data_flights`. Alternatively, you can enter another index pattern to visualize.

	1. In Geospatial field, select a data field to be displayed in the visualization. In this example, select `DestLocation`.
	1. In Geospatial field, select a geospatial field (geo_point or geo_shape) to be displayed in the visualization. In this example, select `DestLocation`.


		## Using tooltips to visualize additional data

		The map layers show geopoint and geoshape document fields as locations on the map. To add more information to the locations, you can use tooltips. For example, you may want to to show flight delay, destination weather, and destination country in the Flight destination layer. Perform the following steps to configure tooltips to show additional data:

	The map layers show geopoint and geoshape document fields as locations on the map. To add more information to the locations, you can use tooltips. For example, you may want to to show flight delay, destination weather, and destination country in the Flight destination layer. Perform the following steps to configure tooltips to show additional data:
	The Document layer show geo_point and geo_shape document fields as locations on the map. To add more information to the locations, you can use tooltips. For example, you may want to to show flight delay, destination weather, and destination country in the Flight destination layer. Perform the following steps to configure tooltips to show additional data:


		## Filtering data

		To show a subset of the data in the index, filter the data. The following example filters the Flight destination data to see only United States destinations:


		## Using tooltips to visualize additional data

		Document layers show geopoint and geoshape document fields as locations on the map. To add more information to the locations, you can use tooltips. For example, you may want to to show flight delay, destination weather, and destination country in the Flight destination layer. Perform the following steps to configure tooltips to show additional data:


		To change the default map settings, select Default map in the Layers panel. Under Layer settings, you can change the layer name and description and configure zoom levels and opacity for your layer:

		- Zoom levels: By default, a layer is visible at all zoom levels. If you want to make a layer visible only on a certain range of zoom levels, you can specify the zoom levels either by entering them in the text boxes or by sliding the range slider to the desired values.

	1. (Optional) Enter layer description in Description.
	1. (Optional) Enter the layer description in Description.

	1. To see more data, in the upper-right corner select the calendar icon dropdown list, then under Quick select choose Last 15 days.
	1. To see more data, in the upper-right corner, select the calendar icon dropdown list. Then under Quick select, choose Last 15 days.

	You should see the flight destination data similar to the following image:
	You should see the flight destination data, as in the following image.


		## Refreshing data for a real-time dataset

		If you want to visualize a real-time dataset, after adding layers to the map use the following steps to set the refresh interval:


		## Saving a map

		To save a map with all layers that you set up, perform the following steps:


		To save a map with all layers that you set up, perform the following steps:

		1. Select the Save button in the upper-right corner. This brings up the Save map dialog.

	1. In the Title textbox, enter the map name.
	1. In the Title text box, enter the map name.

Adds maps documentation #2376

Adds maps documentation #2376

Conversation

kolchfa-aws commented Jan 11, 2023

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

VijayanB Jan 11, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vagimeli left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JeffHuss left a comment

Choose a reason for hiding this comment

natebower left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

VijayanB commented Jan 14, 2023

VijayanB Jan 11, 2023 •

edited

Loading

	1. (Optional) In the Description textbox, enter map description.
	1. (Optional) In the Description text box, enter the map description.