Enhanced Coordinate Map

The Enhanced Coordinate Map visualization displays a geographic area that is overlaid with circles. The circles are keyed to the data that is determined by the buckets that you specify.

The default tilemap server service that is used to display map tiles, Open Street Maps, has limited features. Particularly in a production setting, it is recommended that you choose another tilemap provider and configure the tilemap settings in the investigate.yml file.

Configuration

Configuring external tilemap providers

You can use existing free or paid tilemap providers or build and serve your own tilemap tiles.

After you have setup your own tilemap provider, configure these tilemap settings in investigate.yml to have map visualizations render these tiles.

For example, to use an OpenStreetMap default provider, the configuration YAML settings would look like:

tilemap:
  url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
  options:
    attribution: '© [OpenStreetMap]("http://www.openstreetmap.org/copyright")'
    subdomains:
      - a

The Data Tab

Metrics

The default metrics aggregation for a coordinate map is the Count aggregation. You can select any of the following aggregations as the metrics aggregation:

  • Count (total number of documents present in the aggregation)

  • Average

  • Sum

  • Min

  • Max

  • Unique Count (total number of unique values present in the specified field within the aggregation)

When you select any of the above aggregations except Count, a Field dropdown is displayed from which you can select a field that is valid for the selected aggregation).

For more information, see Y-axis aggregations.

Enter a string in the Custom Label field to change the display label.

Clicking Advanced opens a field where you can enter a viable JSON input that acts on the field selected for the metrics aggregation. For example, the following JSON multiplies the number of employees by 1,000:

{"script" : "doc['number_of_employees'].value * 1000"}

Buckets

Coordinate maps use the geohash aggregation. Select a field, typically coordinates, from the box.

  • The Change precision on map zoom check box is selected by default. Clear the check box to switch off this behavior. The Precision slider determines the granularity of the results displayed on the map. See the documentation for the geohash grid aggregation for details on the area specified by each precision level.

Higher precision increases memory usage for the browser displaying Siren Investigate as well as for the underlying Elasticsearch cluster.
  • The place markers off grid (use geocentroid) box is checked by default. When this box is checked, the markers are placed in the center of all the documents in that bucket. When cleared, the markers are placed in the center of the geohash grid cell. Leaving this checked generally results in a more accurate visualization.

You can customize your visualization. For more information, see Customizing aggregations.

The Options Tab

Map Collar Scale

A scaling factor for selecting which documents to use for the aggregation. A setting of 1 will select documents within the map extent, 2 will select documents within 2 times the size of the map extent, while a value of 0.9 will scale the selection to be 0.9 times the size of the map extent. The purpose of this feature is to avoid excessive fetches to Elasticsearch or slower performance due to too many results being fetched.

Map type

Select one of the following options from the box.

  • Scaled Circle Markers - Scale the size of the markers based on the metric aggregation’s value.

  • Shaded Circle Marker - Displays the markers with different shades based on the metric aggregation’s value.

  • Shaded Geohash Grid - Displays the rectangular cells of the geohash grid instead of circular markers, with different shades based on the metric aggregation’s value.

  • Heatmap - A heat map applies blurring to the circle markers and applies shading based on the amount of overlap. Heatmaps have the following options:

    • Radius: Sets the size of the individual heatmap dots.

    • Blur: Sets the amount of blurring for the heatmap dots.

    • Maximum zoom: Tilemaps in Siren Investigate support 18 zoom levels. This slider defines the maximum zoom level at which the heatmap dots appear at full intensity.

    • Minimum opacity: Sets the opacity cutoff for the dots.

    • Show Tooltip: Check this box to have a tooltip with the values for a given dot when the cursor is on that dot.

Tooltip Formatter

Select from the following options:

  • Metric Value - A tooltip containing the coordinates and the metric value specified on the Data tab

  • Visualization - The option to add a Visualization as a tooltip. The contents of the visualization will be an aggregation based on the aggregation the tool tip is being applied to.

