Query API

This page describes the omniscope.query API.

Query Methods	Query Request Methods	Events
table(query)	on(String|String[], function)	load
batch(query)	execute()	error
schema()	cancel()
schema(query)

Query Methods

All of the below methods return a ‘request’ object. They can all be called from omniscope.query.builder(endpoint).

• table(query)

Given a valid query JSON object, table(query) returns the chosen data set in a JSON object. This is akin to making a SQL select query, and having the valid table output returned.

• formula(query)

Given a valid FormulaQueryInput JSON object, formula(query) returns the result of the formula evaluation in a FormulaQueryOutput JSON object.

• batch(query)

Performs multiple queries with a single call, the query argument requires a JSON object stating each query.

• schema()

This provides a JSON object detailing all of the available fields and their types. This can be used to find which fields are suitable for your view. For instance if you have a line view, you may want to avoid any text fields being used as a measure. You can check what fields are TEXT using the schema JSON output.

• schema(query)

Has the same functionality as schema(), only returning the schema JSON for the which matches the query given.

Query Request Methods

All of the below methods are used on a ‘request’ object and perform some action upon it. Each of the functions will also return a request object in a different state.

For example omniscope.query.builder(endpoint).schema().execute() will take the query request and execute it, returning the completed request.

• on(String|String[], function)

On the given string event(s) the function will be exectued, where the functions first input will be a request.

• execute()

Executes the request object. This should be done at the end of all queries.

• cancel()

Cancels the request. This should be called upon an error.

Events

When given a event as a string object, the function given will be executed. For example:

• load

  This event is fired when the query is successful. The “data” property of the event will be the result object for the query API method being called - typically a QueryApi.SchemaFieldsQueryOutput, QueryApi.TableQueryOutput or QueryApi.GridQueryOutput object. See the JSON schema.

• error

  This event is fired in 3 cases:

  1. A network error occurs and no response is received. For example, the network connection is down.
  2. A non-200 HTTP response code is received from the server. For example, a 5xx error if the query endpoint is currently failing.
  3. An invalid JSON response was received from the server. For example, an error document is returned by the server or an interim proxy server.

  The “data” property of the event will be:

  {
      message: "Error making request to the query api",
      internal: "...",
      error: Error,
      responseCode: 503,
      responseText: "..."
  }
  

  Message is always populated; internal is the internal error data received from the server. Error is populated for case 3. Response code is populated for cases 2 and 3.