Query API Tutorials

Getting started

The “omniscope.js” library includes a helper for using the Query API. This helper handles URL endpoints and network communication, and lets you focus on creating query input objects and interpreting query output objects.

omniscope.query.builder(omniscope.view.endpoint())
    .table({groupings: [], measures: [{function: "RECORD_COUNT"}]})
        .on("error", function(event) {
            if (event.data.error) console.log(event.data.error);
            omniscope.view.error(event.data.message, event.data.internal);
        })
        .on("load", function(event) {
            console.log(event.data.records[0][0]);
        })
        .execute();

First, create a query builder for the file's data:

 omniscope.query.builder(omniscope.view.endpoint())

You can also omniscope.view.queryBuilder() which pre-configures the builder with the view’s filter state.

Then, choose a query endpoint. The most common Query endpoint is table, which requests tabular data a little like SQL, with groupings and measures (aggregations).

Then pass a query input object. For Table queries, the simple approach is to pass a SimpleQuery:

{
    groupings: [], 
    measures: [
        { function: "RECORD_COUNT" }
    ]
}

In this example we have no grouping levels so the data will be rolled up to a single record. We have one measure, the number of records in that single record. This is expected to produce a single-cell table (one row, one column).

Now add callbacks to handle the result:

.on("error", function(err) {
    if (event.data.error) console.log(event.data.error);
    omniscope.view.error(event.data.message, event.data.internal);
})
.on("load", function(event) {
    // do something with event.data
})

Finally execute the query:

.execute();

In this example, in the "load" handler, event data will be like this:

{
  "schema": {
    "fields": [
      {
        "name": "RECORD_COUNT",
        "type": "NUMBER"
      }
    ]
  },
  "records": [
    [ 12345 ]
  ]
}

So to extract the record count in this case, use event.data.records[0][0].

Schema by example

This is a semi-auto-generated SimpleQuery for querying aggregated data, illustrating the structure of the object:

{
  "groupings": [
    {
      "inputField": "example",
      "type": "UNIQUE_VALUES",
      "name": "example"
    }
  ],
  "measures": [
    {
      "name": "example",
      "inputField": "example",
      "function": "RECORD_COUNT"
    }
  ],
  "filter": {
    "type": "AND",
    "filters": [
      {
        "type": "FIELD_VALUE",
        "inputField": "example",
        "operator": "=",
        "value": "example"
      }
    ]
  },
  "sorts": [
    {
      "inputField": "example",
      "direction": "ASCENDING"
    }
  ],
  "range": {
    "start": 123,
    "length": 123
  }
}

Query API Tutorials

Getting started

Schema by example

Further reading