Close tooltip on mouseout

When mouse is hovered over aggregation a tooltip will appear. When the mouse is moved away from aggregation, the tool tip will disappear if this box is checked; it will remain if unchecked.

Legend Scale

Configuration settings for how the aggregation is displayed on legend +

  • Dynamic - Linear - Each class in the legend has the same size (e.g. values from 0 to 16 and 4 classes, each class has a size of 4)

  • Dynamic - Uneven - Each class will have the same number of documents inside, useful when data is unevenly distributed between the maximum and minimum ranges

  • Static - Manual specification of colors, values and number of classes for the legend scale

Scroll Wheel Zoom

When checked, it is possible to use the mouse scroll wheel to toggle map zoom level. (+ and - work toggle zoom regardless of this)

Desaturate map tiles

Desaturates the map’s color to make the markers stand out more clearly.

Synchronize map

Synchronize the map canvas of this visualization with all other visualizations present on a dashboard that also have this option selected

Auto-fit map to data

Automatic zoom to include all Aggregations when filters are altered. This includes time filter. Disabled when panning or zooming.

WMS compliant map server

Check this box to enable the use of a third-party mapping service that complies with the Web Map Service (WMS) standard. Specify the following elements: +

  • WMS url: The URL for the WMS map service.

  • WMS layers: A comma-separated list of the layers to use in this visualization. Each map server provides its own list of layers.

  • WMS version: The WMS version used by this map service.

  • WMS format: The image format used by this map service. The two most common formats are image/png and image/jpeg.

  • WMS attribution: An optional, user-defined string that identifies the map source. Maps display the attribution string in the lower right corner.

  • WMS styles: A comma-separated list of the styles to use in this visualization. Each map server provides its own styling options.

If you need to display custom layers for the Region Map visualization, a geospatial server may provide the solution. See Configuring GeoServer.
Point of Interest layers

Add any Elasticsearch index with a geo_point or geo_shape field as a marker or polygon layer:

  • You can draw geo_point type POI layers by using the Marker Clustering process.

  • You can create geo_shape type POI layers to enable viewing, pop-ups, and to create geo-filters. Geo-filters are applied to aggregations, other POI layers and other visualizations when on the dashboards (see Apply filters below).

    To render a geo_shape field on the map, it is required for an index to also have a geo_point field type

image

Configuration options for POI layers:

  • Saved Search - Select any elasticsearch index from the dropdown menu. Note - will need a geo point field

  • Geospatial Field -  Select a geo point field within the Saved Search

  • Styling

    • For geo_point - Set the size of the marker to appear for each document

    • For geo_shape - Set color in Hex value form

  • Popup Content - Selecting fields to appear on popup tooltip

  • Limit - The number of markers that are allowed to appear for this Point of Interest layer. The default is 100

  • Apply Filters - Whether or not to include filters from Selection tools or geo_shape type POI layers, a different visualization on the same Dashboard or filters from other Dashboards applied through relational Navigator

Drag and drop POI Layers

You can also create a POI Layer when in Dashboard view. Simply drag and drop a dashboard that has a main search with a geo_point field. If the main search has multiple spatial fields, a modal will appear prompting you to select one.

The filters from the other dashboard will be applied and can be viewed by hovering over the filter icon in the layer control. Drag and drop layers will not be saved and can be removed at any point by clicking the remove layer button in the layer control

image
image

