Package org.opensearch.action.search

Class SearchRequest

java.lang.Object
org.opensearch.core.transport.TransportMessage
org.opensearch.transport.TransportRequest
org.opensearch.action.ActionRequest
org.opensearch.action.search.SearchRequest
All Implemented Interfaces:
IndicesRequest, IndicesRequest.Replaceable, org.opensearch.core.common.io.stream.Writeable, TaskAwareRequest
Direct Known Subclasses:
PipelinedRequest
@PublicApi(since="1.0.0") public class SearchRequest extends ActionRequest implements IndicesRequest.Replaceable
A request to execute search against one or more indices (or all). Best created using Requests.searchRequest(String...).

Note, the search source(org.opensearch.search.builder.SearchSourceBuilder) is required. The search source is the different search options, including aggregations and such.

See Also:
Opensearch.api:

  • Field Details

    • FORMAT_PARAMS

      public static final org.opensearch.core.xcontent.ToXContent.Params FORMAT_PARAMS

    • DEFAULT_PRE_FILTER_SHARD_SIZE

      public static final int DEFAULT_PRE_FILTER_SHARD_SIZE
      See Also:

    • DEFAULT_BATCHED_REDUCE_SIZE

      public static final int DEFAULT_BATCHED_REDUCE_SIZE
      See Also:

    • DEFAULT_INDICES_OPTIONS

      public static final IndicesOptions DEFAULT_INDICES_OPTIONS

  • Constructor Details

    • SearchRequest

      public SearchRequest()

    • SearchRequest

      public SearchRequest(SearchRequest searchRequest)
      Constructs a new search request from the provided search request

    • SearchRequest

      public SearchRequest(String... indices)
      Constructs a new search request against the indices. No indices provided here means that search will run against all indices.

    • SearchRequest

      public SearchRequest(String[] indices, SearchSourceBuilder source)
      Constructs a new search request against the provided indices with the given search source.

    • SearchRequest

      public SearchRequest(org.opensearch.core.common.io.stream.StreamInput in) throws IOException
      Constructs a new search request from reading the specified stream.
      Parameters:
      in - The stream the request is read from
      Throws:
      IOException - if there is an issue reading the stream

  • Method Details

    • writeTo

      public void writeTo(org.opensearch.core.common.io.stream.StreamOutput out) throws IOException
      Specified by:
      writeTo in interface org.opensearch.core.common.io.stream.Writeable
      Overrides:
      writeTo in class ActionRequest
      Throws:
      IOException

    • validate

      public ActionRequestValidationException validate()
      Specified by:
      validate in class ActionRequest

    • getOrCreateAbsoluteStartMillis

      public long getOrCreateAbsoluteStartMillis()
      Returns the current time in milliseconds from the time epoch, to be used for the execution of this search request. Used to ensure that the same value, determined by the coordinating node, is used on all nodes involved in the execution of the search request. When created through subSearchRequest(SearchRequest, String[], String, long, boolean), this method returns the provided current time, otherwise it will return System.currentTimeMillis().

    • indices

      public SearchRequest indices(String... indices)
      Sets the indices the search will be executed on.
      Specified by:
      indices in interface IndicesRequest.Replaceable

    • indicesOptions

      public IndicesOptions indicesOptions()
      Description copied from interface: IndicesRequest
      Returns the indices options used to resolve indices. They tell for instance whether a single index is accepted, whether an empty array will be converted to _all, and how wildcards will be expanded if needed.
      Specified by:
      indicesOptions in interface IndicesRequest

    • indicesOptions

      public SearchRequest indicesOptions(IndicesOptions indicesOptions)

    • includeDataStreams

      public boolean includeDataStreams()
      Description copied from interface: IndicesRequest
      Determines whether the request should be applied to data streams. When false, none of the names or wildcard expressions in IndicesRequest.indices() should be applied to or expanded to any data streams. All layers involved in the request's fulfillment including security, name resolution, etc., should respect this flag.
      Specified by:
      includeDataStreams in interface IndicesRequest

    • isCcsMinimizeRoundtrips

      public boolean isCcsMinimizeRoundtrips()
      Returns whether network round-trips should be minimized when executing cross-cluster search requests. Defaults to true.

    • setCcsMinimizeRoundtrips

      public void setCcsMinimizeRoundtrips(boolean ccsMinimizeRoundtrips)
      Sets whether network round-trips should be minimized when executing cross-cluster search requests. Defaults to true.

    • routing

      public String routing()
      A comma separated list of routing values to control the shards the search will be executed on.

    • routing

      public SearchRequest routing(String routing)
      A comma separated list of routing values to control the shards the search will be executed on.

    • routing

      public SearchRequest routing(String... routings)
      The routing values to control the shards that the search will be executed on.

    • preference

      public SearchRequest preference(String preference)
      Sets the preference to execute the search. Defaults to randomize across shards. Can be set to _local to prefer local shards, _primary to execute only on primary shards, or a custom value, which guarantees that the same order will be used across different requests.

    • preference

      public String preference()

    • searchType

      public SearchRequest searchType(SearchType searchType)
      The search type to execute, defaults to SearchType.DEFAULT.

    • searchType

      public SearchRequest searchType(String searchType)
      The a string representation search type to execute, defaults to SearchType.DEFAULT. Can be one of "dfs_query_then_fetch"/"dfsQueryThenFetch", "dfs_query_and_fetch"/"dfsQueryAndFetch", "query_then_fetch"/"queryThenFetch", and "query_and_fetch"/"queryAndFetch".

    • source

      public SearchRequest source(SearchSourceBuilder sourceBuilder)
      The source of the search request.

    • source

      public SearchSourceBuilder source()
      The search source to execute.

    • pointInTimeBuilder

      public PointInTimeBuilder pointInTimeBuilder()

    • searchType

      public SearchType searchType()
      The type of search to execute.

    • indices

      public String[] indices()
      The indices
      Specified by:
      indices in interface IndicesRequest

    • scroll

      public Scroll scroll()
      If set, will enable scrolling of the search request.

    • scroll

      public SearchRequest scroll(Scroll scroll)
      If set, will enable scrolling of the search request.

    • scroll

      public SearchRequest scroll(org.opensearch.common.unit.TimeValue keepAlive)
      If set, will enable scrolling of the search request for the specified timeout.

    • scroll

      public SearchRequest scroll(String keepAlive)
      If set, will enable scrolling of the search request for the specified timeout.

    • requestCache

      public SearchRequest requestCache(Boolean requestCache)
      Sets if this request should use the request cache or not, assuming that it can (for example, if "now" is used, it will never be cached). By default (not set, or null, will default to the index level setting if request cache is enabled or not).

    • requestCache

      public Boolean requestCache()

    • allowPartialSearchResults

      public SearchRequest allowPartialSearchResults(boolean allowPartialSearchResults)
      Sets if this request should allow partial results. (If method is not called, will default to the cluster level setting).

    • allowPartialSearchResults

      public Boolean allowPartialSearchResults()

    • setBatchedReduceSize

      public void setBatchedReduceSize(int batchedReduceSize)
      Sets the number of shard results that should be reduced at once on the coordinating node. This value should be used as a protection mechanism to reduce the memory overhead per search request if the potential number of shards in the request can be large.

    • getBatchedReduceSize

      public int getBatchedReduceSize()
      Returns the number of shard results that should be reduced at once on the coordinating node. This value should be used as a protection mechanism to reduce the memory overhead per search request if the potential number of shards in the request can be large.

    • getMaxConcurrentShardRequests

      public int getMaxConcurrentShardRequests()
      Returns the number of shard requests that should be executed concurrently on a single node. This value should be used as a protection mechanism to reduce the number of shard requests fired per high level search request. Searches that hit the entire cluster can be throttled with this number to reduce the cluster load. The default is 5

    • setMaxConcurrentShardRequests

      public void setMaxConcurrentShardRequests(int maxConcurrentShardRequests)
      Sets the number of shard requests that should be executed concurrently on a single node. This value should be used as a protection mechanism to reduce the number of shard requests fired per high level search request. Searches that hit the entire cluster can be throttled with this number to reduce the cluster load. The default is 5

    • setPreFilterShardSize

      public void setPreFilterShardSize(int preFilterShardSize)
      Sets a threshold that enforces a pre-filter roundtrip to pre-filter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method ie. if date filters are mandatory to match but the shard bounds and the query are disjoint.

      When unspecified, the pre-filter phase is executed if any of these conditions is met:

      • The request targets more than 128 shards
      • The request targets one or more read-only index
      • The primary sort of the query targets an indexed field

    • isPhaseTook

      public Boolean isPhaseTook()
      Returns value of user-provided phase_took query parameter for this search request.

    • setPhaseTook

      public void setPhaseTook(Boolean phaseTook)
      Sets value of phase_took query param if provided by user. Defaults to null.

    • getPreFilterShardSize

      @Nullable public Integer getPreFilterShardSize()
      Returns a threshold that enforces a pre-filter roundtrip to pre-filter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold, or null if the threshold is unspecified. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method ie. if date filters are mandatory to match but the shard bounds and the query are disjoint.

      When unspecified, the pre-filter phase is executed if any of these conditions is met:

      • The request targets more than 128 shards
      • The request targets one or more read-only index
      • The primary sort of the query targets an indexed field

    • isSuggestOnly

      public boolean isSuggestOnly()
      Returns:
      true if the request only has suggest

    • resolveTrackTotalHitsUpTo

      public int resolveTrackTotalHitsUpTo()

    • resolveTrackTotalHitsUpTo

      public static int resolveTrackTotalHitsUpTo(Scroll scroll, SearchSourceBuilder source)

    • setCancelAfterTimeInterval

      public void setCancelAfterTimeInterval(org.opensearch.common.unit.TimeValue cancelAfterTimeInterval)

    • getCancelAfterTimeInterval

      public org.opensearch.common.unit.TimeValue getCancelAfterTimeInterval()

    • pipeline

      public SearchRequest pipeline(String pipeline)

    • pipeline

      public String pipeline()

    • createTask

      public SearchTask createTask(long id, String type, String action, org.opensearch.core.tasks.TaskId parentTaskId, Map<String,String> headers)
      Description copied from interface: TaskAwareRequest
      Returns the task object that should be used to keep track of the processing of the request.
      Specified by:
      createTask in interface TaskAwareRequest

    • buildDescription

      public final String buildDescription()

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object