[RFC] - Upload Custom GeoJSON as vector map

[VijayanB]

The purpose of this RFC (request for comments) is to gather community feedback on a new proposal to allow OpenSearch users to upload custom GeoJSON file as vector map in Region map for visualization.

Problem

OpenSearch Dashboards provides region maps of many default vector maps like World Countries, Argentina Provinces, Australia States, USA States, etc... This is not an exhaustive list of vector map (for example, we do not have US Counties, US Zip Codes), and this will always be a growing list. Users who need specific vector map (GeoJSONs format) that we do not provide today out of the box, won’t be able to use in Region map for visualization.

Solution

We propose an integrated solution that allows users to import their own custom GeoJSON as new vector map, and, later use it for visualizations inside Region maps.

Design

In order to use imported GeoJSON file across sessions in Dashboard, we have to persist this file as an index and later, make this index available for selection as vector map in Region map.

Upload Custom GeoJSON API

New API will be created to upload GeoJSON objects into a target index.

POST /_plugins/geospatial/_import
{

   "index": "my-geo-index",
   "field": "destination",
   "type" : "geo_shape",
   "data": [
        {
          "type": "Feature",
          "geometry": {
            "type": "Point",
            "coordinates": [125.6, 10.1]
          },
          "properties": {
            "name": "Dinagat Islands"
          }
        }
   ]
}

Prerequisite

1. Before using this API, you should be familiar with the GeoJSON Specification.
2. If Security plugin is installed, user must pass valid credentials along with this API.

Request body

• index (Required, String): New target index to upload data.
• field (Optional, String): The field to which assign the geo field data. If field is omitted, “location” will be used as default field name.
• type (Required,String): This field describes the field type of Geospatial data ex: geo_point or geo_shape.
• data (Required, GeoJSON object): This field contains an array of GeoJSON object. This could be either a Feature Collection or list of Feature object.

Response body

The Response body depends on the success or failure of the upload action.

Success response

The upload action is succeeded and acknowledged by the server

{
    "acknowledged":true
}

Failure response

Failure action will return list of error message corresponding to GeoJSON object it failed to upload.

Description

Internally OpenSearch Geospatial plugin will perform following operations

1. Create new index with mapping like below and raise an exception if index already exists.

{
  "mappings": {
    "properties": {
      "location": {          -> field value
        "type": "geo_shape"  -> type value either geo_shape or geo_point
      }
    }
  }
}

1. Create new pipeline with geojson-feature processor. This processor will converts GeoJSON Feature into a document by removing fields that are GeoJSON specification like “type” and move the “geometry” value from Feature into geospatial field .
2. For every GeoJSON Feature, create an IndexRequest with index name from Step 1, pipeline name from Step 2 and GeoJSON as source.
3. Create Bulk Request and include all Index Request to improve performance.

Region Map

Region Map will have new tab called “Import Vector Map”, This will let users to upload valid GeoJSON file and specify Vector map name which will be used as an identifier to use this Layer Options in future.

The Import file, will build upload custom GeoJSON API request as mentioned above and delegate index creation to geospatial plugin.

[elfisher]

@VijayanB can we update this issue with the OpenSearch version it is targeting and the label "Roadmap". After that I can add it to the overall project roadmap board accordingly.

[bbarani]

@VijayanB Can you please tag this RFC to the appropriate version since we have already released 2.1.0 and 2.2.0?

[VijayanB]

@bbarani This issue was tagged appropriately, but it was not closed.