Configuration options for the use of a third-party mapping service that complies with the Web Map Service standard. Multiple layers (or layer groups) can be loaded. Many third party mapping services are available, and some of these are described in ifdef::output-html[Configuring GeoServer.]

  • Layer Name - A customizable label to appear in the map’s layer view (image)

  • Url - The URL for the WMS map service

  • WMS Layers - This is where layers (or layer groups) can be specified from a WMS server. There are two options:

    • If you have added a URL to a CORS-enabled WMS server - Investigate will internally run a WMS getCapabilities request and will populate a list of layers that can be added by clicking ①. These can be ordered, by clicking and dragging ② as below. The layer at the top of the list is drawn furthest in the background.

      image
    • If your URL is not a CORS-enabled WMS server - The UI will remain the same. You can order your layers, separated by a comma. The first layer you specify will be drawn the furthest in the background.

      image

      You can still see the available layers for the WMS by running a getCapabilities request. Below is an example from a local instance of Geoserver:

      http://localhost:8080/geoserver/wms?SERVICE=WMS&REQUEST=GetCapabilities

  • CQL Filter - Allows you to query your spatial layers as parameters in WMS requests

  • Min Zoom Level - The minimum zoom level that the WMS request will be visible

  • Max Zoom Level - The maximum zoom level that the WMS request will be visible

  • Max Features - The maximum number of features, up to a maximum of 10,000, to be rendered per tile from the specified layer(s). Note - Max features can be configured in the WMS, which overrides this setting

  • Styles - A comma-separated list of the styles for your layer. If you have access to the WMS server, you can assign defaults for these and it is possible for this field to be left blank. Otherwise, each map server provides its own styling options

  • Output Format - The image format to be returned by the WMS. The two most common formats are image/png and image/jpeg. Default is image/png

  • Non Tiled - The option to send the WMS request as one complete image to fit the map extent, or to send it in multiple tiles

  • Visible On Load - Check this option to draw the layer when the visualization is loaded. Note - this will be over ridden if a user saves their dashboard state

  • Elasticsearch WMS Options - Configuration options for WMS request

    • Aggregation - Allows for the customization of geohash request from WMS using elasticgeo. Example of aggregation WMS request using the company index in Siren’s classic demo (“location” has a Geo_Point field type): { "agg": { "geohash_grid": { "field": "location" } } }

    • Sync Filters - When checked, the WMS response includes the filters made using Selection tools, visualizations in the same and visualizations from other dashboards.

image

This allows for point, linestring (including multi-linestring) and polygon (including multi-polygon) types to be rendered onto the Enhanced Coordinate Map. To create a geo-filter, click a polygon.

Point layers from WFS sources will not cluster. Instead, single document features are drawn.

See image section above for description on Layer Name, Url and WFS Layers fields. For details on setting up a WFS server, see the Configuring GeoServer guide. Additional fields specific for editing WFS layers:

  • Styling - Set color in Hex value form and specify the size of the marker to display on map

  • Output Format - The format that your spatial server is capable of responding with. The format for ArcGis Server is GeoJSON, and the format for Geoserver is JSON.

  • Popup Content - To configure a pop-up tooltip, create a comma-separated list of fields in the properties object of your GeoJSON features. For example, the parameter City_name,Pop_est adds the city name and the estimated population fields to each feature that is added to the map. Note: This parameter is case-sensitive.

Marker clustering

Marker clustering is a method that allows all documents on the current map canvas to be represented at once. It is used by Point of Interest layers and Stored Layer sources.

How does it work?

Each time this layer type is re-rendered, the following two queries are used:

  • Firstly, a geo-hash aggregation query is initiated. Based on this query, geo-hashes that have the least number of documents present are selected up to the limit that is configured. These selected geo-hashes are removed and geo-filters are created for these instead.

  • Secondly, a document query is initiated to retrieve individual documents in these areas. The configured Map Collar Scale aggregation is used for both queries.

How does it look?

The result is displayed in the following image. The cluster can be distinguished by the number (391). When you hover your cursor over a cluster, the corresponding geo-hash is displayed. When a marker that corresponds to one document is hovered over, a pop-up window can be displayed if it is configured. For more information, see Stored Layers and POI for respective configuration steps.

Example of marker clustering

Configuring stored layers

Before you begin, ensure that you have ingested the data for stored layers. For more information about ingesting stored layer data, see Loading Stored Layers into Elasticsearch. You can configure the stored layers by modifying the following parameters:

  • Spatial path - Defines the path that corresponds to a layer, for example, continents/europe/ireland.

