Querying

This section covers concepts needed to query the data available for your Custom View.

Auto-querying

Auto-querying is a way of making the framework automatically execute the queries for your view based on the measures and groupings you have defined in your manifest.json. The results of these queries are then made available to you in the context as part of “result” property. You can retrieve these by calling omniscope.view.context().result.

By default when you create a new custom view the manifest is already updated to have auto-querying turned on.

Auto-Query Turned on

Manifest setting: auto-query: true

The options for your view (declared in the manifest, modelled in the context, configured by auto menus) are used to automatically infer aggregate queries with groupings and measures. The query should aim to result typically in a row per visual element.

For example, if you declare the view supports “split”, and the user picks a “split” field, this will cause that field to be included as a grouping within the query, and as a column in the table.

For simple views the only development needed is to map the result table (a 2d array) to the creation of visual elements such as pie or bar segments, or to the format needed for an off-the-shelf chart.

We have not finalised the manner or extent that auto-querying will allow query customisation without having to resort to turning it off.

Auto-Query Turned off

Manifest setting: auto-query: false

You should disable auto-querying if your view needs to execute its own queries directly against the underlying data engine (using the Query APIs, below), perhaps in a different sequence or chain, or perhaps if the structure of the queries needs more sophisticated customisation.

For example you may need to execute queries iteratively as a user explores a tree structure. Or you may need multiple data queries at different levels of aggregation.

Auto-Pane Turned on

Manifest setting: auto-pane: true

For simple views no development is needed to enable this.

Auto-Pane Turned off

Manifest setting: auto-pane: false

You should disable auto-paning if your view does its own paning or paning is undesirable for performance, aesthetics or user experience reasons. The IFRAME for your view will fill the view area.

For example you may want total freedom to be able to develop 3D paning in a WebGL canvas.

We may in future expose the auto paning logic to allow it to be customised or used within a single IFRAME.

You may also want to delete the paneX and paneY options in the manifest appropriately.

Queries

We provide two methods two query data; Schema, which retrieves field names and types, and Table which is used to select a subset of the data.

The Table query API allows you to execute SQL-like queries on the underlying data engine, providing filters, performing grouping (aggregation) and sorts, rather like a SELECT statement but without the cross-vendor

See the Swagger API docs where you can test queries out.

The input query object to the Table API accepts simple queries as follows, with more complex forms in the works:

{
    groupings: [ { field: "Customer name" }, { field: "Age range" }, ... ],
    measures: [ { field: "Shoe size", function: "SUM" }, ... ]
}

For more detail see the “SimpleQuery” in the JSON schema in Docson and example JSON

The output can assumed to be a table of data in JSON / a 2d JS array, such as this 3-column example:

Next: Custom View tutorials