Java 8 has reached end of support
and will be
deprecated
on January 31, 2026. After deprecation, you won't be able to deploy Java 8
applications, even if your organization previously used an organization policy to
re-enable deployments of legacy runtimes. Your existing Java
8 applications will continue to run and receive traffic after their
deprecation date. We recommend that
you
migrate to the latest supported version of Java.
FacetRefinement (Google App Engine API for Java)
Stay organized with collections
Save and categorize content based on your preferences.
- 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 Summary
-
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
-
-
Method Detail
-
withValue
public static FacetRefinement withValue(java.lang.String name,
java.lang.String 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)
- 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.
-
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
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-06-16 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-06-16 UTC."],[[["\u003cp\u003e\u003ccode\u003eFacetRefinement\u003c/code\u003e is a class used to filter search results based on facet values, allowing for both manual specification and token-based refinements.\u003c/p\u003e\n"],["\u003cp\u003eIt is recommended to use refinement token strings, provided by \u003ccode\u003eFacetResultValue\u003c/code\u003e, with \u003ccode\u003eQuery.Builder.addFacetRefinementFromToken(String)\u003c/code\u003e for follow-up queries instead of directly instantiating this class.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eFacetRefinement\u003c/code\u003e class supports creating refinements with specific values using \u003ccode\u003ewithValue\u003c/code\u003e or numeric ranges using \u003ccode\u003ewithRange\u003c/code\u003e, enabling filtering by exact values or ranges.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003etoTokenString\u003c/code\u003e converts a refinement to a token for use in HTML, while \u003ccode\u003efromTokenString\u003c/code\u003e reconstructs a \u003ccode\u003eFacetRefinement\u003c/code\u003e from such a token, facilitating the use of tokens in refining queries.\u003c/p\u003e\n"],["\u003cp\u003eThe methods \u003ccode\u003egetName\u003c/code\u003e, \u003ccode\u003egetValue\u003c/code\u003e, and \u003ccode\u003egetRange\u003c/code\u003e are included to enable you to get the name, value and the range respectively from the \u003ccode\u003eFacetRefinement\u003c/code\u003e object.\u003c/p\u003e\n"]]],[],null,["# FacetRefinement (Google App Engine API for Java)\n\ncom.google.appengine.api.search\n\nClass FacetRefinement\n---------------------\n\n- java.lang.Object\n-\n - com.google.appengine.api.search.FacetRefinement\n\n-\n\n *** ** * ** ***\n\n \u003cbr /\u003e\n\n ```\n public final class FacetRefinement\n extends java.lang.Object\n ``` \n A Facet Refinement to filter out search results based on a facet value.\n\n\n We recommend using refinement token strings instead of this class. We include a refinement\n token string with each [`FacetResultValue`](../../../../../com/google/appengine/api/search/FacetResultValue.html \"class in com.google.appengine.api.search\") returned by the backend that can be passed to\n [`Query.Builder.addFacetRefinementFromToken(String)`](../../../../../com/google/appengine/api/search/Query.Builder.html#addFacetRefinementFromToken-java.lang.String-) to refine follow-up queries.\n\n\n We also support manually-specified query refinements by passing an instance of this class to\n [`Query.Builder.addFacetRefinement(FacetRefinement)`](../../../../../com/google/appengine/api/search/Query.Builder.html#addFacetRefinement-com.google.appengine.api.search.FacetRefinement-).\n\n\n Example: Request to only return documents that have a number facet named \"rating\" with a value\n between one and two: \n\n ```\n FacetRefinement lowRating = FacetRefinement.withRange(\"rating\", FacetRange.startEnd(1.0, 2.0));\n query.addFacetRefinement(lowRating);\n \n ```\n\n \u003cbr /\u003e\n\n \u003cbr /\u003e\n\n \u003cbr /\u003e\n\n-\n -\n\n ### Method Summary\n\n -\n\n ### Methods inherited from class java.lang.Object\n\n`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait` \n-\n -\n\n ### Method Detail\n\n\n -\n\n #### withValue\n\n ```\n public static FacetRefinement withValue(java.lang.String name,\n java.lang.String value)\n ``` \n Create a [`FacetRefinement`](../../../../../com/google/appengine/api/search/FacetRefinement.html \"class in com.google.appengine.api.search\") with the given `name` and `value`.\n\n Parameters:\n : `name` - the name of the facet.\n : `value` - the value of the facet (both numeric and atom).\n\n Returns:\n : an instance of [`FacetRefinement`](../../../../../com/google/appengine/api/search/FacetRefinement.html \"class in com.google.appengine.api.search\").\n\n Throws:\n : `java.lang.IllegalArgumentException` - if `name` is null or empty or the `value` length\n is less than 1 or greater than SearchApiLimits#FACET_MAXIMUM_VALUE_LENGTH.\n\n\n -\n\n #### withRange\n\n ```\n public static FacetRefinement withRange(java.lang.String name,\n FacetRange range)\n ``` \n Create a [`FacetRefinement`](../../../../../com/google/appengine/api/search/FacetRefinement.html \"class in com.google.appengine.api.search\") with the given `name` and `range`.\n\n Parameters:\n : `name` - the name of the facet.\n : `range` - the range of the numeric facet.\n\n Returns:\n : an instance of [`FacetRefinement`](../../../../../com/google/appengine/api/search/FacetRefinement.html \"class in com.google.appengine.api.search\").\n\n Throws:\n : `java.lang.IllegalArgumentException` - if `name` is null or empty.\n\n\n -\n\n #### getName\n\n ```\n public java.lang.String getName()\n ``` \n Returns the name of the facet.\n\n\n -\n\n #### getValue\n\n ```\n public java.lang.String getValue()\n ``` \n Returns the value of the facet or null if there is no value.\n\n\n -\n\n #### getRange\n\n ```\n public FacetRange getRange()\n ``` \n Returns the range for numeric facets or null if there is no range.\n\n\n -\n\n #### toTokenString\n\n ```\n public java.lang.String toTokenString()\n ``` \n Converts this refinement to a token string safe to be used in HTML.\n\n\n NOTE: Do not persist token strings. The format may change.\n\n Returns:\n : A token string safe to be used in HTML for this facet refinement.\n\n\n -\n\n #### fromTokenString\n\n ```\n public static FacetRefinement fromTokenString(java.lang.String token)\n ``` \n Converts a token string to a FacetRefinement object.\n\n\n NOTE: Do not persist token strings. The format may change.\n\n Parameters:\n : `token` - A token string returned by [`FacetResultValue.getRefinementToken()`](../../../../../com/google/appengine/api/search/FacetResultValue.html#getRefinementToken--) or\n [`toTokenString()`](../../../../../com/google/appengine/api/search/FacetRefinement.html#toTokenString--).\n\n Returns:\n : A [`FacetRefinement`](../../../../../com/google/appengine/api/search/FacetRefinement.html \"class in com.google.appengine.api.search\") object.\n\n Throws:\n : `java.lang.IllegalArgumentException` - if the given token cannot be processed.\n\n\n -\n\n #### toString\n\n ```\n public java.lang.String toString()\n ```\n\n Overrides:\n : `toString` in class `java.lang.Object`"]]
