PreEmptive Analytics Workbench User Guide

Metadata Query Spec

The Metadata Query provides information about the other queries available in the Workbench. Specifically, it provides:

  • The domain and name (i.e. the ID) of each available query
  • The list of fields in each query, with their details (ID, type, friendly name)
  • The available filters (e.g. date ranges) for each field, with their details (type, allowed values)

Accessing the Metadata Query

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.

Query Arguments

You must pass the query parameter ?format=json when calling the Metadata Query. Other formats have not been tested and are not guaranteed to work.

No other options or arguments are supported.

The Metadata Query Response

Top-level object

The response from the Metadata Query will be a JSON object with the following structure:

{
    "query_metadata": <array of query metadata objects>
}

Query metadata objects

Each query metadata object will have the following structure:

{
    "domain": <string>,
    "name": <string>,
    "fields": <array of field metadata objects>
}

The query metadata object also has a property named id that should be ignored. It may be removed in a future version of the Workbench.

Field metadata objects

Each field metadata object will have the following structure:

{
    "field": <string>,                                  // the unique ID for the field
    "as": <string>,                                     // a default human-friendly name 
    "type": <string>                                    // see below for details
    "filters": <array of filter metadata objects>       // potentially empty or missing
}

The field metadata object also has a property named required that should be ignored. It will be removed in a future version of the Workbench.

Field types

A field can be one of the following types:

  • character: A string of characters
  • number: A numeric value
  • formatted: An arbitrary JSON object (whose details depend on the specific field)
  • timestamp: A date/time value specified as DateTime Ticks
  • timelength: A duration value specified as TimeSpan Ticks

Additional types may be added in future versions of the Workbench.

Filter metadata objects

Each filter metadata object will have the following structure:

{
    "type": <string>,                       // see below for details
    "__type": <string>,                     // see below for details
    <other properties as described below>
}

The value of the type property determines which additional properties will be included in the filter metadata object. Please see below for information about each possible type value. Additional filter types may be introduced in future releases of the Workbench.

The value of the __type property is specific to the server-side implementation of each type, and may change from release to release. That value is important, however - any query that uses a filter must pass the appropriate __type value back to the server, as part of the query request.

There may be other properties in the filter metadata object (in addition to the ones described below), which should be ignored. They will be removed in a future version of the Workbench.

Filter type: Application

The Application filter type indicates that the field can be filtered by specifying a list of application objects. Each application object actually defines a specific company, application, and version - so in most cases a single real-world application will actually have multiple application objects, one for each version of the application.

The metadata query provides a list of all available application objects, as part of the filter metadata object, in a property named values.

For example:

{
    "type": "Application"
    "__type": "AggregationDTO.PickFilterDTO, AggregationDTO"
    "values": <array of application metadata objects>
}

Application metadata objects

Each application metadata object will have the following structure:

{
    "__type": <string>,                 // see below for details
    "value": <string>,                  // a unique ID for the application
    "value_type": <string>,             // see below for details
    "format": <string>,                 // a human-readable summarized name for the application
    "metadata": {
        "AppId": <GUID>,                // the app-supplied app ID
        "AppName": <string>,            // an optional app-supplied app name
        "CompanyId": <GUID>,            // the app-supplied company ID
        "CompanyName": <string>,        // an optional app-supplied company name
        "Version": <string>             // an optional app-supplied version string
    }
}

The metadata sub-object also has a property named AppGroupId that should be ignored. It will be removed in a future version of the Workbench.

The value of the __type property is specific to the server-side implementation of each type, and may change from release to release. That value is important, however - any query that uses an Application filter must pass the __type value back to the server, as part of each Application object in the filter.

The value_type property is meant to specify the data type of the value property's value. The value_type property currently always has a value of characters. Future versions of the Workbench may use additional values, or the value_type property may be removed entirely.

There may be other properties in this object, which should be ignored. They will be removed in a future version of the Workbench.

Note: For the purpose of filtering queries, only the __type and value fields need to be preserved. The rest of the fields are provided for human consumption.

Filter type: DateRange

The DateRange filter type indicates that the field can be filtered by specifying min and max dates (timestamps).

For example:

{
    "type": "DateRange",
    "__type": "AggregationDTO.RangeFilterDTO, AggregationDTO",
    "min": 630822996000000000,          // a value in Ticks, see below for details
    "max": 635337740683512287           // a value in Ticks, see below for details
}

The min and max values are specified as Ticks. They indicate the earliest and latest timestamps that can be specified as part of the filter.

There may be other properties in this object, which should be ignored. They will be removed in a future version of the Workbench.

Filter type: Many

The Many filter type indicates that the field can be filtered by specifying a list of individual values. The allowed values are not provided by the metadata query; they may be obtained by running a regular data query.

An example:

{
    "type": "Many",
    "__type": "AggregationDTO.PickFilterDTO, AggregationDTO"
}

There may be other properties (including an empty values property) in this object, which should be ignored.



Workbench Version 1.2.0. Copyright © 2016 PreEmptive Solutions, LLC