FacetRefinement (Google App Engine API for Java)

com.google.appengine.api.search

Class FacetRefinement

  • java.lang.Object
    • com.google.appengine.api.search.FacetRefinement


  • public final class FacetRefinement
    extends java.lang.Object
    A Facet Refinement to filter out search results based on a facet value.

    We recommend using refinement token strings instead of this class. We include a refinement token string with each FacetResultValue returned by the backend that can be passed to Query.Builder.addFacetRefinementFromToken(String) to refine follow-up queries.

    We also support manually-specified query refinements by passing an instance of this class to Query.Builder.addFacetRefinement(FacetRefinement).

    Example: Request to only return documents that have a number facet named "rating" with a value between one and two:

     FacetRefinement lowRating = FacetRefinement.withRange("rating", FacetRange.startEnd(1.0, 2.0));
     query.addFacetRefinement(lowRating);
     

    • Method Detail

      • withValue

        public static FacetRefinement withValue(java.lang.String name,
                                                java.lang.String value)
        Create a FacetRefinement with the given name and value.
        Parameters:
        name - the name of the facet.
        value - the value of the facet (both numeric and atom).
        Returns:
        an instance of FacetRefinement.
        Throws:
        java.lang.IllegalArgumentException - if name is null or empty or the value length is less than 1 or greater than SearchApiLimits#FACET_MAXIMUM_VALUE_LENGTH.
      • withRange

        public static FacetRefinement withRange(java.lang.String name,
                                                FacetRange range)
        Create a FacetRefinement with the given name and range.
        Parameters:
        name - the name of the facet.
        range - the range of the numeric facet.
        Returns:
        an instance of FacetRefinement.
        Throws:
        java.lang.IllegalArgumentException - if name is null or empty.
      • getName

        public java.lang.String getName()
        Returns the name of the facet.
      • getValue

        public java.lang.String getValue()
        Returns the value of the facet or null if there is no value.
      • getRange

        public FacetRange getRange()
        Returns the range for numeric facets or null if there is no range.
      • toTokenString

        public java.lang.String toTokenString()
        Converts this refinement to a token string safe to be used in HTML.

        NOTE: Do not persist token strings. The format may change.

        Returns:
        A token string safe to be used in HTML for this facet refinement.
      • fromTokenString

        public static FacetRefinement fromTokenString(java.lang.String token)
        Converts a token string to a FacetRefinement object.

        NOTE: Do not persist token strings. The format may change.

        Parameters:
        token - A token string returned by FacetResultValue.getRefinementToken() or toTokenString().
        Returns:
        A FacetRefinement object.
        Throws:
        java.lang.IllegalArgumentException - if the given token cannot be processed.
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object