Elasticsearch Connector

Search UI provides a way to connect to Elasticsearch directly without needing Enterprise Search. This is useful for when you dont need the features of Enterprise Search, such as relevance tuning.

The connector uses the same Search UI configuration that other connectors use.

You must specify either the cloud id or on-premise host url for the Elasticsearch connector.

import ElasticsearchAPIConnector from "@elastic/search-ui-elasticsearch-connector";

const connector = new ElasticsearchAPIConnector(
  {
    // Either specify the cloud id or host to connect to elasticsearch
    cloud: {
      id: "<elastic-cloud-id>"
    },
    host: "http://localhost:9200",
    index: "<index-name>",
    apiKey: "<api-key>",
    // This key will be visible to everyone so ensure its setup with restricted privileges.
    // See Authentication section for more details.
    connectionOptions: {
      // Optional connection options.
      headers: {
        "x-custom-header": "value"
      }
    }
  },
  (requestBody, requestState, queryConfig) => {
    // Optional: modify the query before sending to Elasticsearch
    return {
      ...requestBody,
      custom_field: "value"
    };
  }
);

1. cloud id found under your cloud deployment overview page
2. host url for the Elasticsearch instance
3. index name where the search documents are contained
4. Optional. apiKey used to authorize a connection to Elasticsearch instance.
5. Optional. Specify custom headers to send with the request

Constructor Parameters

Config

The ApiProxyConnector is used when you want to proxy search requests through your own backend rather than exposing your Elasticsearch cluster directly to the browser.

It sends onSearch and onAutocomplete requests to your API, which is expected to forward them to Elasticsearch using ElasticsearchAPIConnector.

import { ApiProxyConnector } from "@elastic/search-ui-elasticsearch-connector";

const connector = new ApiProxyConnector({
  basePath: "/api",
  fetchOptions: {
    headers: {
      Authorization: "Bearer your-auth-token"
    }
  }
});

1. Base path for your proxy server
2. Optional fetch params

Constructor Parameters

Expected Server API

The server is expected to expose two endpoints:

• POST /search — handles search requests
• POST /autocomplete — handles autocomplete requests

Both endpoints should accept a body with the following format:

{
  "state": {
    /* RequestState */
  },
  "queryConfig": {
    /* QueryConfig */
  }
}

And respond with the standard Search UI response types:

• ResponseState for /search
• AutocompleteResponseState for /autocomplete

For a full working example with server setup, see the Using in Production guide or jump to the CodeSandbox.

Elasticsearch connector differs in the way filters can be applied to facets. Currently its not possible to apply an explicit range filter to range facets. Elasticsearch connector uses the name thats been given to the option to apply the filter. It uses this name to match the option and creates a the range filter query for the option.

{
  visitors: {
    type: "range",
    ranges: [
      { from: 0, to: 10000, name: "0 - 10000" },
      { from: 10001, to: 100000, name: "10001 - 100000" },
      { from: 100001, to: 500000, name: "100001 - 500000" },
      { from: 500001, to: 1000000, name: "500001 - 1000000" },
      { from: 1000001, to: 5000000, name: "1000001 - 5000000" },
      { from: 5000001, to: 10000000, name: "5000001 - 10000000" },
      { from: 10000001, name: "10000001+" }
    ]
  }
}

setFilter("visitors", {
  name: "10001 - 100000",
  from: 10001,
  to: 100000
});

1. name of the option
2. both from and to will be ignored

If the field isn’t a facet, you will be able to apply filters to the search using value, numeric range and date range, depending on the field type.

setFilter("precio", {
  name: "precio",
  from: rangePrices[0],
  to: rangePrices[1]
});

Currently the None filter type is not supported. If this is a feature thats needed, please mention it in this issue.

Search UI supports autocomplete functionality to suggest search terms that provide results. The autocomplete functionality is built on top of the Elasticsearch suggest and bool prefix query API.

To take advantage of the feature, first update the autocomplete query configuration.

Below is an example of what the autocompleteQuery may look like.

autocompleteQuery: {
  // performs a prefix search on the query
  results: {
    resultsPerPage: 5,
    search_fields: {
      // the fields to prefix search on
      title_suggest: {}
    },
    result_fields: {
      // Add snippet highlighting within autocomplete suggestions
      title: { snippet: { size: 100, fallback: true }},
      nps_link: { raw: {} }
    }
  },
  // performs a query to suggest for values that partially match the incomplete query
  suggestions: {
    types: {
      // Limit query to only suggest based on "title" field
      documents: {  fields: ["title_completion"] }
    },
    // Limit the number of suggestions returned from the server
    size: 4
  }
}

1. number of results to display. Default is 5.

Above we are configuring both the results and suggestions sections of the autocomplete query.

results will need a search field to perform a prefix search on the query. We advise using a search_as_you_type field to be used. suggestions require a completion type field to perform a query to suggest for values that partially match the incomplete query.

Below is an example of the mappings for the above example. title_suggest is a search_as_you_type field and title_completion is a completion type field.

{
  "mappings": {
    "properties": {
      "title_suggest": {
        "type": "search_as_you_type"
      },
      "title_completion": {
        "type": "completion"
      }
    }
  }
}

With a combination of this configuration + the Searchbox component with autocomplete configuration, your users will be able to see suggestions as they type within the search box.