Package com.yahoo.search
Class Query
java.lang.Object
com.yahoo.component.provider.FreezableClass
com.yahoo.processing.Request
com.yahoo.search.Query
- All Implemented Interfaces:
com.yahoo.component.provider.Freezable
,Cloneable
A search query containing all the information required to produce a Result.
The Query contains:
- the selection criterion received in the request - which may be a structured boolean tree of operators, an annotated piece of natural language text received from a user, or a combination of both
- a set of field containing the additional general parameters of a query - number of hits, ranking, presentation etc.
- a Map of properties, which can be of any object type
The properties has three sources
- They may be set in some Searcher component already executed for this Query - the properties acts as a blackboard for communicating arbitrary objects between Searcher components.
- Properties set in the search Request received - the properties acts as a way to parametrize Searcher components from the Request.
- Properties defined in the selected
QueryProfile
- this provides defaults for the parameters to Searcher components. Note that by using query profile types, the components may define the set of parameters they support.
The identity of a query is determined by its content.
- Author:
- Arne Bergene Fossaa, bratseth
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
static enum
The type of the query -
Field Summary
Modifier and TypeFieldDescriptionstatic final com.yahoo.processing.request.CompoundName
static final com.yahoo.processing.request.CompoundName
static final com.yahoo.processing.request.CompoundName
static final List<com.yahoo.processing.request.CompoundName>
Returns an unmodifiable list of all the native properties under a Querystatic final com.yahoo.processing.request.CompoundName
static final com.yahoo.processing.request.CompoundName
static final com.yahoo.processing.request.CompoundName
static final com.yahoo.processing.request.CompoundName
static final com.yahoo.processing.request.CompoundName
static final com.yahoo.processing.request.CompoundName
Fields inherited from class com.yahoo.processing.Request
CHAIN, JDISC_REQUEST
-
Constructor Summary
ConstructorDescriptionQuery()
Constructs an empty (null) queryQuery
(com.yahoo.container.jdisc.HttpRequest request) Creates a query from a requestQuery
(com.yahoo.container.jdisc.HttpRequest request, CompiledQueryProfile queryProfile) Creates a query from a requestQuery
(com.yahoo.container.jdisc.HttpRequest request, Map<String, String> requestMap, CompiledQueryProfile queryProfile) Creates a query from a requestConstruct a query from a string formatted in the http style, e.g?query=test&offset=10&hits=13
The query must be uri encoded.Query
(String query, CompiledQueryProfile queryProfile) Construct a query from a string formatted in the http style, e.g?query=test&offset=10&hits=13
The query must be uri encoded. -
Method Summary
Modifier and TypeMethodDescriptionstatic void
void
attachContext
(Query query) Set the context information for another query to be part of this query's context information.clone()
Returns a clone of this querystatic Query
createNewQuery
(Query query) Creates a new query from another query, but with time sensitive fields reset.int
encode
(ByteBuffer buffer) Encodes this query tree into the given bufferint
encodeAsProperties
(ByteBuffer buffer, boolean encodeQueryData) Deprecated.do not useboolean
Returns whether the given query is equal to thisstatic QueryProfileType
getContext
(boolean create) Returns the context of this query, possibly creating it if missing.long
Returns the time (in milliseconds) since the query was started/createdint
Returns the explain level of this query, 0 means no tracing Higher numbers means increasingly more explainingboolean
Returns whether this query should use the grouping session cache.int
getHits()
Returns the number of hits requested by the submitter of this query.com.yahoo.container.jdisc.HttpRequest
Return the HTTP request which caused this query.getModel()
Returns the query representation model to be used for this query, never nullboolean
Returns whether this query should never be served from a cache.int
Returns the offset from the most relevant hits requested by the submitter of this query.Returns the presentation to be used for this query, never nullReturns the ranking to be used for this query, never nullReturns the select to be used for this query, never nullReturns the session id of this query, or null if none is assignedgetSessionId
(String serverId) Returns the session id of this query, and creates and assigns it if not already presentlong
Returns the time (in milliseconds since epoch) when this query was startedlong
Get the appropriate timeout for the query.long
Returns the number of milliseconds to wait for a response from a search backend before timing it out.int
Returns the context level of this query, 0 means no tracing Higher numbers means increasingly more tracingboolean
Deprecated.int
hashCode()
Returns a hash of this query based on (some of) its content.final boolean
isTraceable
(int level) Returns the context level of this query, 0 means no tracing Higher numbers means increasingly more tracingvoid
prepare()
Prepares this for binary serialization.Returns the properties of this query.void
Resets the start time of the query.void
setExplainLevel
(int explainLevel) Sets the explain level of this query, 0 means no tracing Higher numbers means increasingly more explainingvoid
setGroupingSessionCache
(boolean groupingSessionCache) Sets whether this query should use the grouping session cache.void
setHits
(int hits) Sets the number of hits requested.void
setNoCache
(boolean noCache) Sets whether this query should never be server from a cache.void
setOffset
(int offset) Set the hit offset.void
setTimeout
(long timeout) Sets the number of milliseconds to wait for a response from a search backend before time out.void
setTimeout
(String timeoutString) Sets timeout from a string which will be parsed as avoid
setTraceLevel
(int traceLevel) Sets the context level of this query, 0 means no tracing Higher numbers means increasingly more tracingvoid
setWindow
(int offset, int hits) Convenience method to set both the offset and the number of hits to returnReturns a string describing this query in more detailtoString()
Returns a string describing this queryvoid
Adds a trace message to this query if the trace level of the query is sufficiently high.void
void
Adds a trace message to this query if the trace level of the query is sufficiently high.void
Adds a context message to this query and to the info log, if the context level of the query is sufficiently high.validate()
Validates this querySerialize this query as YQL+.yqlRepresentation
(boolean includeHitsAndOffset) Serialize this query as YQL+.yqlRepresentation
(com.yahoo.collections.Tuple2<String, com.yahoo.component.Version> segmenterVersion, boolean includeHitsAndOffset) Deprecated.remove the ignored segmenterVersion argument from invocationsMethods inherited from class com.yahoo.processing.Request
errors
Methods inherited from class com.yahoo.component.provider.FreezableClass
ensureNotFrozen, freeze, isFrozen
-
Field Details
-
OFFSET
public static final com.yahoo.processing.request.CompoundName OFFSET -
HITS
public static final com.yahoo.processing.request.CompoundName HITS -
QUERY_PROFILE
public static final com.yahoo.processing.request.CompoundName QUERY_PROFILE -
SEARCH_CHAIN
public static final com.yahoo.processing.request.CompoundName SEARCH_CHAIN -
TRACE_LEVEL
public static final com.yahoo.processing.request.CompoundName TRACE_LEVEL -
EXPLAIN_LEVEL
public static final com.yahoo.processing.request.CompoundName EXPLAIN_LEVEL -
NO_CACHE
public static final com.yahoo.processing.request.CompoundName NO_CACHE -
GROUPING_SESSION_CACHE
public static final com.yahoo.processing.request.CompoundName GROUPING_SESSION_CACHE -
TIMEOUT
public static final com.yahoo.processing.request.CompoundName TIMEOUT -
nativeProperties
Returns an unmodifiable list of all the native properties under a Query
-
-
Constructor Details
-
Query
public Query()Constructs an empty (null) query -
Query
Construct a query from a string formatted in the http style, e.g?query=test&offset=10&hits=13
The query must be uri encoded. -
Query
public Query(com.yahoo.container.jdisc.HttpRequest request) Creates a query from a request- Parameters:
request
- the HTTP request from which this is created
-
Query
Construct a query from a string formatted in the http style, e.g?query=test&offset=10&hits=13
The query must be uri encoded. -
Query
Creates a query from a request- Parameters:
request
- the HTTP request from which this is createdqueryProfile
- the query profile to use for this query, or null if none
-
Query
public Query(com.yahoo.container.jdisc.HttpRequest request, Map<String, String> requestMap, CompiledQueryProfile queryProfile) Creates a query from a request- Parameters:
request
- the HTTP request from which this is createdrequestMap
- the property map of the queryqueryProfile
- the query profile to use for this query, or null if none
-
Query
-
-
Method Details
-
getArgumentType
-
addNativeQueryProfileTypesTo
-
createNewQuery
Creates a new query from another query, but with time sensitive fields reset. -
properties
Returns the properties of this query. The properties are modifiable- Overrides:
properties
in classcom.yahoo.processing.Request
-
validate
Validates this query- Returns:
- the reason if it is invalid, null if it is valid
-
getStartTime
public long getStartTime()Returns the time (in milliseconds since epoch) when this query was started -
getDurationTime
public long getDurationTime()Returns the time (in milliseconds) since the query was started/created -
getTimeLeft
public long getTimeLeft()Get the appropriate timeout for the query.- Returns:
- timeout in milliseconds
-
getTimeout
public long getTimeout()Returns the number of milliseconds to wait for a response from a search backend before timing it out. Default is 500.Note: If Ranking.RANKFEATURES is turned on, this is hardcoded to 6 minutes.
- Returns:
- timeout in milliseconds.
-
setTimeout
public void setTimeout(long timeout) Sets the number of milliseconds to wait for a response from a search backend before time out. Default is 500 ms. -
setTimeout
Sets timeout from a string which will be parsed as a -
resetTimeout
public void resetTimeout()Resets the start time of the query. This will ensure that the query will run for the same amount of time as a newly created query. -
setTraceLevel
public void setTraceLevel(int traceLevel) Sets the context level of this query, 0 means no tracing Higher numbers means increasingly more tracing -
setExplainLevel
public void setExplainLevel(int explainLevel) Sets the explain level of this query, 0 means no tracing Higher numbers means increasingly more explaining -
getTraceLevel
public int getTraceLevel()Returns the context level of this query, 0 means no tracing Higher numbers means increasingly more tracing -
getExplainLevel
public int getExplainLevel()Returns the explain level of this query, 0 means no tracing Higher numbers means increasingly more explaining -
isTraceable
public final boolean isTraceable(int level) Returns the context level of this query, 0 means no tracing Higher numbers means increasingly more tracing -
getNoCache
public boolean getNoCache()Returns whether this query should never be served from a cache. Default is false -
setNoCache
public void setNoCache(boolean noCache) Sets whether this query should never be server from a cache. Default is false -
getGroupingSessionCache
public boolean getGroupingSessionCache()Returns whether this query should use the grouping session cache. Default is false -
setGroupingSessionCache
public void setGroupingSessionCache(boolean groupingSessionCache) Sets whether this query should use the grouping session cache. Default is false -
getOffset
public int getOffset()Returns the offset from the most relevant hits requested by the submitter of this query. Default is 0 - to return the most relevant hits -
getHits
public int getHits()Returns the number of hits requested by the submitter of this query. The default is 10. -
setHits
public void setHits(int hits) Sets the number of hits requested. If hits is less than 0, an IllegalArgumentException is thrown. Default number of hits is 10. -
setOffset
public void setOffset(int offset) Set the hit offset. Can not be less than 0. Default is 0. -
setWindow
public void setWindow(int offset, int hits) Convenience method to set both the offset and the number of hits to return -
toString
Returns a string describing this query -
toDetailString
Returns a string describing this query in more detail -
encode
Encodes this query tree into the given buffer- Parameters:
buffer
- the buffer to encode the query to- Returns:
- the number of encoded query tree items
-
trace
Adds a context message to this query and to the info log, if the context level of the query is sufficiently high. The context information will be carried over to the result at creation. The message parameter will be included with XML escaping.- Parameters:
message
- the message to addtraceLevel
- the context level of the message, this method will do nothing if the traceLevel of the query is lower than this value
-
trace
-
trace
Adds a trace message to this query if the trace level of the query is sufficiently high.- Parameters:
message
- the message to addincludeQuery
- true to append the query root stringValue at the end of the messagetraceLevel
- the context level of the message, this method will do nothing if the traceLevel of the query is lower than this value
-
trace
Adds a trace message to this query if the trace level of the query is sufficiently high.- Parameters:
includeQuery
- true to append the query root stringValue at the end of the messagetraceLevel
- the context level of the message, this method will do nothing if the traceLevel of the query is lower than this valuemessages
- the messages whose toStrings will be concatenated into the trace message. Concatenation will only happen if the trace level is sufficiently high.
-
attachContext
Set the context information for another query to be part of this query's context information. This is to be used if creating fresh query objects as part of a plug-in's execution. The query should be attached before it is used, in case an exception causes premature termination. This is enforced by an IllegalStateException. In other words, intended use is create the new query, and attach the context to the invoking query as soon as the new query is properly initialized.This method will always set the argument query's context level to the context level of this query.
- Parameters:
query
- The query which should be traced as a part of this query.- Throws:
IllegalStateException
- If the query given as argument already has context information.
-
yqlRepresentation
Serialize this query as YQL+. This method will never throw exceptions, but instead return a human readable error message if a problem occurred while serializing the query. Hits and offset information will be included if different from default, while linguistics metadata are not added.- Returns:
- a valid YQL+ query string or a human readable error message
- See Also:
-
yqlRepresentation
@Deprecated public String yqlRepresentation(com.yahoo.collections.Tuple2<String, com.yahoo.component.Version> segmenterVersion, boolean includeHitsAndOffset) Deprecated.remove the ignored segmenterVersion argument from invocations -
yqlRepresentation
Serialize this query as YQL+. This will create a string representation which should always be legal YQL+. If a problem occurs, a RuntimeException is thrown.- Parameters:
includeHitsAndOffset
- whether to include hits and offset parameters converted to a offset/limit slice- Returns:
- a valid YQL+ query string
- Throws:
RuntimeException
- if there is a problem serializing the query tree
-
getContext
Returns the context of this query, possibly creating it if missing. Returns the context, or null -
hashCode
public int hashCode()Returns a hash of this query based on (some of) its content. -
equals
Returns whether the given query is equal to this -
clone
Returns a clone of this query- Overrides:
clone
in classcom.yahoo.processing.Request
-
getPresentation
Returns the presentation to be used for this query, never null -
getSelect
Returns the select to be used for this query, never null -
getRanking
Returns the ranking to be used for this query, never null -
getModel
Returns the query representation model to be used for this query, never null -
getHttpRequest
public com.yahoo.container.jdisc.HttpRequest getHttpRequest()Return the HTTP request which caused this query. This will never be null when running with queries from the network. -
getSessionId
Returns the session id of this query, or null if none is assigned -
getSessionId
Returns the session id of this query, and creates and assigns it if not already present -
hasEncodableProperties
Deprecated. -
encodeAsProperties
Deprecated.do not useEncodes properties of this query.- Parameters:
buffer
- the buffer to encode toencodeQueryData
- true to encode all properties, false to only include session information, not actual query data- Returns:
- the encoded length
-
prepare
public void prepare()Prepares this for binary serialization. This must be invoked after all changes have been made to this query before it is passed on to a receiving backend. Calling it is somewhat expensive, so it should only happen once. If a prepared query is cloned, it stays prepared.
-