Package com.day.cq.search

Interface Query

@ProviderType public interface Query
A Query represents a JCR repository query that can be created programmatically, with a list of so-called Predicates. These act as constraints on the query, meaning they either add predicates to the underlying XPath query or filter the result, and there can be any number of predicates.

Each predicate has a type (Predicate.getType()) for which a PredicateEvaluator must exist, that can eg. translate the predicate in question into an XPath predicate. It is possible to register custom PredicateEvaluators by using the proper OSGi component factory name.

To create queries, use the QueryBuilder interface. To execute it, simply call getResult() to get the SearchResult, which will contain the hits, metadata about paging and access to facets.

Since:
5.2

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    getExcerpt()
    Returns whether the query will return plain nodes or an excerpt.
    long
    getGuessTotal()
    Answer the number of results to count to.
    long
    getHitsPerPage()
    Returns the number of hits to include per ResultPage, ie.
    PredicateGroup
    getPredicates()
    Returns the list of predicates that define this query.
    SearchResult
    getResult()
    Executes the query and returns the result.
    long
    getStart()
    Returns the offset in the actual search results to start from.
    boolean
    isGuessTotal()
    Answer whether the Query is configured to avoid counting all results.
    Query
    refine(Bucket bucket)
    This will return a new query that includes the given bucket from a previous search.
    void
    registerPredicateEvaluator(String type, PredicateEvaluator evaluator)
    This is an alternate way of providing a custom evaluator for predicates.
    void
    setExcerpt(boolean excerpt)
    Whether the query should return plain nodes or an excerpt.
    void
    setGuessTotal(boolean guessTotal)
    Set whether to stop counting results at the current limit.
    void
    setGuessTotal(long guessTotal)
    Set the amount of results to count to.
    void
    setHitsPerPage(long hitsPerPage)
    Sets the number of hits to include on a ResultPage.
    void
    setStart(long start)
    This sets an offset for the actual search results, ie.

  • Method Details

    • getResult

      SearchResult getResult()
      Executes the query and returns the result. Implementations will cache the result, ie. a second call of this method will return the initial result of the query execution; each Query only runs once. This also means that
      invalid reference 
      adding
      or
      invalid reference 
      removing
      predicates is no longer possible after calling getResult().

    • getPredicates

      PredicateGroup getPredicates()
      Returns the list of predicates that define this query. Changing this predicate tree only has an effect before getResult() has been called.
      Returns:
      the root predicate group making up this query

    • registerPredicateEvaluator

      void registerPredicateEvaluator(String type, PredicateEvaluator evaluator)
      This is an alternate way of providing a custom evaluator for predicates. The normal way is to register them as OSGi component factories (see PredicateEvaluator), but in some cases it is simpler to inline them, for example to provide a custom facet extraction inside a JSP. A notable difference is that this mechanism is only valid for the current Query, whereas the OSGi component way of registration makes the evaluator available for all queries.

      To register, a type must be specified. This evaluator will be used for all predicates with that type. Evaluators registered this way will have precedence over evaluators provided as OSGi component factories. The type should not start with a "_", as it would be ignored for queries created from requests (see PredicateConverter.createPredicates(java.util.Map).

      Parameters:
      type - the predicate type to register the evaluator for
      evaluator - a custom predicate evaluator

    • refine

      Query refine(Bucket bucket)
      This will return a new query that includes the given bucket from a previous search. It will simply take the predicate provided by the bucket (Bucket.getPredicate()) and add it to the new query so that both the existing predicate group and this new predicate are required to match.
      Parameters:
      bucket - a bucket (typically from the facets of this queries search result)
      Returns:
      a new query that includes the predicate provided by the bucket

    • setExcerpt

      void setExcerpt(boolean excerpt)
      Whether the query should return plain nodes or an excerpt. Default is false.
      Parameters:
      excerpt - true if an excerpt should be returned, false if not

    • getExcerpt

      boolean getExcerpt()
      Returns whether the query will return plain nodes or an excerpt. Default is false.
      Returns:
      true if an excerpt should be returned, false if not

    • setStart

      void setStart(long start)
      This sets an offset for the actual search results, ie. it will skip the first N (= start) items of the underlying result. By default this is 0, ie. right from the very beginning.
      Parameters:
      start - the offset in the actual search results to start from

    • getStart

      long getStart()
      Returns the offset in the actual search results to start from. See setStart(long).
      Returns:
      offset in the actual search results to start from

    • setHitsPerPage

      void setHitsPerPage(long hitsPerPage)
      Sets the number of hits to include on a ResultPage. Since only the first page is returned directly and typically fully read by clients, this can also be seen as "limit" for the search result. Further results can be accessed either by retrieving the next result page or by running a new query and setting the start parameter (often also called "offset"). For unlimited results on a single page, use 0. Default value is 10.
      Parameters:
      hitsPerPage - the number of hits to include on a result page (0 for unlimited results).

    • getHitsPerPage

      long getHitsPerPage()
      Returns the number of hits to include per ResultPage, ie. the limit. See setHitsPerPage(long).
      Returns:
      the number of hits to include per result page.

    • setGuessTotal

      void setGuessTotal(long guessTotal)
      Set the amount of results to count to. Default -1 means to count all results.
      Parameters:
      guessTotal - the value to count upto.

    • getGuessTotal

      long getGuessTotal()
      Answer the number of results to count to. To count all results, use -1.
      Returns:
      the number of results to count to.

    • setGuessTotal

      void setGuessTotal(boolean guessTotal)
      Set whether to stop counting results at the current limit. Default is false.
      Parameters:
      guessTotal - whether to stop counting results at the current limit.

    • isGuessTotal

      boolean isGuessTotal()
      Answer whether the Query is configured to avoid counting all results.
      Returns:
      true if the query will not count all results.