How to display search results using the Splunk SDK for Java

After you run a search, you can retrieve different output from the search job:

Events: The untransformed events of the search.

Results: The transformed results of the search after processing has been completed. If the search does not have transforming commands, the results are the same as the events. The result count will be less than the event count if there are transforming commands.

Results preview: A preview of a search that is still in progress, or results from a real-time search. When the search is complete, the preview results are the same as the results. You must enable previews for non-real-time searches (previews are enabled automatically for real-time searches).

Summary: Summary information about the fields of a search from the results that have been read thus far. Set "status_buckets" on the search job to a positive value to access this data.

Timeline: The event distribution over time of the untransformed events that have been read thus far. Set "status_buckets" on the search job to a positive value to access this data.

You can display the direct results using standard Java classes or make your own parser. But for convenience, the SDK includes results readers for XML, CSV, and JSON that properly parse and format the results for you, and handle the idiosyncrasies of each output type for each Splunk Enterprise version. For a comparison of XML output displayed using standard Java classes versus the SDK's XML results reader, see Results reader comparison, below.

The search results APIs

Retrieve a search job using the Job class (or for streaming searches, retrieve the stream using the InputStream class). From the search job, you can retrieve events, results, preview results, the summary, and timeline information:

The Job.getEvents method retrieves events from a search job. Use the JobEventsArgs class to specify additional arguments to the method.

The Job.getResults method retrieves results from a search job. Use the JobResultsArgs class to specify additional arguments to the method.

The Job.getResultsPreview method retrieves result previews from a search job. Use the JobResultsPreviewArgs class to specify additional arguments to the method.

The Job.getSummary method retrieves summary data from a search job. Use the JobSummaryArgs class to specify additional arguments to the method.

The Job.getTimeline method retrieves timeline data from a search job.

Use the following classes to display results with the results readers. For results from an export search, use the multi-results reader to parse the multiple results sets that are returned.

The ResultsReader class is the base class for the typed results readers.

ResultsReader or MultiResultsReader?

You should only use a MultiResultsReader if you're running an export search and you want to retrieve preview results. The rest of the time, you should use a ResultsReader. Read on for the benefits of each reader type.

Use a ResultsReader...

With normal, blocking, oneshot, and real-time search results.

When you don't need to access preview events. (This reader skips them, unless the search is run in normal mode with previews enabled. For more information, see To display preview results.)

When working with search jobs (versus searches that return a stream).

When you want to return results in comma-separated values (CSV) format. (Both readers support JSON and XML formats.)

Use a MultiResultsReader...

With export search results. (ResultsReader will also work with export search results, but will not allow you to access preview events.)

When you need to access preview events. (The exception is when running a normal mode search with previews enabled. In this situation, you can use the ResultsReader. For more information, see To display preview results.)

When working with searches that result in a stream, not a search job.

With searches with a very large data set.

To paginate through a large set of results

The maximum number of results you can retrieve at a time from your search results is determined by the maxresultrows field, which is specified in a Splunk Enterprise configuration file. Here's a quick way to find out what your system setting is:

// Find out how many results your system is configured to return
Entity restApi = service.getConfs().get("limits").get("restapi");int maxResults =Integer.parseInt((String)restApi.get("maxresultrows"));System.out.println("Your system is configured to return a maximum of "+ maxResults +" results");

However, we don't recommend changing the default value of 50,000. If your job has more results than this limit, you can retrieve your results in sets (0-49999, then 50000-99999, and so on), using the "count" and "offset" parameters to define how many results to retrieve at a time:

Set the count to a value up to the size of maxresultrows to define the number of results in a set.

Retrieve this set of results.

Increment the offset by the count to retrieve the next set.

Repeat until you've retrieved all of your results.

The example below shows how to retrieve 100 search results in sets of 10, and uses the ResultsReaderXml class to parse and format the results.

To display preview results

You can display a preview of the results of a search that is in progress as long as a couple conditions are met:

The search must be run in normal execution mode ("exec_mode" is "normal"). Previews aren't available for blocking searches (the search job ID is not available until the search is done) or streaming searches (results are returned as they become available anyway.)

Previews must be enabled ("preview" is "1"). By default, previews are only enabled for real-time searches, and searches with "status_buckets" set to a positive value. Use the Job.enablePreview method to enable previews for an existing search job.

To display the previews, run the search, enable previews for the search job, then retrieve the preview results from it. By default, the most recent 100 previews are retrieved. To change this number, set a value for "count". Use the "offset" value to page through large sets of previews.

The following example runs a normal search, enables preview for the search job, and then displays preview results while the search runs. For an example of a real-time search, see To run a real-time search.

To work with results from an export search

Working with search results from export searches is a little different than that of regular searches:

A reporting (transforming) search returns a set of previews followed by the final events, each as separate elements.

A non-reporting (non-transforming) search returns events as they are read from the index, each as separate elements.

A real-time search returns multiple sets of previews, each preview as a separate element.

For JSON output, each result set is not returned as a single JSON object, but rather each row is an individual object, where rows are separated by a new line and the last row of the set is indicated by "lastrow":true.

Here's sample JSON output that shows two results sets, each with five rows:

This format allows results to be sent as a continuous stream of JSON data that is still easy to parse.

So, we recommend using the SDK's multi-results readers to parse the output—we've already done some of the heavy lifting here, and these results readers handle the output appropriately. Display the results stream in XML or JSON, and use one of the MultiResultsReader classes to parse and format the results.

This example below shows how to display a real-time export search with XML output, using a 30-second time range:

This next example shows how to display previews from a normal export search. This search is useful when you are performing a reporting (transforming) search on a large data set and you want to view previews while the search runs.

A time string that specifies the earliest time in the time range to search. The time string can be a UTC time (with fractional seconds), a relative time specifier (to now), or a formatted time string. For a real-time search, specify "rt".

events

f

A string that contains the field to return for the event set.

events, results, results preview

field_list

A string that contains a comma-separated list of fields to return for the event set.

events, results, results preview

latest_time

A time string that specifies the earliest time in the time range to search. The time string can be a UTC time (with fractional seconds), a relative time specifier (to now), or a formatted time string. For a real-time search, specify "rt".

events

max_lines

The maximum number of lines that any single event's "_raw" field should contain.

events

offset

A number of the index of the first result (inclusive) from which to begin returning data. This value is 0-indexed.

More about search

We use our own and third-party cookies to provide you with a great online experience. We also use these cookies to improve our products and services, support our marketing campaigns, and advertise to you on our website and other websites. Some cookies may continue to collect information after you have left our website.
Learn more (including how to update your settings) here »