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

isRelative()

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

Splunk.util.getConfigValue()

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()

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

isSubRangeOfJob()

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()

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

toConciseString()