The default configuration does not require the spatial_path attribute to be defined. Values will be taken from it if they are not found within the The cascading configuration process.
  • Icon - Defines the favicon that is displayed for points on a map and layer control.

  • Color - Defines the color that is displayed on a map and in the Layer Control dialog.

  • Size - Defines the display size of points on a map.

  • Popup Fields - Defines the content of the tooltips that appear when the cursor moves over features.

  • Min Visible Zoom - The minimum map zoom a layer will be visible on the map

  • Max Visible Zoom - The maximum map zoom a layer will be visible on the map

It is important to consider the levels of zoom that you want to configure in your maps. For more information about Zoom levels, see this explanation on the LeafletJS website.

The cascading configuration process

A cascading process, which is similar to CSS, is used to assign configurations to each layer. Using this process, the most specific spatial_path to the given layer is checked for the presence of the configuration parameters first. After this check is complete, the spatial_path chain is followed and default values are assigned if a parameter is missing a configuration.

For more information, see the Detailed example of a stored layer configuration.

Configurations by parameter or field

You can configure some parameters by using one of the following methods:

  • The parameter method outlines the exact parameter to use on the map. Parameters are configured by a string.

  • The field method relies on configuring a field that exists within the documents of each layer. Fields are configured by using a single element array.

Table 1. Example: Values for configuring by parameter or field
Parameter Parameter examples Field examples

spatial_path

"World Countries"

N/A

icon

"fas fa-arrow-alt-circle-down"

["properties.icontouse"]

color

"#7CBFFA", "blue"

["colortouse"]

size

"xs", "s", "m", "l", "xl",

["properties.size"]

popupFields

"is constant for all features"

["fields", "mustbein", "afeatures","propertiesobject"]

minZoom

0

N/A

maxZoom

18

N/A

When a new Enhanced Coordinate Map visualization is created, the Stored Layer Configuration will be populated with a default object: Default stored layers configuration

Feature-level configurations

If any of the icon, size, color, or popupField parameters are specified in a document’s properties object, this field will take precedence. This can be useful if you want to assign different icons within the same layer.

After changing options, click Apply changes to update your visualization, or Discard changes to keep your visualization in its current state.

Navigating the map

After your tilemap visualization is ready, you can explore the map in several ways using various tools:

Panning the map

  • Click and drag anywhere on the map to move the map center

  • Hold Shift to drag a bounding box across the map to zoom in on a desired extent

  • Viewing extent

    • Click Zoom In/Out (image) to change the zoom level manually.

    • Click Fit Data Bounds (image) to automatically crop the map boundaries to the geohash buckets that have at least one result.

  • Click Set View Location (image) to manually specify:

    • Whether latitude and longitude are in decimal degrees (dd) or degrees/minutes/seconds (dms) ①

    • The latitude ② and longitude ③ of the centroid of the canvas you would like to display

    • The desired level of zoom ④

    • Whether changes are applied ⑤ or cancelled ⑥

image

Selection tools - used to create geo filters

  • Click Draw a Polygon (image), then

    • Click on the map canvas and add vertices; if you add a vertex that you don’t want, click the Delete last point option on the menu that opens to the right when you clicked Draw a Polygon tool.

    • When complete, either click on the first vertex or double click and the polygon will autocomplete. Elasticsearch documents within the drawn polygon will be filtered.

  • Click Latitude/Longitude Filter (image), then drag a bounding box across the map, to create a filter for the box coordinates. Elasticsearch documents within the drawn polygon will be filtered.

  • Click Draw a Circle (image), then drag a circle and release to select documents. Elasticsearch documents within the drawn polygon will be filtered.

For all selection tools, a geo filter is created. This will appear above the map canvas:

+ image

Multiple geo filters

If exactly one geo filter (i.e. a pill similar to the above image) exists, and you create another geo filter for the same map visualization, you will be prompted by the modal below:

  • Overwrite existing filter - Replaces the exising geo filter with the new one you have created

  • Create new filter - Creates a new filter and will keep the existing one, use this option to create an AND

  • Combine with existing filters - Merges the new filter with the existing one, use this option to create an OR

