Class Query

  • All Implemented Interfaces:
    com.yahoo.component.provider.Freezable, java.lang.Cloneable

    public class Query
    extends com.yahoo.processing.Request
    implements java.lang.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

    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.Type
      The type of the query
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static com.yahoo.processing.request.CompoundName EXPLAIN_LEVEL  
      static com.yahoo.processing.request.CompoundName GROUPING_SESSION_CACHE  
      static com.yahoo.processing.request.CompoundName HITS  
      static java.util.List<com.yahoo.processing.request.CompoundName> nativeProperties
      Returns an unmodifiable list of all the native properties under a Query
      static com.yahoo.processing.request.CompoundName NO_CACHE  
      static com.yahoo.processing.request.CompoundName OFFSET  
      static com.yahoo.processing.request.CompoundName QUERY_PROFILE  
      static com.yahoo.processing.request.CompoundName SEARCH_CHAIN  
      static com.yahoo.processing.request.CompoundName TIMEOUT  
      static com.yahoo.processing.request.CompoundName 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, java.util.Map<java.lang.String,​java.lang.String> requestMap, CompiledQueryProfile queryProfile)
      Creates a query from a request
      Query​(Query query)  
      Query​(java.lang.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​(java.lang.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

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      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​(java.nio.ByteBuffer buffer)
      Encodes this query onto the given buffer
      int encodeAsProperties​(java.nio.ByteBuffer buffer, boolean encodeQueryData)
      Encodes properties of this query.
      boolean equals​(java.lang.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()
      Returns the explain level of this query, 0 means no tracing Higher numbers means increasingly more explaining
      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​(java.lang.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.
      int getTraceLevel()
      Returns the context level of this query, 0 means no tracing Higher numbers means increasingly more tracing
      boolean hasEncodableProperties()  
      int hashCode()
      Returns a hash of this query based on (some of) its content.
      boolean isTraceable​(int level)
      Returns the context level of this query, 0 means no tracing Higher numbers means increasingly more tracing
      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)
      Sets the explain level of this query, 0 means no tracing Higher numbers means increasingly more explaining
      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​(java.lang.String timeoutString)
      Sets timeout from a string which will be parsed as a
      void setTraceLevel​(int traceLevel)
      Sets the context level of this query, 0 means no tracing Higher numbers means increasingly more tracing
      void setWindow​(int offset, int hits)
      Convenience method to set both the offset and the number of hits to return
      java.lang.String toDetailString()
      Returns a string describing this query in more detail
      java.lang.String toString()
      Returns a string describing this query
      void trace​(boolean includeQuery, int traceLevel, java.lang.Object... messages)
      Adds a trace message to this query if the trace level of the query is sufficiently high.
      void trace​(java.lang.Object message, int traceLevel)  
      void trace​(java.lang.String message, boolean includeQuery, int traceLevel)
      Adds a trace message to this query if the trace level of the query is sufficiently high.
      void trace​(java.lang.String message, int traceLevel)
      Adds a context message to this query and to the info log, if the context level of the query is sufficiently high.
      java.lang.String validate()
      Validates this query
      java.lang.String yqlRepresentation()
      Serialize this query as YQL+.
      java.lang.String yqlRepresentation​(boolean includeHitsAndOffset)
      Serialize this query as YQL+.
      java.lang.String yqlRepresentation​(com.yahoo.collections.Tuple2<java.lang.String,​com.yahoo.component.Version> segmenterVersion, boolean includeHitsAndOffset)
      Deprecated.
      remove the ignored segmenterVersion argument from invocations
      • 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 Detail

      • 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

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

      • Query

        public Query()
        Constructs an empty (null) query
      • Query

        public Query​(java.lang.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​(java.lang.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,
                     java.util.Map<java.lang.String,​java.lang.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 Detail

      • 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 java.lang.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​(java.lang.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

        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

        public java.lang.String toString()
        Returns a string describing this query
        Overrides:
        toString in class java.lang.Object
      • toDetailString

        public java.lang.String toDetailString()
        Returns a string describing this query in more detail
      • encode

        public int encode​(java.nio.ByteBuffer buffer)
        Encodes this query onto the given buffer
        Parameters:
        buffer - The buffer to encode the query to
        Returns:
        the number of encoded items
      • trace

        public void trace​(java.lang.String message,
                          int traceLevel)
        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 add
        traceLevel - the context level of the message, this method will do nothing if the traceLevel of the query is lower than this value
      • trace

        public void trace​(java.lang.Object message,
                          int traceLevel)
      • trace

        public void trace​(java.lang.String message,
                          boolean includeQuery,
                          int traceLevel)
        Adds a trace message to this query if the trace level of the query is sufficiently high.
        Parameters:
        message - the message to add
        includeQuery - true to append the query root stringValue at the end of the message
        traceLevel - the context level of the message, this method will do nothing if the traceLevel of the query is lower than this value
      • trace

        public void trace​(boolean includeQuery,
                          int traceLevel,
                          java.lang.Object... messages)
        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 message
        traceLevel - the context level of the message, this method will do nothing if the traceLevel of the query is lower than this value
        messages - the messages whose toStrings will be concatenated into the trace message. Concatenation will only happen if the trace level is sufficiently high.
      • attachContext

        public void attachContext​(Query query)
                           throws java.lang.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:
        java.lang.IllegalStateException - If the query given as argument already has context information.
      • yqlRepresentation

        public java.lang.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(boolean)
      • yqlRepresentation

        @Deprecated
        public java.lang.String yqlRepresentation​(com.yahoo.collections.Tuple2<java.lang.String,​com.yahoo.component.Version> segmenterVersion,
                                                  boolean includeHitsAndOffset)
        Deprecated.
        remove the ignored segmenterVersion argument from invocations
      • yqlRepresentation

        public java.lang.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:
        java.lang.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 java.lang.Object
      • equals

        public boolean equals​(java.lang.Object other)
        Returns whether the given query is equal to this
        Overrides:
        equals in class java.lang.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
      • 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

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

        public SessionId getSessionId​(java.lang.String serverId)
        Returns the session id of this query, and creates and assigns it if not already present
      • hasEncodableProperties

        public boolean hasEncodableProperties()
      • encodeAsProperties

        public int encodeAsProperties​(java.nio.ByteBuffer buffer,
                                      boolean encodeQueryData)
        Encodes properties of this query.
        Parameters:
        buffer - the buffer to encode to
        encodeQueryData - 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.