Splunk.Search

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.

abandonJob()

The abandonJob() method removes the search object Splunk.Job from the view Splunk.Jobber queue so the job is no longer be touched by the view. This eventually leads to the job expiring. This method is called by a module when it no longer requires the current job within the context search object, including any time there are search object changes that require a new job to be dispatched.

Synopsis

abandonJob()

Return Value

Undefined

Example

var context = this.getContext();var search = context.get('search');
search.abandonJob();

absorbIntentions()

The absorbIntentions() method uses the Parser REST endpoint to flatten the baseSearch and intentions array into a flattened search string, stored in fullSearchWithIntentions.

Synopsis

results = absorbIntentions( onSuccess, onFailure )

Parameters

onSuccess	`Function`	(Optional) Function to call upon successful operation.
onFailure	`Function`	(Optional) Function to call upon unsuccessful operation.

Return Value

Undefined

Throws

this._baseSearch + " is not a search"

Example

this.absorbIntentions();

addIntention()

The addIntention() method adds the specified intention dictionary to the previous intentions list.

Synopsis

addIntention( intentionDict )

Parameters

intentionDict Object Dictionary of intentions.

Return Value

Undefined

Throws

"Assertion Failed - addIntention called for null intention"

Example

getModifiedContext: function() {    var context = this.getContext();

   var legacyTarget = this.getParam('settingToConvert');
   var intention = $.extend(true, {}, this.getParam('intention'));
   var search = context.get("search");

if (legacyTarget) {

       var setting = context.get(legacyTarget);
       if (!setting) setting = "";
       intention = Splunk.util.replaceTokens(intention, this._legacyIntentionReplace, setting);
   } else {
       for (var i=0; i<this._matches.length; i++) {
       var key = this._matches[i]
       var replacer = new RegExp("\\$" + key + "\\$");
       intention = Splunk.util.replaceTokens(intention, replacer, context.get(key));
       }
   }

   search.addIntention(intention);
   context.set("search", search);
   return context;

clearIntentions()

The clearIntentions() method empties the search object intentions list, undefining savedSearchName if it is defined.

This method should be called by modules that call absorbIntentions(), if leaving intentions could result in unexpected behavior in subsequent calls to absorbIntentions().

Synopsis

clearIntentions()

Return Value

Undefined

Example

var context = this.getContext();var search = context.get('search');
search.absorbIntentions();
search.clearIntentions();
context.set('search', search);
return context;

clearTimeRange()

The clearTimeRange() method resets the search TimeRange object to the all time default and undefines savedSearchName, if it is defined.

Synopsis

this = clearTimeRange()

Return Value

Object Current object.

Example

var context = this.getContext();var search = context.get('search');
search.absorbIntentions();
search.clearIntentions();
context.set('search', search);
return context;

clone()

The clone () method instantiates a search object identical to the current context search object.

Synopsis

search = clone()

Return Value

Object Search object identical to the current context search object.

Example

var context = this.getContext();var search = context.get("search"); var newSearch = this.newSearch.clone();

dispatchJob()

The dispatchJob() method handles job dispatch requests, dispatching a search job and flattening intentions as needed, if the job is not already dispatched.

Note: This method is called by pushContextToChildren() in modules derived from AbstractModule and should not be called directly.

Synopsis

results = dispatchJob( onSuccess, onFailure ), group)

Parameters

onSuccess	`Object`	(Optional) Function to call on successful operation.
onFailure	`Object`	(Optional) Function to call on unsuccessful operation.
group	`String`	(Optional) group identifier for UI to display `last refreshed` text at the top of the appropriate group hierarchy.

Return Value

Boolean Job dispatch status:
True = Search job successfully dispatched.
False = Search job is already dispatched.

Example

search.dispatchJob(this._fireDispatchSuccessHandler.bind(this),

this._fireDispatchFailHandler.bind(this),

this.getGroupName());

equalToSearch()

The equalToSearch() method tests if a context current search is equal to the specified search, where the following properties are equivalent in both objects:

