Splunk.TimeRange
Important notice: As part of Advanced XML deprecation, the Module System is officially deprecated beginning with Splunk Enterprise 6.3. For more information, see Advanced XML Deprecation. |
clone()
The clone() method gets a copy of the current time range.
Synopsis
range = clone()
Return Value
Object | Splunk.TimeRange object, which is a copy of the current time range object. |
Example
var context = this.getContext();var search = context.get('search');
var range = search.getTimeRange();
var cloned_range = range.clone();
containsRange()
The containsRange() method checks if the specified timeRange is contained in the current time range, inclusive.
Note: This method is only accurate given absolute terms in both the specified range and the current, stored time range. If relative or real-time terms are used, the method always returns true.
Synopsis
contains = containsRange( timeRange )
Parameters
timeRange | Object | Splunk.TimeRange object to test against current time range. |
Return Value
Boolean | Time range included indication: True = Specified timeRange is included in the current time range, or there are relative or real-time terms in the current time range object. False = Specified timeRange is not included in the current time range. |
Example
var context = this.getContext();var search = context.get('search');
var range = search.getTimeRange();
var new_range = new Splunk.TimeRange('-15m', 'now');
if (range.containsRange(new_range)) {
alert('this will always fire since new_range is relative');
}
var new_range = new Splunk.TimeRange('1311695438', '1311695498');
if (range.containsRange(new_range)) {
alert('this will fire only if range contains new_range or if range contains real-time or relative terms');
}
See Also
containsTime()
equalToRange()
isAbsolute()
isRealTime()
isRelative()
containsTime()
The containsTime() method checks if the specified dateObj time is contained in the current time range.
Note: This method is only accurate for absolute terms contained in the current time range. If relative or real-time terms are used, the method always returns true.
Synopsis
contains = containsTime( dateObj )
Parameters
dateObj | Object | Time, of type JavaScript Date() object. |
Return Value
Boolean | Time included indication: True = Specified dateObj is included in current time range, or there are relative or real-time terms in the current time range object. False = Specified dateObj is not included in current time range. |
Example
var context = this.getContext();var search = context.get('search');
var range = search.getTimeRange();
var new_time = new Date();
if (range.isAbsolute() && range.containsTime(new_time)) {
alert('this will fire only if range is absolute and contains new_time');
}
See Also
containsRange()
equalToRange()
isAbsolute()
isRealTime()
isRelative()
equalToRange()
The equalToRange() method checks if the specified range time range object is equal to the current time range.
Synopsis
equals = equalToRange( range )
Parameters
range | Object | TimeRange object to compare against the current time range. |
Return Value
Boolean | Time range equality indication: True = Specified range is equal to the current time range. Always returns true for relative or real-time terms in current time range object. False = Specified range is not equal to the current time range. |
Example
var context = this.getContext();var search = context.get('search');
var range = search.getTimeRange();
var new_range = new Splunk.TimeRange('-15m', 'now');
if (range.equalToRange(new_range)) {
alert('this fires only if range is equivalent to new_range');
}
See Also
containsRange()
containsTime()
isAbsolute()
isRealTime()
isRelative()
formatRelativeRange()
The formatRelativeRange() method gets a text-formated representation of the current time range.
Synopsis
formattedRange = formatRelativeRange()
Return Value
String | Text-formatted representation of the current time range. |
Throws
"Assertion failed - we dont support cases where one side has snapUnits and the other does not."
Example
var range = new Splunk.TimeRange('-15m', 'now');if (range.isRelative()) {
alert(range.formatRelativeRange());
}
See Also
getAbsoluteEarliestTime()
The getAbsoluteEarliestTime() method gets the absolute earliest time of the current time range object.
Note: This is intended to be a private method.
Synopsis
time = getAbsoluteEarliestTime()
Return Value
Object | Absolute earliest time, of JavaScript type Date(). False, if time is relative. |
Example
var context = this.getContext();var search = context.get('search');
var range = search.getTimeRange();
if (range.isAbsolute()) {
alert(range.getAbsoluteEarliestTime().toString());
}
See Also
getAbsoluteLatestTime()
getEarliestTimeTerms()
getLatestTimeTerms()
getRelativeEarliestTime()
getRelativeLatestTime()
getAbsoluteLatestTime()
The getAbsoluteLatestTime() method gets the absolute latest time in the current time range object.
Note: This method is intended to be a private method.
Synopsis
time = getAbsoluteLatestTime()
Return Value
Object | Absolute latest time, of JavaScript type Date(). False, if the time is relative. |
Example
var context = this.getContext();var search = context.get('search');
var range = search.getTimeRange();
if (range.isAbsolute()) {
alert(range.getAbsoluteEarliestTime().toString());
}
See Also
getAbsoluteEarliestTime()
getEarliestTimeTerms()
getLatestTimeTerms()
getRelativeEarliestTime()
getRelativeLatestTime()
getDuration()
The getDuration() method gets the interval between the absolute current time range earliest and latest times.
Synopsis
duration = getDuration()
Return Value
Integer | Interval, in milliseconds, between the earliest and latest times in the current time range. Returns -1, if the current time range is relative. |
Example
if (timeRange.getDuration() == -1)
{
this._activator.text(timeRange.toConciseString());
}
else {
this._activator.text(this.CUSTOM_TIME_LABEL);
}
See Also
isAbsolute()
isRealTime()
isRelative()
getEarliestTimeTerms()
The getEarliestTimeTerms() method gets the earliest time since the epoch, in seconds, for absolute current time, or a Splunk time string representing the earliest time, for relative current time.
Synopsis
time = getEarliestTimeTerms()
Return Value
Integer, String | Absolute current time: Earliest time since the epoch, in seconds. Relative current time: Splunk time string representing earliest time. |
Example
updatePermalinks: function(event) { var context = this.getContext();
var search = context.get("search");
var args = {};
args["q"] = Splunk.util.addLeadingSearchCommand(search.toString());
var range = search.getTimeRange();
if (range) {
if (range.getEarliestTimeTerms()) {
args["earliest"] = range.getEarliestTimeTerms();
}
if (range.getLatestTimeTerms()) {
args["latest"] = range.getLatestTimeTerms();
}
}
$("li." + this.PERMALINK_SEARCH_CLASS + " a", this.container).attr("href", "?" + Splunk.util.propToQueryString(args));
$("li." + this.PERMALINK_SID_CLASS + " a", this.container).attr("href", "?sid=" + encodeURIComponent(search.job.getSearchId()));
},
See Also
getAbsoluteEarliestTime()
getAbsoluteLatestTime()
getLatestTimeTerms()
getRelativeEarliestTime()
getRelativeLatestTime()
getLatestTimeTerms()
The getLatestTimeTerms() method gets the latest time since the epoch, in seconds, for absolute current time, or a Splunk time string representing the latest time, for relative current time..
Synopsis
time = getLatestTimeTerms()
Return Value
Integer String | Absolute current time: Latest time since the epoch, in seconds. Relative current time: Splunk time string representing latest time. |
Example
updatePermalinks: function(event) { var context = this.getContext();
var search = context.get("search");
var args = {};
args["q"] = Splunk.util.addLeadingSearchCommand(search.toString());
var range = search.getTimeRange();
if (range) {
if (range.getEarliestTimeTerms()) {
args["earliest"] = range.getEarliestTimeTerms();
}
if (range.getLatestTimeTerms()) {
args["latest"] = range.getLatestTimeTerms();
}
}
$("li." + this.PERMALINK_SEARCH_CLASS + " a", this.container).attr("href", "?" + Splunk.util.propToQueryString(args));
$("li." + this.PERMALINK_SID_CLASS + " a", this.container).attr("href", "?sid=" + encodeURIComponent(search.job.getSearchId()));
},
See Also
getAbsoluteEarliestTime()
getAbsoluteLatestTime()
getEarliestTimeTerms()
getRelativeEarliestTime()
getRelativeLatestTime()
getRelativeEarliestTime()
The getRelativeEarliestTime() method gets the earliest time of the relative current time range.
Note: This method is intended to be private.
Synopsis
time = getRelativeEarliestTime()
Return Value
String | Splunk time representation of the earliest time in the current time range. Returns false for an absolute current time range. |
Example
var context = this.getContext();var search = context.get('search');
var range = search.getTimeRange();
if (range.isRelative()) {
alert(range.getRelativeEarliestTime().toString());
}
See Also
getAbsoluteEarliestTime()
getAbsoluteLatestTime()
getEarliestTimeTerms()
getLatestTimeTerms()
getRelativeLatestTime()
getRelativeLatestTime()
The getRelativeLatestTime() method gets the latest time of the relative current time range.
Note: This method is intended to be private.
Synopsis
time = getRelativeLatestTime()
Return Value
String | Splunk time representation of the latest time in the current time range. Returns false for an absolute current time range. |
Example
var context = this.getContext();var search = context.get('search');
var range = search.getTimeRange();
if (range.isRelative()) {
alert(range.getRelativeEarliestTime().toString());
}
See Also
getAbsoluteEarliestTime()
getAbsoluteLatestTime()
getEarliestTimeTerms()
getLatestTimeTerms()
getRelativeEarliestTime()
getTimeFormat()
The getTimeFormat() method gets a formatted absolute time used by the REST API. This method wraps Splunk.util.getConfigValue( 'DISPATCH_TIME_FORMAT' ).
Synopsis
formattedTime = getTimeFormat()
Return Value
String | Server configured dispatch time format |
Example
var context = this.getContext();var search = context.get('search');
var range = search.getTimeRange();
alert(range.getTimeFormat());
See Also
isAbsolute()
The isAbsolute() method tests if the earliest and latest times in the current time range are absolute.
Synopsis
results = isAbsolute()
Return Value
Boolean | Absolute time representation indication: true = Time range is absolute. false = Time range is not absolute. |
Example
updateTimeHeader: function(range) {
var job = this.getContext().get("search").job;
var actualIndexRange = new Splunk.TimeRange(job["_searchEarliestTime"], job["_searchLatestTime"]);
if (!actualIndexRange.isAllTime()) {
if (range.isAbsolute()) {
header = sprintf(_("%(humanReadableTime)s (%(actualAbsoluteTime)s)"),
{humanReadableTime: header,
actualAbsoluteTime: actualIndexRange.toConciseString()}); }
}
this._timeRangeHeader.text(header);
},
See Also
containsRange()
containsTime()
equalToRange()
getDuration()
isAllTime()
isRealTime()
isRelative()
isAllTime()
The isAllTime() method tests if the time range is "all time," unbounded earliest and latest time.
Synopsis
allTime = isAllTime()
Return Value
Boolean | "all time" time range indication: true = Time range is "all time." false = Time range is not "all time." |
Example
updateTimeHeader: function(range) {
var header = this.getMatchingCustomHeader(range) range.toConciseString();
var job = this.getContext().get("search").job;
var actualIndexRange = new Splunk.TimeRange(job["_searchEarliestTime"], job["_searchLatestTime"]);
if (!actualIndexRange.isAllTime()) {
if (range.isAbsolute()) {
header = sprintf(_("%(humanReadableTime)s (%(actualAbsoluteTime)s)"),
{humanReadableTime: header,
actualAbsoluteTime: actualIndexRange.toConciseString()});
}
}
this._timeRangeHeader.text(header);
},
See Also
containsRange()
containsTime()
equalToRange()
isAbsolute()
isRealTime()
isRelative()
isRealTime()
The isRealTime() method tests if the current time range is a real-time representation.
Synopsis
realTime = isRealTime()
Return Value
Boolean | Real-time current time range indication: true = Current time range is real-time. false = Current time range is not real-time. |
Example
onContextChange: function() { var context = this.getContext();
var search = context.get("search");
var range = search.getTimeRange();
var currentSID = search.job.getSearchId();
if (range.isRealTime() ) {
this.hide(this.PREVIEW_AND_REAL_TIME_CONFLICT);
}
else {
this.show(this.PREVIEW_AND_REAL_TIME_CONFLICT);
if (search.isJobDispatched() && !search.job.isDone() && currentSID != this.previousSID) {
search.job.setPreviewable(this.isChecked());
}
}
this.previousSID = currentSID;
},
See Also
containsRange()
containsTime()
equalToRange()
getDuration()
isAbsolute()
isAllTime()
isRelative()
isRelative()
The isRelative() method tests if the current time range is relative.
Synopsis
relative = isRelative()
Return Value
Boolean | Relative time representation indication: true = Time range is relative. false = Time range is not relative. |
Example
var context = this.getContext();var search = context.get('search');
var range = search.getTimeRange();
if (range.isRelative()) {
alert(range.getRelativeLatestTime().toString());
}
See Also
containsRange()
containsTime()
equalToRange()
formatRelativeRange()
getDuration()
isAbsolute()
isAllTime()
isRealTime()
isSubRangeOfJob()
The isSubRangeOfJob() method checks if the current time range is a sub-range of the underlying job. If setAsSubRangeOfJob( true ) was previously called when selection part of the original time range to drill down, this method may need to be called to determine if a new search needs to be dispatched.
Synopsis
results = isSubRangeOfJob()
Return Value
Boolean | Sub-range indication: true = Current time range is a sub-range of the underlying job time range. false = Current time range is a not sub-range of the underlying job time range. |
Example
requiresDispatch: function(search) {
search = search new Splunk.Search();
if (this.requiresTransformedResults()) {
var range = search.getTimeRange();
if (range.isSubRangeOfJob()) {
return true;
}
}
},
See Also
setAsSubRangeOfJob()
The setAsSubRangeOfJob() method must be called to indicate that the current time range is a subset of the underlying job time range.
If the Splunk.TimeRange instance attached to a Splunk.Search instance was modified to represent a sub-range, with the start and end times corresponding to boundaries on the timelineData structure in splunkd, the client is required to call setAsSubRangeOfJob(). The time range is typically changed when interacting with the REST API timeline endpoint, such that the search time range becomes a sub-range of the job time range.
Synopsis
setAsSubRangeOfJob( isSubrange )
Parameters
isSubrange | Boolean | Current time range is a sub-range indication: true = Current time range is a sub-range of underlying job time range. false = Current time range is not a sub-range of underlying job time range. |
Return Value
Undefined
Example
getSelectionRange: function(selectedBuckets) {
selectedBuckets = selectedBuckets this.bridge.callMethod("getSelectedBuckets");
var numberOfBuckets = selectedBuckets.length;
if (numberOfBuckets==0) {
this.logger.error(this.moduleType,
" getSelectionRange returned an empty selectedBuckets");
return new Splunk.TimeRange();
}
var earliestBucket = selectedBuckets[0];
var latestBucket = selectedBuckets[numberOfBuckets-1];
var range = new Splunk.TimeRange(earliestBucket["earliestTime"],
latestBucket["latestTime"]);
range.setAsSubRangeOfJob(!this.isEntireRangeSelected);
return range;
},
See Also
toConciseString()
The toConciseString() method gets a compact, localized time range in human-readable form.
Synopsis
timeRange = toConciseString()
Return Value
Boolean | Success |
Example
updateTimeHeader: function(range) { var header = this.getMatchingCustomHeader(range) range.toConciseString();
var job = this.getContext().get("search").job;
var actualIndexRange = new Splunk.TimeRange(job["_searchEarliestTime"],
job["_searchLatestTime"]);
if (!actualIndexRange.isAllTime()) {
if (range.isAbsolute()) {
header = sprintf(_("%(humanReadableTime)s (%(actualAbsoluteTime)s)"),
{humanReadableTime: header,
actualAbsoluteTime: actualIndexRange.toConciseString()}); }
}
this._timeRangeHeader.text(header);
},
See Also
toString()
The toString() method serializes the current time range.
Synopsis
timeRange = toString()
Return Value
String | Serialized time range. |
Example
var context = this.getContext();var search = context.get('search');
var range = search.getTimeRange();
alert(range.toString());
See Also
Splunk.Search | Splunk.util |
This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9
Feedback submitted, thanks!