Building content search and visualization applications using Elasticsearch with Exaptive will feel pretty familiar if you're already an Elasticsearch user. Exaptive provides some added convenience. Whether you have an existing Elasticsearch instance you want to integrate with or use Exaptive's shared instance to get up and running quickly, you can store and retrieve content quickly without the need to write code. Exaptive also makes working with the data returned easier. 

Connecting to Elasticsearch

You will need a few key pieces of information to connect to an Elasticsearch instance.

  • Server name/IP address: the location of the Elasticsearch instance
  • Port: the port number to connect on
  • Index: the named index or indices you will be accessing; you usually have one index per application/content store
  • Type: the type(s) of content you will be accessing, which is set up during content indexing; this is typically used to distinguish content with different schema/structure

Important: the Elasticsearch server and port must be accessible from your Exaptive instance (e.g. This means that your network's firewall must allow access to your Elasticsearch server on the specified port, either globally or restricted to specific IP addresses or ranges. If the latter is used, your network administrator must allow traffic to and from Exaptive. The specific IP address to allow can be found by "pinging" the URL you use to log into the Exaptive Studio. An example is shown below. In this instance, you would provide the IP address to your network administrator.



Your Studio comes with a handful of Elasticsearch components for indexing and querying documents. They use the Python Elasticsearch API to connect to and feed or retrieve content.

Additional components exposing Elasticsearch functionality will be added based on demand. If you have a specific need, please contact Exaptive. You can always write your own components as well in Python, R or Javascript.

To search for components, type #elasticsearch in the explore/search page, as shown below:


The Exaptive Elasticsearch components specify a default server name and port that you are welcome to use for non-sensitive, non-production use. There are no guarantees the content will be secure or stored indefinitely. We recommend setting up a dedicated Elasticsearch instance for your production needs. Contact Exaptive if you would like us to manage your infrastructure.

Querying Elasticsearch

Elasticsearch components support both basic queries and Elasticsearch's Domain Specific Language (DSL). The query input port is dynamic, meaning you can specify different data types. If you pass a string, for example from a text box, it assumes a basic search string. If you send it an entity (e.g. a JSON/Javascript dictionary object), it assumes the query is DSL. For information on DSL syntax, see the Elasticsearch documentation.

Exaptive's data model complements the document-oriented structure of Elasticsearch. Exaptive sends data around as lists of entities. In Elasticsearch's case, each entity corresponds to a document, and the entity's attributes correspond to various fields in the index. This applies both to adding content (indexing) and retrieving content (searching/querying).

The main difference between raw Elasticsearch results and what Exaptive returns is that Exaptive provides some additional convenience methods to simplify subsequent use of the results. For instance, the Elasticsearch Search Documents component returns a list of results as the root node (without needing to inspect the JSON object) and flattens each result so that fields normally in _source are available at the root level. Metadata, like the total number of results, are available as separate ports.

Performance Considerations

When you search Elasticsearch with Exaptive's standard Python components, the data resides on the server so long as it goes to other Python or R components. The instant you feed the data to a Javascript component, including any UI component like a Result List, however, all mapped content will be sent to the web browser. This is not particular to Exaptive and has bitten many a person new to Elasticsearch's APIs.

You should exercise caution in the following ways.

  • Limit the total number of results returned at any one time using the start and size parameters.
  • Return the least number of fields needed for your visualization needs.
  • Do not return full text of documents as a regular field; use the highlight field to dynamically create snippets/teasers based on search terms.