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
public class Query extends com.yahoo.processing.Request implements 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 have three sources

  1. 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.
  2. Properties set in the search Request received - the properties acts as a way to parametrize Searcher components from the Request.
  3. 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.
When looked up, the properties are accessed in the priority order listed above.

The identity of a query is determined by its content.

Author:
Arne Bergene Fossaa, bratseth

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Query.Builder
     
    static enum 
    Query.Type
    The type of the query

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final com.yahoo.processing.request.CompoundName
    EXPLAIN_LEVEL
    Deprecated.
    use Trace.EXPLAIN_LEVEL
    static final com.yahoo.processing.request.CompoundName
    GROUPING_SESSION_CACHE
     
    static final com.yahoo.processing.request.CompoundName
    HITS
     
    static final List<com.yahoo.processing.request.CompoundName>
    nativeProperties
    Returns an unmodifiable list of all the native properties under a Query
    static final com.yahoo.processing.request.CompoundName
    NO_CACHE
     
    static final com.yahoo.processing.request.CompoundName
    OFFSET
     
    static final com.yahoo.processing.request.CompoundName
    QUERY_PROFILE
     
    static final com.yahoo.processing.request.CompoundName
    SEARCH_CHAIN
     
    static final com.yahoo.processing.request.CompoundName
    TIMEOUT
     
    Trace
    trace
    How this query should be traced
    static final com.yahoo.processing.request.CompoundName
    TRACE_LEVEL
    Deprecated.
    use Trace.LEVEL

    Fields inherited from class com.yahoo.processing.Request

    CHAIN, JDISC_REQUEST

  • Constructor Summary

    Constructors
    Constructor
    Description
    Query()
    Constructs an empty (null) query
    Query(com.yahoo.container.jdisc.HttpRequest request)
    Creates a query from a request
    Query(com.yahoo.container.jdisc.HttpRequest request, CompiledQueryProfile queryProfile)
    Creates a query from a request
    Query(com.yahoo.container.jdisc.HttpRequest request, Map<String,String> requestMap, CompiledQueryProfile queryProfile)
    Creates a query from a request
    Query(Query query)
     
    Query(String 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(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 Type
    Method
    Description
    static void
    addNativeQueryProfileTypesTo(QueryProfileTypeRegistry registry)
     
    void
    attachContext(Query query)
    Set the context information for another query to be part of this query's context information.
    Query
    clone()
    Returns a clone of this query
    static 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 buffer
    boolean
    equals(Object other)
    Returns whether the given query is equal to this
    static QueryProfileType
    getArgumentType()
     
    QueryContext
    getContext(boolean create)
    Returns the context of this query, possibly creating it if missing.
    long
    getDurationTime()
    Returns the time (in milliseconds) since the query was started/created
    int
    getExplainLevel()
    Deprecated.
    use getTrace().getExplainLevel(level)
    boolean
    getGroupingSessionCache()
    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
    getHttpRequest()
    Return the HTTP request which caused this query.
    Model
    getModel()
    Returns the query representation model to be used for this query, never null
    boolean
    getNoCache()
    Returns whether this query should never be served from a cache.
    int
    getOffset()
    Returns the offset from the most relevant hits requested by the submitter of this query.
    Presentation
    getPresentation()
    Returns the presentation to be used for this query, never null
    Ranking
    getRanking()
    Returns the ranking to be used for this query, never null
    Select
    getSelect()
    Returns the select to be used for this query, never null
    SessionId
    getSessionId()
    Returns the session id of this query, or null if none is assigned
    SessionId
    getSessionId(String serverId)
    Returns the session id of this query, and creates and assigns it if not already present
    long
    getStartTime()
    Returns the time (in milliseconds since epoch) when this query was started
    long
    getTimeLeft()
    Get the appropriate timeout for the query.
    long
    getTimeout()
    Returns the number of milliseconds to wait for a response from a search backend before timing it out.
    Trace
    getTrace()
    Returns the trace settings and facade API.
    int
    getTraceLevel()
    Deprecated.
    use getTrace().setLevel(level)
    URI
    getUri()
     
    int
    hashCode()
    Returns a hash of this query based on (some of) its content.
    final boolean
    isTraceable(int level)
    Deprecated.
    use getTrace().isTraceable(level)
    void
    prepare()
    Prepares this for binary serialization.
    Properties
    properties()
    Returns the properties of this query.
    void
    resetTimeout()
    Resets the start time of the query.
    void
    setExplainLevel(int explainLevel)
    Deprecated.
    use getTrace().setExplainLevel(level)
    void
    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 a
    void
    setTraceLevel(int traceLevel)
    Deprecated.
    use getTrace().setLevel(level)
    void
    setWindow(int offset, int hits)
    Convenience method to set both the offset and the number of hits to return
    String
    toDetailString()
    Returns a string describing this query in more detail
    String
    toString()
    Returns a string describing this query
    void
    trace(boolean includeQuery, int traceLevel, Object... messages)
    Calls getTrace().trace(message, traceLevel, messages).
    void
    trace(Object message, int traceLevel)
    Calls getTrace().trace(message, traceLevel).
    void
    trace(String message, boolean includeQuery, int traceLevel)
    Calls getTrace().trace(message, includeQuery, traceLevel).
    void
    trace(String message, int traceLevel)
    Calls getTrace().trace(message, traceLevel).
    String
    validate()
    Validates this query
    String
    yqlRepresentation()
    Serialize this query as YQL+.
    String
    yqlRepresentation(boolean includeHitsAndOffset)
    Serialize this query as YQL+.

    Methods inherited from class com.yahoo.processing.Request

    errors

    Methods inherited from class com.yahoo.component.provider.FreezableClass

    ensureNotFrozen, freeze, isFrozen

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • trace

      public Trace trace
      How this query should be traced

    • 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

    • 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

    • TRACE_LEVEL

      @Deprecated public static final com.yahoo.processing.request.CompoundName TRACE_LEVEL
      Deprecated.
      use Trace.LEVEL

    • EXPLAIN_LEVEL

      @Deprecated public static final com.yahoo.processing.request.CompoundName EXPLAIN_LEVEL
      Deprecated.
      use Trace.EXPLAIN_LEVEL

    • nativeProperties

      public static final List<com.yahoo.processing.request.CompoundName> nativeProperties
      Returns an unmodifiable list of all the native properties under a Query

  • Constructor Details

    • Query

      public Query()
      Constructs an empty (null) query

    • Query

      public Query(String 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

      public 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.

    • Query

      public Query(com.yahoo.container.jdisc.HttpRequest request, CompiledQueryProfile queryProfile)
      Creates a query from a request
      Parameters:
      request - the HTTP request from which this is created
      queryProfile - 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 created
      requestMap - the property map of the query
      queryProfile - the query profile to use for this query, or null if none

    • Query

      public Query(Query query)

  • Method Details

    • getArgumentType

      public static QueryProfileType getArgumentType()

    • addNativeQueryProfileTypesTo

      public static void addNativeQueryProfileTypesTo(QueryProfileTypeRegistry registry)

    • createNewQuery

      public static Query createNewQuery(Query query)
      Creates a new query from another query, but with time sensitive fields reset.

    • properties

      public Properties properties()
      Returns the properties of this query. The properties are modifiable
      Overrides:
      properties in class com.yahoo.processing.Request

    • validate

      public String 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

      public void setTimeout(String timeoutString)
      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

      @Deprecated public void setTraceLevel(int traceLevel)
      Deprecated.
      use getTrace().setLevel(level)

    • setExplainLevel

      @Deprecated public void setExplainLevel(int explainLevel)
      Deprecated.
      use getTrace().setExplainLevel(level)

    • getTraceLevel

      @Deprecated public int getTraceLevel()
      Deprecated.
      use getTrace().setLevel(level)

    • getExplainLevel

      @Deprecated public int getExplainLevel()
      Deprecated.
      use getTrace().getExplainLevel(level)

    • isTraceable

      @Deprecated public final boolean isTraceable(int level)
      Deprecated.
      use getTrace().isTraceable(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

      public String toString()
      Returns a string describing this query
      Overrides:
      toString in class Object

    • toDetailString

      public String toDetailString()
      Returns a string describing this query in more detail

    • encode

      public int encode(ByteBuffer buffer)
      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

      public void trace(String message, int traceLevel)
      Calls getTrace().trace(message, traceLevel).

    • trace

      public void trace(Object message, int traceLevel)
      Calls getTrace().trace(message, traceLevel).

    • trace

      public void trace(String message, boolean includeQuery, int traceLevel)
      Calls getTrace().trace(message, includeQuery, traceLevel).

    • trace

      public void trace(boolean includeQuery, int traceLevel, Object... messages)
      Calls getTrace().trace(message, traceLevel, messages).

    • attachContext

      public void attachContext(Query query) throws IllegalStateException
      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

      public String 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

      public String yqlRepresentation(boolean includeHitsAndOffset)
      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

      public QueryContext getContext(boolean create)
      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.
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object other)
      Returns whether the given query is equal to this
      Overrides:
      equals in class Object

    • clone

      public Query clone()
      Returns a clone of this query
      Overrides:
      clone in class com.yahoo.processing.Request

    • getPresentation

      public Presentation getPresentation()
      Returns the presentation to be used for this query, never null

    • getSelect

      public Select getSelect()
      Returns the select to be used for this query, never null

    • getRanking

      public Ranking getRanking()
      Returns the ranking to be used for this query, never null

    • getModel

      public Model getModel()
      Returns the query representation model to be used for this query, never null

    • getTrace

      public Trace getTrace()
      Returns the trace settings and facade API.

    • 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.

    • getUri

      public URI getUri()

    • getSessionId

      public SessionId getSessionId()
      Returns the session id of this query, or null if none is assigned

    • getSessionId

      public SessionId getSessionId(String serverId)
      Returns the session id of this query, and creates and assigns it if not already present

    • 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.