Note - You can cancel filter creation from this modal by clicking the X in the top right

image

Marking tools

  • Click Draw a Marker (image), and select any point on the map to place a marker. You can add multiple markers.

  • After adding at least one marker, the Delete Marker(s) option becomes available

    • Point and click to delete individual markers

    • Remove all of them by clicking Clear All

Viewing detailed information

For information on displaying the raw data, see Visualization Spy.

Loading Stored Layers into Elasticsearch

Loading methods

There are two methods for loading the GeoJSON files into Elasticsearch. These are the Folder Structure and the Spatial Path methods. Both will accept files of type json or geojson. The methods differ in how their spatial_path is determined.

Folder structure

This method requires all GeoJSONs to be contained in a folder structure, that will determine scope/layer of each GeoJSON file.

Folder structure

Spatial path

This method requires all GeoJSON features to have a spatial_path property in their properties object. This will determine its scope/layer, example.

Spatial path

File validation

Each file needs to meet the following criteria:

  • Can not be empty

  • Must only contain one of the following type categories:

    • polygon - including Polygon or MultiPolygon

    • line - including LineString or MultiLineString

    • point - Point

  • If using the spatial path loading method, each GeoJSON feature must contain the spatial_path property

If these requirements are not met, the validation process will fail, only files to that point will be loaded.

Spatial path

Spatial path is the scope/layer of a feature. Documents that have the same spatial path, will be part of the same layer when used in Investigate.

Folder structure

When using the folder structure loading method the spatial path will be constructed based on the folder structure the GeoJSON file is in.

Here is an example of a spatial path for Continents/Europe/Poland/counties.geojsoncontinents/europe/poland

The file …​/Poland/counties.geojson contains 34 counties that make up Poland while …​/counties 2.json contains the other 8 Polish counties. The spatial path of both GeoJSONs when ingested is specified below. They will be loaded as one layer on Enhanced Coordinate Map Visualization, i.e. one 42 county layer: continents/europe/poland

Spatial Path

The spatial path loading method requires each feature to contain a spatial_path property in the properties object of each GeoJSON feature. This is checked for during initial validation.

{
  "type": "Feature",
  "properties": {
    "county": "Galway",
    "population": 86000,
    "spatial_path": "continents/europe/ireland"
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": []
  }
}

Usage

To load files into Elasticsearch go to siren-investigate folder and run ./bin/load_map_reference_indices script with appropriate arguments.

Make sure a user that has Elasticsearch write permissions is used for authorization.

Mappings

The load script will automatically differentiate between shape and point geoJSON files and use appropriate mapping file from /src/map_indices_loader to create an elasticsearch index, a custom mapping can be passed in with arguments.

Arguments

  • -p/--path/--inputdir specifies a path to the folder containing files

  • -y/--yml allows for using a custom investigate.yml. If omitted, the default configuration from /config/investigate.yml will be used

  • --username <username> --password <password> allows for specification of Elasticsearch authorization credentials. If <username> and <password> are left blank, environmental variables LOAD_LAYERS_ES_USERNAME, LOAD_LAYERS_ES_PASSWORD will be used. If not used at all, credentials specified in /config/investigate.yml will be used instead

  • --ms allows for use of a custom mappings JSON file for geo_shape objects (Polygons and Lines) instead of the default /src/map_indices_loader/mappings_geoshape.json

  • --mp allows for use of a custom mappings JSON file for geo_point objects (Points) instead of the default /src/map_indices_loader/mappings_geopoint.json

  • -s/--settings allows for use of a custom index settings JSON file instead of the default /src/map_indices_loader/index_settings.json

  • --dryrun will run the validation stage of the script, but will not connect to Elasticsearch

  • --overwrite if an index already exists it will be overwritten with a new one

  • --structure/--spatialpath determines the loading method

  • -n specifies the maximum number of documents per single request - higher number will result in heavier requests (default 500)

  • -r/--simrequests specifies the number of simultaneous requests made to Elasticsearch (default 40)

  • --debug outputs additional debug information, including Elasticsearch authorization credentials

