This article covers:

1. How to set up a connection to a ElasticSearch cluster
2. How to add datasets
3. How to do connection overrides on a ElasticSearch connection
4. The supported ElasticSearch data types and the respective Luzmo data type they are mapped to

1. How to setup a ElasticSearch connection

Navigate to the Datasets tab and click 'New dataset'. Select the 'ElasticSearch' connector. You'll be asked to provide a host, key and token:

• Host: this is the host where your ElasticSearch database is exposed. Note that only https is allowed here in order to securely transfer data over the wire. The structure of the host url expects: https://url-to-elasticsearch-cluster:port
• Key: the username that will be used to connect to your ElasticSearch cluster.
• Token: the password to connect to your ElasticSearch cluster

After that you should see a list of indeces that are available in your cluster.

Please refer to the examples in our developer documentation to find out how to create a connection to Elasticsearch via our API.

Notes:

1. To ensure that e.g. only the Luzmo application can access your ElasticSearch instance, it is highly recommended to whitelist Luzmo's range of static IP addresses. You should whitelist Luzmo's range of IP addresses as described here.
2. Since ElasticSearch evolves quickly and has frequent small breaking syntax changes, we currently only support ES clusters from version 6.1 (that introduced pagination queries).
3. Note that text fields you want to use for filtering, grouping or aggregations must either be of the type keyword or of the type text but have a subfield of the type keyword. More information on this can be found in the ElasticSearch docs.

2. How to add datasets

Once you have connected your ElasticSearch you can add datasets (indexes) as explained here. You can select one or multiple datasets (indeces) as available in your ElasticSearch and link them in Luzmo to ensure they can be used together in a dashboard. Also make sure to check out this article on Preparing your data for analytics.

Notes:

1. Note that text fields you want to use for filtering, grouping or aggregations must either be of the type keyword or of the type text but have a subfield of the type keyword. More information on this can be found in the ElasticSearch docs.
2. You can only select indexes to add as a dataset. If you want to add a dataset that uses a "*" wildcard naming for the source index, you can create an alias that references an index with a wildcard. Make sure the (readonly) user has sufficient permissions to list/query aliases too in that case. Example:

POST _aliases
{
    "actions": [
        {
            "add": {
                "index": "logs-*",
                "alias": "logs"
            }
        }
    ]
}

To find out how to add datasets using our API, please refer to this example in our developer documentation.

3. ElasticSearch Connection Overrides

When generating an Authorization token to grant a user acces to your embedded dashboards it is possible to override the data source properties in the authorization request to dynamically use different properties. Find out more about connection overrides.

The fields available for overriding a ElasticSearch connection are as follows:

• Connection ID: The ID of the Connection to be overridden. Retrieve the ID to specify as detailed here.
• host:The new ElasticSearch host to connect to.
• key: The new username that will be used to connect to your ElasticSearch cluster.
• token: The new password to connect to your ElasticSearch cluster.
• datasets: List of dataset-level overrides. Useful if you want to override only a single dataset in your dashboard or if you have a separate table per client.
  • table: The new index to query.

Our developer documentation has more info about connection overrides and an example of a ElasticSearch connection override.

Example code demonstrating how to override a ElasticSearch connection:

 import Luzmo from '@luzmo/nodejs-sdk';
const client = new Luzmo({
api_key: '<your Luzmo API key>',
api_token: '<your Luzmo API token>',
host: 'https://api.luzmo.com:443'
});


const response = await client.create('authorization',
{
  type: "embed",
  username: "< A unique and immutable identifier for your user >",
  name: "< user name >",
  email: "< user email >",
  suborganization: "< a suborganization name >",
  access: {
    collections: [
      
      {
        id: "<collection_id>",
        inheritRights: "use"
      }
    ]
  },
  account_overrides: {
    <your connection_id>: {
      host: "<The new ElasticSearch host URL to connect to>",
      key: "<username>",
      token: "<password>"
    }
  }
}
);

4. Supported Data Types