npm package: @ndlib/aws-opensearch
Description: Library for interacting with AWS OpenSearch
Author: Hesburgh Libraries, University of Notre Dame
Latest version: 1.0.8

# AWS OpenSearch

This is a plugin designed to facilitate any interaction with AWS OpenSearch. In order to use this plugin, several assumptions are made. Those are listed below.

* First, OpenSearch requires either IAM signed operations, which requires a lot of setup and the use of authentication keys, or it requires the use of Basic HTTP Authentication. We use the latter.
* Given the previous assumption, you will need to provide in the context for your consuming application the username and password required to interact with OpenSearch
* We also assume that all request and response bodies transferred using REST interactions are serialized using JSON - if you attempt interaction with OpenSearch using another data format it will not work
* The JSON body passed to OpenSearch should be just that - JSON, not a string. The response body will be JSON. JSON in, and JSON out.
* The plugin provides basic error checking - whether the connection was successful, whether a response was received from the OpenSearch API and what that response was. However, it makes no assumptions about what "success" looks like when indexing a document. The consuming application is responsible for determining whether the operation was truly a success.
* All interactions with OpenSearch happen over HTTPS

## Configuration Parameters Needed

* You will need the host name of your OpenSearch domain
* You will need the Basic Auth credentials
* You will need the name of the index you will use within your search domain

## Example of use

How to use (in `gatsby-config.js`):

```
import { opensearch_mappings } from './content/opensearch/mappings'
import { opensearch_query } from './content/opensearch/query'
import { opensearch_selector } from './content/opensearch/selector'

...

module.exports = {
  plugins: [
    ...
    {
      resolve: '@ndlib/aws-opensearch',
      options: {
        opensearch_hostname: <hostname>,
        opensearch_password: <password>,
        opensearch_port: <port-number>,
        opensearch_protocol: <http | https>
        index_name: <index_name>,
        content_grouping: 'bulk' | 'individual',
        query: opensearch_query,
        unique_id: <unique_id_field>,
        selector: opensearch_selector,
        mappings: opensearch_mappings
      }
    },
    ...
  ]
}
```

| Parameter | Description | Required |
| ------------- |:-------------| ----- |
| opensearch_hostname | The OpenSearch host name associated with the endpoint for the search domain being used. | yes |
| opensearch_password | The password required that allows write operations against the domain | yes |
| opensearch_port | The port number used by the OpenSearch api | yes |
| opensearch_protocol | There are only two options: http or https | yes |
| index_name | The name of the OpenSearch index. | yes |
| content_grouping | Two options: either 'bulk' or 'individual' referring to the number of documents being indexed. | yes |
| query | The GraphQL query used to build the data set to be indexed | yes |
| unique_id | The GraphQL query used to build the data set to be indexed | yes |
| selector | A function to remap the query data to the top level. | yes |
| mappings | A function to create custom mappings for OpenSearch. | yes |