PreEmptive Analytics Workbench User Guide

Query API Overview

Recall from the architecture diagram that there is a Query Web Service that provides an API for retrieving aggregated data from MongoDB. That web service is primarily used by the Portal, but it can also be accessed by other client applications that wish to access the data directly.

The Metadata Query

The actual data queries that the Workbench exposes are entirely customizable. In fact, the default queries can be entirely removed and replaced with different queries. Because of this, the Query API provides a permanent "metadata query" that catalogs all the available queries and their details, including their unique names, available fields, and available filters.

The typical access pattern for the Query API is to first request the metadata query, to discover all the available queries, and then to request individual query results. It is possible, however, to directly access an individual query, so long as the client has specific knowledge of which queries are available.

The metadata query can be accessed at 127.0.0.1:88/Interaction/query_metadata?format=json. (You may need to change the host and port.) You can try that URL in your browser, to see the results - a simple HTTP GET is all that's required.

JSON

Note the query parameter in the URL above: ?format=json. That parameter asks the metadata query to deliver the results in JSON format, which is an easy-to-parse data-exchange format often used by JavaScript applications. All interactions with the Query API use JSON, both for request bodies and for responses. While it is possible to request other formats from the metadata API, those formats are not tested and are not guaranteed to work.

If you don't already have tools to help you work with HTTP / JSON data, we can recommend a few:

  • Your browser console (i.e. press the F12 key) will parse JSON in requests and responses and show you the data in tree form.
  • Fiddler can automatically intercept requests and responses and show a parsed JSON tree.
  • Most browsers have plugins that will automatically parse and render a JSON response, within the page.
  • Various text editors have plugins (or built-in features) that can automatically format JSON for easy readability.

Data Queries

Like the Metadata Query, the regular Data Queries are accessed via a simple URL - 127.0.0.1:88/Interaction/query. (You may need to change the host and port.) Note that these queries won't work from a browser - they require an HTTP POST with an appropriate (JSON-encoded) body.

Note that there is no need for a ?format=json argument here, because the regular queries are unable to provide responses in any other format.

Understanding the Data

Before you begin using the Query API directly, we strongly suggest that you read the section on Making Meaningful Queries for the Portal so that you understand how the default indexers and queries provide data, and how to construct a user of the API that will give you the data you expect.

Managing Timeouts

When querying the API directly you may run queries that take longer to run (or to transfer the data) than the default IIS settings allow for. (The default timeout is 110 seconds.) If so, you will typically see a 500 HTTP response code, and an error in the server Event Log indicating a timeout. You might also see client-side timeouts, depending on your client-side implementation.

These timeouts can be increased, as needed.

On the server, edit <Installation Folder>\IIS\Interaction\web.config and update <system.web> like so:

<system.web>
    <httpRuntime executionTimeout="300" />
</system.web>

Then restart the PreEmptive Analytics Workbench Portal website, in IIS.

You may also need to update your client application to have a larger timeout. If your client is written in C# and uses HttpClient, you can set the Timeout property, e.g.

new HttpClient() { Timeout = TimeSpan.FromSeconds(300) };


Workbench Version 1.2.0. Copyright © 2016 PreEmptive Solutions, LLC