Examples

./bin/load_map_reference_indices.sh -p "/home/siren/geoJsonFolder" --structure

./bin/load_map_reference_indices.sh -p /home/siren/geoJsonFolder -y /home/siren/config.yml --username admin --password password --structure

./bin/load_map_reference_indices.sh -p /home/siren/geoJsonFolder --username --password --spatialpath

The console output below is a successful file load (with --debug) to Elasticsearch Console output

Loading stored layers from Elasticsearch into the Enhanced Coordinate Map

In this section, you can learn how to load stored layers into the map.

You will need to have layers stored in elasticsearch in indices that have a .map__ prefix. See Loading Stored Layers into Elasticsearch for details on our recommended way to load these.

In top right click of an Enhanced Coordinate Map visualization, click on the Layer Control to toggle it open. When the ‘Add Layers’ button is clicked, a modal (below) will appear displaying Stored Layers (e.g. Irish Counties) and the group they are in (i.e. World Countries).

Add Layers Modal

It is possible to add a layer type corresponding to a group and we will explain with the aid of an example below, using the US states layer:

  • If the US states group checkbox is toggled, all layers and groups in that group will also be toggled

    • If the US States layer checkbox is toggled, only the layer will be affected

    • If the California nested group is toggled, only the checkboxes within that group will be toggled

  • If either a nested group or a layer box is unchecked, the group will become indeterminate indicating that some of the boxes in that group are unchecked

  • Finally, if no items in a group are checked, the group checkbox will be unchecked

To add the selected layers to the map but keep them hidden for now, click Add. To add the layers to the map and also make them visible, click Add and Enable.

You can configure the stored layers when your visualization is in edit mode. For more information, see when in Visualization edit mode.

Stored layers and the map

If a Polygon is clicked when loaded on the map, Geo Filter(s) will be created

This only applies to Polygons and NOT Points or Lines

Layer control

The Layers function is located in the top-right corner of any Enhanced Coordinate Map. It allows you to select which layers that you want to display on the map. The following image shows multiple layers that can be selected and displayed as needed. You can load stored layers into the map from Elasticsearch. For more information, see Loading stored layers from Elasticsearch.

The Layers function

Layer Ordering

Layers are drawn on the map in the same order they are in the Layer Control. Layers can be ordered by clicking the drag handle to the left of any checkbox and dragging them to the desired position.

Layers will be automatically positioned at the top or bottom of their type in the event that they are dropped out of order. The precedence is:
  • Point Layers

  • Shape Layers (polygons and lines)

  • Heatmap aggregation layer: If this type of aggregation is selected, this will appear above tile layers and below all other shape layers.

  • Tile Layers

Layer Visibility

Layers can be toggled on and off by clicking the checkboxes

Features Omitted Due to Request Limits

If there are more features in the map canvas than are allowed by the Elasticsearch query size response limit, a warning icon appears beside the layer.

Detailed example of a stored layer configuration

The icon, color, size, or popupFields can be specified in the properties object of an Elasticsearch document. For example, by using the following code, the church appears as a red heart on the map:

 {
   "spatial_path": "pois/states/churches",
   "geometry": {
     "type": "point",
     "coordinates": [ [ 100.0, 0.0 ] ]
   },
   "properties": {
     "icon": "heart",
     "color": "red",
     "popupfields": ['Label','denomination']
   },
   "colorfield": "green"
 }
