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 Detail

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