The Query Generator API

Siren Investigate exposes an API that retrieves a list of saved dashboards and entity tables.

The API returns a list of objects and includes in each of them the list of indexes and the query that can be understood by Elasticsearch.

Siren Investigate also provides SQL drivers in the form of JDBC and ODBC, which, in conjunction with the APIs, allow you to extract data using the familiar SQL 92 syntax.

You can try out this functionality by downloading the Siren Platform Preloaded Demo.

Background

The following section assumes that you have knowledge of the basic Elasticsearch concepts, such as index, index pattern, and query. For more information, see the Elasticsearch glossary.

The Siren Investigate configuration is stored in an index, which, by default, is called .siren.

  • A saved object is an entity table or search, a visualization, or a dashboard that is stored in the .siren index.

  • An entity table is an Elasticsearch query that returns a list of records.

  • A search is an entity table that has been stored as a saved object in the .siren index.

  • A visualization is a visual element that displays the data that is returned by an entity table or search.

  • A dashboard contains one or more visualizations and filters and, when it is configured to be connected to the data model, the dashboard is linked to an entity table or search.

A dashboard has two states:

  • The saved state - This is how the dashboard appears at the beginning of any analysis. This state is stored in the .siren index.

  • The current state - This is how the dashboard appears during the investigation. For example, the transient state when a filter is momentarily applied.

Saved objects do not include current states.

Requirements

To be able to query the Siren Investigate API, an external tool must have TCP/IP access to Siren Investigate and, in order to directly query Elasticsearch, the external tool must have direct TCP/IP access to Elasticsearch.

Example of usage

The Query Generator API is useful when an analyst has created an investigation that contains multiple entity tables and multiple saved dashboards.

The analyst has refined the data in a dashboard to the point that they have selected the precise records that are useful.

The analyst saves that dashboard and, in doing so, updates the saved object that is associated with the dashboard.

An external tool can now leverage the API to get the list of saved dashboards, extract the index and query for the relevant one and build the request to be sent to Elasticsearch.

After the external tool has retrieved the index and query, it can change objects to further refine or reuse them. Records that are returned by Elasticsearch can then be used as required.

In this section

Next steps