Example 1: A document with some configuration fields
 [
   {
     "spatial_path": "pois/states/churches",
     "icon": "cross",
     "color": ["colorfield"],
     "popupfields" : ['Label','denomination']
   },
   {
     "spatial_path": "pois/states",
     "icon": "map",
     "popupfields" : ['Label','statecode’],
     "maxZoom": 15
   },
   {
     "color" : "default_color",
     "icon": "default_icon",
     "popupfield" : [],
     "minZoom": 0,
     "maxZoom": 18
   }
 ]
Example 2: The stored layer configuration

The values for the icon, size, popupFields, and color properties on the map are taken in the following order: . From the feature itself. . Then, from the the most specific spatial_path parameter in the configuration. . Then, from the next most relevant spatial_path parameter in the configuration. . Finally, the root of the configuration is reached and a default value is assigned. The values for the maxZoom and minZoom properties on the map are taken in the following order: . From the most specific spatial_path parameter in the configuration. . Then, from the next spatial_path parameter in the configuration. . Finally, the root of the configuration is reached and a default value is assigned. The values for icon and color for the layer in the [Layer Control] are taken in the same order as the maxZoom and minZoom properties.

Configurations for example 1

For the example document above, the properties on the map will be:
  • color: red - taken from the feature document

  • icon: heart - taken from the feature document

  • size: m - this is the underlying default

  • popupField: ["label", “denomination”] - taken from the feature document

  • maxZoom: 15 - taken from the configuration with the “pois/states” spatial_path

  • minZoom: 0 - taken from the default configuration (the configuration without spatial_path attribute)

The properties on the [Layer Control] for example 1 will be:
  • color: green - field type, taken from the configuration and retrieved from a document with the “pois/states/churches” spatial_path

  • Icon: cross - taken from the configuration with the “Pois/states/churches” spatial_path If there are more features present within the current map canvas extent than were retrieved with the set Elasticsearch query size response limit, a warning icon will appear beside the layer. The warning icon has a tooltip indicating this and the set current limit

Configuring layer security

Index security

By default, only the sirenadmin user has the permissions to view the map layer indices. To make layers available for other users to configure, you must assign read permissions to their roles. To configure the permissions, open Access control, click the Roles tab, and add the prefix ?map__* to the allowed indices in index_permissions.

image

This prefix will apply permissions to all map indices. If you want to be more specific, you can add each index to the role individually.

Document-level security (DLS)

You can configure document-level security on the map indices, which allows only the documents that match the DLS query to be returned.

To maintain system performance, run DLS map queries ONLY on the map indices. For more information, see the Search Guard performance considerations.

Configuring security by spatial path

The following DLS query retrieves only the documents that contain "World Lakes" in their spatial_path parameter:

index_permissions:
  - index_patterns:
      - '?siren*'
      - article
      - company
      - investment
      - investor
    fls: []
    masked_fields: []
    allowed_actions:
      - READ
      - VIEW_INDEX_METADATA
  - index_patterns:
      - '?map__*'
    dls: '{ "match": { "spatial_path":"World Lakes" } }'
    fls: []
    masked_fields: []
    allowed_actions:
      - READ
      - VIEW_INDEX_METADATA
image

Configuring security by geo-shape

The following DLS query retrieves only the documents that are within the specified coordinates:

- index_patterns:
    - '?map__*'
  dls: >-
    { "geo_shape": { "geometry": { "shape": { "type": "Polygon",
    "coordinates": [ [ [ -12.85400390625, 50.680797145321655 ], [
    -4.306640625, 50.680797145321655 ], [ -4.306640625, 56.42605447604972 ], [
    -12.85400390625, 56.42605447604972 ], [ -12.85400390625,
    50.680797145321655 ] ] ] }, "relation": "within" } } }
  fls: []
  masked_fields: []
  allowed_actions:
    - READ
    - VIEW_INDEX_METADATA
image
image

Configuring security by properties fields

The following DLS query retrieves only the documents that match a specific property:

- index_patterns:
    - '?map__*'
  dls: '{ "term": { "properties.CONTINENT.keyword": "North America" } }'
  fls: []
  masked_fields: []
  allowed_actions:
    - READ
    - VIEW_INDEX_METADATA
image