Data Query API Overview

Learn more about the Data Query API.

The Data Query API allows you to retrieve data from Visier in aggregate or list form:

• Aggregate: This aggregates data for a single object in Visier, usually across time. For example, you can perform a single aggregation to retrieve your organization's headcount over the last 12 months grouped by Location and filtered by Organization.
• List: This returns a list of values for objects at a specific time. The values are not aggregated. For example, you can perform a list query to retrieve the names of the female employees in your organization at a specific time.

If you use Visier to visualize your data, the above actions have a direct correlation to the interface you see in the solution experience, including the Explore room and the Detailed View visual. The following examples illustrate this relationship.

The below image shows a Breakdown of Headcount by Job Pay Level, filtered to Female employees for July 2020 to September 2020.

You can retrieve the data shown in the above image using the Data Query API aggregate action. The components in the image correspond to API as follows. For more information, see "Data Query" in API Reference.

1. Metric picker: The metric that you're retrieving data for. For more information, see "AggregationQuerySource" in the API Reference. In this example, the parameters are:

   Copy

   1
   2
   3
   "source": {
           "metric": "employeeCount"
   }

2. Group By picker: The selection concepts or dimensions that you want to group the data by. For more information, see "QueryAxis" in the API Reference. In this example, the parameters are:

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   "axes": [
         {
           "dimensionMemberSelection": {
             "dimension": {
               "name": "Pay_Level",
               "qualifyingPath": "Employee"
             },
             "members": [
               { "path": ["Low"] },
               { "path": ["High"] }
            ]
         }
      }
   ]

3. Time picker: The time during which the data is valid. For more information, see "QueryTimeInterval" in the API Reference. In this example, the parameters are:

   Copy

   1
   2
   3
   4
   5
   "timeIntervals": {
         "fromDateTime": "2020-10-01",
         "intervalPeriodType": "MONTH",
         "intervalCount": 3
   }

   Note: If defining timeInterval in a list query or timeIntervals in an aggregate or snapshot query, the direction value impacts the meaning of the defined time value (fromDateTime and fromInstant).

   • When the direction is BACKWARD, the specified time value is excluded.
     • Events that occur on the specified date are excluded.
     • If the data is subject-based, data that ends on the specified date is included because the ending event is excluded.
   • When the direction is FORWARD, the specified time value is included.

   The default direction is BACKWARD. This means the platform queries backwards from the specified time. You can define direction: FORWARD to query forwards from the specified time.

   For aggregate query results, Visier returns the technical member name for time; for example, 2019-06-01T00:00:00.000Z - [0]. You can request "options": { "memberDisplayMode": "DISPLAY" } for aggregate queries to return time members with a display name matching the caller’s locale; for example, May 31, 2019.

4. Filter picker: The values to include or exclude from the data. For more information, see "QueryFilter" in the API Reference. In this example, the parameters are:

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   "filters": [
         {
           "selectionConcept": {
             "name": "isFemale",
             "qualifyingPath": "Employee"
         }
      }
   ]

5. Group: The groups that the data members belong to, as defined by the Group By. For more information, see "QueryDimensionMemberSelection" in the API Reference. In this example, the parameters are:

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   "axes": [
         {
           "dimensionMemberSelection": {
             "dimension": {
               "name": "Pay_Level",
               "qualifyingPath": "Employee"
             },
             "members": [
               { "path": ["Low"] },
               { "path": ["High"] }
            ]
         }
      }
   ]

6. Value: The aggregated value for the query returned by the response.

The next image shows the Detailed View information for the Headcount of female employees for September 2020.

You can retrieve the data shown in the above image using the Data Query API list action. The components in the image correspond to the API as follows:

1. Detailed View: The underlying set of subject members or event occurrences that make up a given population. See "Query a list of details" in the API Reference. In this example, the request URL is: POST https://jupiter.api.visier.io/v1/data/query/list

2. Subject: The subject associated with the metric. For more information, see "ListQuerySource" in the API Reference. In this example, the parameters are:

   Copy

   1
   2
   3
   "source": {
           "metric": "employeeCount"
   }

3. Time picker: The time during which the data is valid. For more information, see "QueryTimeInterval" in the API Reference. In this example, the parameters are:

   Copy

   1
   2
   3
   4
   5
   "timeIntervals": {
         "fromDateTime": "2020-10-01",
         "intervalPeriodType": "MONTH",
         "intervalCount": 1
   }

   Note: If defining timeInterval in a list query or timeIntervals in an aggregate or snapshot query, the direction value impacts the meaning of the defined time value (fromDateTime and fromInstant).

   • When the direction is BACKWARD, the specified time value is excluded.
     • Events that occur on the specified date are excluded.
     • If the data is subject-based, data that ends on the specified date is included because the ending event is excluded.
   • When the direction is FORWARD, the specified time value is included.

   The default direction is BACKWARD. This means the platform queries backwards from the specified time. You can define direction: FORWARD to query forwards from the specified time.

   For aggregate query results, Visier returns the technical member name for time; for example, 2019-06-01T00:00:00.000Z - [0]. You can request "options": { "memberDisplayMode": "DISPLAY" } for aggregate queries to return time members with a display name matching the caller’s locale; for example, May 31, 2019.

4. Filter: The values to include or exclude from the data. For more information, see "QueryFilter" in the API Reference. In this example, the parameters are:

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   "filters": [
         {
           "selectionConcept": {
             "name": "isFemale",
             "qualifyingPath": "Employee"
         }
      }
   ]

5. Value: The list of values returned by the response.