Search string
Job ID
Dispatch state
Intentions
Time range
Remote servers list
Event count
Post process

Synopsis

equal = equalToSearch( search )

Parameters

search Object Search object to compare to current context search object.

Return Value

Boolean Equivalent search object indication:
True = Search objects are equal.
False = Search objects are not equal.

Example

var context = this.getContext();var search = context.get('search');
if (search.equalToSearch(this._previousSearch)) {

   alert('search has not changed!');
   return true;

} else {

   alert('search has changed!');
   return false;

}

getBaseSearch()

The getBaseSearch() method gets the base search of the current context search object.

Synopsis

baseSearch = getBaseSearch()

Return Value

String Current context base search object.

Example

var context = this.getContext();var search  = context.get("search");
var searchString = search.getBaseSearch();
alert('search = ' + escape(searchString));

getDistributedServerList()

The getDistributedServerList() method gets the list of search peers for distributing the current search.

List items are splunkd instance names, not host names, and the list is used as the optional argument in the REST API remote_server_list set request.

Synopsis

remoteServerList = getDistributedServerList()

Return Value

Array List of search peers to distribute the current search to.

Example

var context = this.getContext();var search  = context.get("search");
var serverList = search.getDistributedServerList();
if ('https://amrit.splunk.com:8089' in serverList) {

   alert('Amrit up in the heezy!');

getEventAvailableCount()

The getEventAvailableCount() method gets the number of events available for export, for the current job.

Note: If there are no status buckets set for the current job, this method returns the result count (see getResultCount() ). This is the main difference between this method and getEventCount().

Synopsis

count = getEventAvailableCount()

Return Value

Integer Number of available events for the current job.

Example

var context = this.getContext();
var search = context.get('search');
var availableEvents = search.job.getEventAvailableCount();
console.log('Available event count = ' + availableEvents.toString());

getEventCount()

The getEventCount() method gets the number of events advertised for the current job.

Note: This method and getEventAvailableCount() often return different values. This method always returns the total number of events returned by the current job.

Synopsis

count = getEventCount()

Return Value

Integer Number of available events for the current job.

Example

var context = this.getContext();
var search = context.get('search');
console.log('Number of events in the current job = ' + search.job.getEventCount().toString());

getIntentionReference()

The getIntentionReference() method gets a reference to the intention specified by the specified intentionName, as constrained by the optional secondArgKey.

Synopsis

intention = getIntentionReference( intentionName, secondArgKey )

Parameters

intentionName	`String`	Name of the intention to get.
secondArgKey	`String`	(Optional) Secondary key, which must be present as an argument of `intentionName` for the reference to be retrieved.

Return Value

Object Reference to the specified intention.

Example

var context = this.getContext();var search = context.get('search');
var fieldsIntention = search.getIntentionReference('setfields');
if (fieldsIntention) {

   alert('setfields exists');

} else {

   alert('setfields does not exist');

getMaxCount()

The getMaxCount() method gets the search max count setting.

maxEvents maps to the splunkd REST API setting max_count, which is an optional argument specifying the maximum number of results that each of a search job's status buckets can contain. If the search is non-transforming, operates on only raw events, maxEvents has precedence. If the search is transforming, uses stats/timechart or similar, maxCount has precedence.

Synopsis

maxCount = getMaxCount()

Return Value

Integer Maximum number of results that each of the search job status buckets can contain.

Example

var context = this.getContext();var search  = context.get("search");
var maxCount = search.getMaxCount();
alert('maxCount = ' + escape(toString(maxCount)));

getMaxEvents()

The getMaxEvents() method gets the maxEvents setting for a search.

maxEvents maps to the splunkd REST API setting max_count, which is an optional argument specifying the maximum number of results that each of a search job's status buckets can contain. If the search is non-transforming, operates on only raw events, maxEvents has precedence. If the search is transforming, uses stats/timechart or similar, maxCount has precedence.

Synopsis

maxEvents = getMaxEvents()

Return Value

Integer Maximum number of events that each of the search job status buckets can contain.

Example

var context = this.getContext();var search  = context.get("search");
var maxEvents = search.getMaxEvents();
alert('maxEvents = ' + escape(toString(maxEvents)));

getMaxTime()

The getMaxTime() method gets the maxTime setting for a search, the number of seconds to run the search before finalizing.

Synopsis

maxTime = getMaxTime()

Return Value

Integer Maximum time that the current context search job should run, in seconds.

Example

var context = this.getContext();var search  = context.get("search");
var maxTime = search.getMaxTime();
if (maxTime > 300) {

   alert('maxTime value seems high');

} else {

   alert('maxTime value seems about right');

getMinimumStatusBuckets()

The getMinimumStatusBuckets() method gets the value of the statusBuckets setting for a search.

The needed number of status buckets is one of the parameters passed in the POST to dispatch a job. You need to allocate buckets to store job event information. Typically, allocating one status bucket is sufficient, while a module like flashtimeline needs to explicitly allocate 300 buckets to handle the default number of events it expects. By convention, a module only sets the number of buckets it needs for itself, if any. Parent modules should not the set bucket count for child modules.

The default minimum status buckets setting specified by SplunkWeb is 300.

Synopsis

minBuckets = getMinimumStatusBuckets()

Return Value

Integer Minimum number of status huckets prepared by the current context search job.

Example

var context = this.getContext();var search  = context.get("search");
var minBuckets = search.getMinimumStatusBuckets();
if (maxBuckets < 300) {

   alert('maxBuckets value seems low');

} else {

   alert('maxBuckets value seems about right');

getPostProcess()

The getPostProcess() method gets the postProcess value of the current search.

postProcess is an optional string stored in a search object, which is used by the post process subsystem to perform work on completed search artifacts.

Synopsis

postProcessVal = getPostProcess()

Return Value

String Search post process string.

Example

var context = this.getContext();var search  = context.get("search");
var postProcess = search.getPostProcess();
if (postProcess) {

   alert('postProcess = ' + escape(postProcess));

} else {

   alert('this search does not have a value for postProcess');

getRequiredFieldList()

The getRequiredFieldList() method gets the requiredFieldList of the current search. This is a list of fields that must be present in the result set, even if empty. The default value is empty.

Synopsis

fieldList = getRequiredFieldList()

Return Value

Array Required field list.

Example

var context = this.getContext();var search  = context.get("search");
var rfl = search.getRequiredFieldList();
if (rfl) {

   $.each(rfl, function(i, v) {
       alert('requireField = ' + escape(v));
   });

} else {

   alert('this search has no required field list');

getSavedSearchName()

The getSavedSearchName() method gets the savedSearchName of the current search.

Synopsis

searchName = getSavedSearchName()

Return Value

String Saved search name. Default = undefined.

Example

var context = this.getContext();var search  = context.get("search");
var savedSearch = search.getSavedSearchName();
if (savedSearch) {

   alert('savedSearch = ' + escape(savedSearch));

} else {

   alert('this search object does not reference a saved search');

getTimeRange()

The getTimeRange() method gets a Splunk.TimeRange instance representing the current job data absolute time range.

Synopsis

timeRange = getTimeRange()

Return Value

Object Splunk.TimeRange instance representing the absolute time range of the current job data.

Example

var context = this.getContext();
var search = context.get('search');
console.log('Timerange: ' + search.job.getTimeRange().toString());

getUrl()

The getUrl() method gets the URI to access resources for the current search job.

Synopsis

jobURI = getUrl( asset, optionalArgs)

Parameters

asset	`String`	(Optional) asset type: results control summary events timeline
optionalArgs	Object	(Not implemented)

Return Value

String Job URI.

Example

var context = this.getContext();var search  = context.get("search");
var url = search.getUrl();

alert('results url is ' + url);

getViewStateId()

The getViewStateId () method gets the current search object viewStateId property. The viewStateId property is used by the Splunk view state subsystem to maintain per-view preferences.

Synopsis

viewStateID = getViewStateId()

Parameters

Return Value

String Current search object viewStateId.

Example

var context = this.getContext();var search  = context.get("search");
var id = search.getViewStateId();
alert('vsid = ' + escape(id));

hasIntentions()

The hasIntentions() method indicates if the current search object has intentions.

Synopsis

results = hasIntentions()

Return Value

Boolean Search object has intentions indication:
True = Search object has intentions.
False = Search object does not have intentions.

Example

var context = this.getContext();var search  = context.get("search");
if (search.hasIntentions()) {

   search.absorbIntentions();

}
context.set('search', search);
return context;

isJobDispatched()

The isJobDispatched() method indicates if the current job has been dispatched.

Synopsis

status = isJobDispatched()

Return Value

Boolean Job dispatch status:
true = Current job has been dispatched.
false = Current job has not been dispatched.

Example

var context = this.getContext();var search  = context.get("search");
if !(search.isJobDispatched()) {

   search.setBaseSearch('search index=_internal sourcetype=splunkd');

} else {

   alert('cannot set base search since search is already dispatched');

}
context.set('search', search);
return context;

popIntention()

The popIntention() method gets the specified intention, intentionName, constrained by the optional secondArgKey parameter. The retrieved intention is removed from the intentions list.

Synopsis

intention = popIntention( intentionName, secondArgKey)

Parameters

intentionName	`String`	Name of intention to be retrieved and removed from list.
secondArgKey	`String`	(Optional) Secondary key that must be present as an argument of the intentionName for the reference to be removed and returned.

Return Value

Object Requested intention.

Example

var context = this.getContext();var search = context.get('search');
if (search.getIntentionReference('setfields')) {

   search.popIntention('setfields');

resurrect()

The resurrect() method gets a search object containing a previously dispatched job.

Synopsis

search = resurrect( paramsDict )

Parameters

paramsDict String Dictionary of URI name-value pair GET request params.

Return Value

Object JSON dictionary as generated by view.py resurrection code.

Example

this.savedSearch = Splunk.Search.resurrect(this._params['jsonSearch']);

sendToView()

The sendToView() method redirects the user and current search to the specified view, performing redirection across views while retaining the current search object.

Synopsis

results = sendToView( viewName, additionalArgs, dispatchBeforeRedirect, openInPopup, options, appName)

Parameters

viewName	`String`	Dictionary of URI name-value pair GET request params.
additionalArgs	`Object`	(Optional) Not implemented.
dispatchBeforeRedirect	`Bool`	Enable dispatching of search job before redirection: True = Enable. False = Disable.
openInPopup	`Bool`	Enable opening of destination window as a popup: True = Enable. False = Disable.
options	`Object`	(Optional) window features representation for destination window object: `windowFeatures` {String} standard XHR window options. Default: "resizable=yes,status=no,scrollbars=yes,toolbar=no" `autosize` {Bool} Enables destination window autosizing: True = Enable. False = Disable (default)
appName	`String`	(Optional) Name of app to redirect to. Default = current app.

Return Value

Boolean Success

Example

var context = this.getContext();
var search  = context.get("search");
var options = {}
var additionalArgs = {}

search.sendToView('charting', additionalArgs, false, true, options);

setBaseSearch()

The setBaseSearch() method replaces the current base search string with the specified search string. This method is the primary interface for setting the base search string. This method also undefines fullSearchWithIntentions and savedSearchName.

Note: You should not call this method against a search where the job has already been dispatched. Use isJobDispatched() to check the dispatch status.

Synopsis

setBaseSearch( search )

Parameters

search Object Search string to be set as new base search string.

Return Value

Undefined

Example

var context = this.getContext();
var search  = context.get("search");
search.setBaseSearch('search index=_internal  head 100');
context.set('search', search);
return context;

setDistributedServerList()

The setDistributedServerList() method sets the list search peers to which the context current search is distributed.

Note: This method is destructive, so preserve the existing list using getDistributedServerList().

Synopsis

results = setDistributedServerList( serverList )

Parameters

serverList Array List of splunkd instance names.

Return Value

Undefined

Example

var context = this.getContext();
var search  = context.get("search");
var serverList = ['https://foobar.splunk.com:8089', 'https://barfoo.splunk.com:8089'];
search.setDistributedServerList(serverList);
context.set('search', search);
return context;

setIntentions()

The setIntentions() method replaces the current search intentions with the specified intentions.

Synopsis

results = setIntentions( intentionsList )

Parameters

intentionsList Array Intentions list.

Return Value

Undefined

Example

setNewIntentions: function(intentionsList) {

   var context = this.getContext();
   var search = context.get('search');
   
   search.setIntentions(intentionsList);
   context.set('search', search);

},

setMaxCount()

The setMaxCount() method sets the search maxCount property, specifying the maximum number of results that each of a search job status buckets can contain.

Note: In general, the default maxCount value should not be changed. Also, if the search is dispatched with status_buckets >= 1, the maxCount setting are ignored by splunkd.

Synopsis

setMaxCount( maxCount )

Parameters

maxCount Integer Maximum job status bucket results count. Default = 10,000.

Return Value

Undefined

Example

var context = this.getContext();
var search  = context.get("search");
search.setMaxCount(31337);
context.set('search', search);
return context;

setMaxEvents()

The setMaxEvents() method sets the maxEvents property for a search, specifying the maximum number of events that each of a search job status buckets can contain.

Note: If the search is dispatched with status_buckets>=1, the maxEvents setting is ignored by splunkd.

Synopsis

setMaxEvents( maxEvents )

Parameters

maxEvents Integer Maximum number of events in job status bucket. Default = 10,000.

Return Value

Undefined

Example

var context = this.getContext();
var search  = context.get("search");
search.setMaxEvents(31337);
context.set('search', search);
return context;

setMaxTime()

The setMaxTime() method sets the maximum time for a search.

Note: In general, the default value should not be changed.

Synopsis

setMaxTime( maxTime )

Parameters

maxTime Integer Maximum search time, in seconds. Default = 0, no constraint.

Return Value

Undefined

Example

var context = this.getContext();
var search  = context.get("search");
search.setMaxTime(31337);
context.set('search', search);
return context;

setMinimumStatusBuckets()

The setMinimumStatusBuckets() method specifies the minimum number of status buckets to generate for consumers, such as flashtimeline.

The needed number of status buckets is one of the parameters passed in the POST to dispatch a job. You need to allocate buckets to store job event information. Typically, allocating one status bucket is sufficient, while a module like flashtimeline needs to explicitly allocate 300 buckets to handle the default number of events it expects. By convention, a module only sets the number of buckets it needs for itself, if any. Parent modules should not the set bucket count for child modules.

If search consumers require access to raw events, specify a value between one and 300. If statusBuckets is less than the current value, the current value is not changed.

Synopsis

setMinimumStatusBuckets( statusBuckets )

Parameters

statusBuckets Integer Minimum number of status buckets that should be prepared by the current context search job.

Return Value

Undefined

Example

bucketFunction: function(statusBuckets) {

   var context = this.getContext();
   var search  = context.get("search");
   var minBuckets = search.getMinimumStatusBuckets();

   if (parseInt(statusBuckets) <= minBuckets) {
       alert('between you and me - this value is too low.  did you read the docs?');
   } else {
       search.setMinimumStatusBuckets(parseInt(statusBuckets));
   }
   
   context.set('search', search);
   return context;

},

setPostProcess()

The setPostProcess() method stores a post-processing string in the current search.

Synopsis

setPostProcess( search )

Parameters

search String Post-processing search string.

Return Value

Undefined

Example

var context = this.getContext();
var search  = context.get("search");
var postProcess = search.getPostProcess();
if (postProcess) {

   alert('There is already a postProcess!');

} else {

   search.setPostProcess('stats count');

}
context.set('search', search);
return context;

setRequiredFields()

The setRequiredFields() method sets the fields that must be present in the event or result set, including an empty list, for when your module needs to render certain fields without re-dispatching.

Synopsis

setRequiredFields( requiredFieldList )

Parameters

requiredFieldList Array List of fields that must be present in the event or result set. Default = empty.

Return Value

Undefined

Example

var context = this.getContext();
var search  = context.get("search");
search.setRequiredFields(['src_ip', 'dest_ip']);
context.set('search', search);
return context;

setSavedSearchName()

The setSavedSearchName() method sets the current search saved search name so the search object reference a particular saved search.

If a saved search name is defined, the baseSearch value is ignored.

Intentions are not compatible with search objects that reference a saved search.

Synopsis

setSavedSearchName( name )

Parameters

name String Saved search name.

Return Value

Undefined

Example

var context = this.getContext();
var search  = context.get("search");
search.setSavedSearchName('Errors in the last hour');
context.set('search', search);
return context;

setSelectedEventAvailableCount()

The setSelectedEventAvailableCount() method sets the search job event available count to the specified value. You should use this method to select a sub-range of the original time range for getEventAvailableCount() to return accurate results.

Synopsis

setSelectedEventAvailableCount( count )

Parameters

count Integer Event available count.

Return Value

Undefined

Example

var context = this.getContext();
var search  = context.get("search");
search.setSelectedEventAvailableCount(totalEventsAvailable);
search.setSelectedEventCount(totalEvents);
var range = this.getSelectionRange(selectedBuckets);
search.setTimeRange(range);
context.set("search", search);
return context;

setSelectedEventCount()

The setSelectedEventCount() method sets the current search job event count. You should use this method to select a sub range of the original time range for getEventCount() to return accurate results.

Synopsis

setSelectedEventCount( count )

Parameters

count Integer Event count.

Return Value

Undefined

Example

var context = this.getContext();
var search  = context.get("search");
search.setSelectedEventAvailableCount(totalEventsAvailable);
search.setSelectedEventCount(totalEvents);
var range = this.getSelectionRange(selectedBuckets);
search.setTimeRange(range);
context.set("search", search);
return context;

setTimeRange()

The setTimeRange() method sets the current search time range to the specified value.

Note: Providing a time range equivalent to the current time range causes the saved search name to be undefined.

Synopsis

this = setTimeRange( range )

Parameters

range Object Time range of type Splunk.TimeRange.

Return Value

Object Calling namespace.

Example

var context = this.getContext();
var search  = context.get("search");
var timeRange = new Splunk.TimeRange('-1d', 'now');
search.setTimeRange(timeRange);
context.set('search', search);
return context;

setViewStateId()

The setViewStateId() method sets the search object view state to the specified value.

Synopsis

setViewStateId( id )

Parameters

id String Desired search object view state.

Return Value

Undefined

Example

var context = this.getContext();
var search  = context.get("search");
search.setViewStateId(null);
context.set('search', search);
return context;

toString()

The toString() method gets the current search as a string, for textual representation of the search.

Synopsis

search = toString()

Return Value

String Current search, as either full search with intentions or base search.

Example

var context = this.getContext();var search  = context.get("search");
alert(escape(search.toString()));

Related answers from Splunk Community

Splunk.Search

abandonJob()

Synopsis

Return Value

Example

See Also

absorbIntentions()

Synopsis

Parameters

Return Value

Throws

Example

See Also

addIntention()

Synopsis

Parameters

Return Value

Throws

Example

See Also

clearIntentions()

Synopsis

Return Value

Example

See Also

clearTimeRange()

Synopsis

Return Value

Example

See Also

clone()

Synopsis

Return Value

Example

dispatchJob()

Synopsis

Parameters

Return Value

Example

See Also

equalToSearch()

Synopsis

Parameters

Return Value

Example

getBaseSearch()

Synopsis

Return Value

Example

See Also

getDistributedServerList()

Synopsis

Return Value

Example

See Also

getEventAvailableCount()

Synopsis

Return Value

Example

See Also

getEventCount()

Synopsis

Return Value

Example

See Also

getIntentionReference()

Synopsis

Parameters

Return Value

Example

See Also