Result
The Vizzly Dashboard expects results to be returned in a certain format, so that the data can be plotted on the components placed on the dashboard.
The result object has a fields
key describing each the fields
that correspond to the array of values in the content
key.
Format
export namespace Result {
export type RowOfValues = Array<string | number | Date | null>;
export type Field = {
// ID of the field, matching the ID of the field in the data set.
id: string;
// Name of the field your users will see
publicName: string;
// What data type is the field before the aggregation?
// For example, if the field holds a `count` aggregation of
// `string` fields, then the dataType here would be `string`.
dataType: "number" | "boolean" | "string" | "date_time";
};
}
export type Result = {
fields: Array<Result.Field>;
content: Array<Result.RowOfValues>;
};
Example result
This is an example of a result from a query for a single stat component. It contains one string field where the
count
aggregate has been applied to it, and because it's a single stat there is only one row of results.
{
"fields": [
{
// Note the `_count` appended to the ID of the field.
// If the aggregate is `none`, then nothing should be appended to the field.
"id": "name_count",
"publicName": "Name",
// Note that even when a number is returned, the `dataType` is still
// that of the original type of the field.
"dataType": "string"
}
],
"content": [
// Note only one row of results because this is a result for a single stat component.
// Results for other components such as timeseries charts will commonly have many more
// results in here.
[619040]
]
}
Result field IDs
Appended to all fields which contains an aggregated result, you'll find a string representing that aggregate. This enables the same field to be used with multiple aggregates.
The exact string denoting the aggregate function used in the query, should be appended to the field
ID with an _
separator. The only exception to this rule is the none
aggregate, which should not
have any value appended to the field ID.
For example, a countDistinct
aggregate on a field with ID of name
would have the result field ID of
name_countDistinct
.
Mapping a query to the result
A Vizzly query defines a list of measures, dimensions and a time dimension. All fields included in these properties should be included in the response. Dimension fields should be treated as having no aggregate, and should therefore not have any value appended to their ID.
Error handling
Currently, errors are handled by simply returning null
instead of the array of results.
Validation
The Vizzly frontend runs some basic validations on the results generated based on the query that we sent. If things aren't working as expected, it is always worth checking the console output in the browser to see if there's a friendly validation error message waiting for you. If not, please get in-touch with our support team and we can work with you on debugging it.