QScript DateTimeAggregationSettings

DateTimeAggregationSettings

Represents date/time aggregation settings for a variable, as used by setDateTimeAggregationSettings().

aggregation

The length of each time period, as a DateQuantum. The dates are grouped into periods of this length. The periods follow each other with no gap, and each date falls in one period. So { numPeriods: 3, periodUnit: "Month" } gives quarters. On set(), null and an omitted aggregation both store the current value, so a variable that was following its guessed unit stops following it and keeps the unit it had. Unlike periodAnchor, minimum and maximum, null does not clear the field, and no input clears it. get() always returns an aggregation.

Example:

variable.setDateTimeAggregationSettings({ aggregation: { numPeriods: 3, periodUnit: "Month" } });

duration

How far back from the latest date the variable reaches, as a DateQuantum. Used when periodType is "Duration". Older dates are left out, so { numPeriods: 6, periodUnit: "Month" } keeps the last six months. A filter moves the latest date, and the span moves with it. Any call that passes periodType as "Duration" must also supply this field. A read of a Duration variable always returns the field, so a get() then set() round trip supplies it. On set(), null and an omitted field both keep the current duration, but only when the call leaves periodType out. get() returns this field only while periodType is "Duration".

Example:

variable.setDateTimeAggregationSettings({ periodType: "Duration", duration: { numPeriods: 6, periodUnit: "Month" } });

maximum

When periodType='Date Range': Maximum date/time ("yyyy-MM-dd" or ISO 8601 string). Null means "not set": on get() (with include_default_values = false) it is tracking its computed default. On set(), omitting the field leaves it exactly as it is, while passing null explicitly clears any stored value so it goes back to tracking its default.

minimum

When periodType='Date Range': Minimum date/time ("yyyy-MM-dd" or ISO 8601 string). Null means "not set": on get() (with include_default_values = false) it is tracking its computed default. On set(), omitting the field leaves it exactly as it is, while passing null explicitly clears any stored value so it goes back to tracking its default.

periodAnchor

Period anchor date/time ("yyyy-MM-dd" or ISO 8601 string). Null means "not set": on get() (with include_default_values = false) the anchor is tracking its computed default. On set(), omitting the field leaves the anchor exactly as it is, while passing null explicitly clears any stored anchor so it goes back to tracking its default.

periodType

Which dates the variable covers, and which other fields apply. Where the periods break follows periodAnchor, for the units that can be anchored: "Week", "Fortnight", "Four Week", "Month", "Quarter" and "Year". A stored anchor puts a period boundary on the anchor date. An unset anchor uses a default that depends on the period type, named below. "All Data" covers every date. The default anchor falls on a natural boundary, such as the start of a month. A filter changes the periods shown. minimum, maximum and duration are not used. "Date Range" covers minimum to maximum, with each end widened to a whole period. The default anchor is maximum, so the periods count back from there. The range starts at the beginning of the period holding minimum, and ends at the end of the period holding the day before maximum. So dates a little before minimum, and maximum itself, can appear. A filter does not change the periods. A call that first sets periodType to "Date Range" must supply minimum and maximum. A variable already in Date Range may omit both and keep its current values. "Duration" covers a span back from the latest date, such as the last six months. The default anchor falls on a natural boundary. A filter moves the latest date and the periods. Any call that passes periodType as "Duration" must also supply duration. On set(), null and an omitted periodType both store the current value. The default is the fixed value "All Data", so storing it changes nothing a reader would notice. get() always returns a periodType.

type

Returns 'DateTimeAggregationSettings'.