# Class FacetRefinement (5.0.3)

    public final class FacetRefinement

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](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.FacetResultValue) returned by the backend that can be passed to
[Query.Builder#addFacetRefinementFromToken(String)](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.Query.Builder#com_google_appengine_api_search_Query_Builder_addFacetRefinementFromToken_java_lang_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)](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.Query.Builder#com_google_appengine_api_search_Query_Builder_addFacetRefinement_com_google_appengine_api_search_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);
     
## Inheritance

[java.lang.Object](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html) \> FacetRefinement

## Inherited Members

[Object.clone()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#clone--) [Object.equals(Object)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#equals-java.lang.Object-) [Object.finalize()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#finalize--) [Object.getClass()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#getClass--) [Object.hashCode()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#hashCode--) [Object.notify()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#notify--) [Object.notifyAll()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#notifyAll--) [Object.toString()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#toString--) [Object.wait()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait--) [Object.wait(long)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait-long-) [Object.wait(long,int)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait-long-int-)

## Static Methods

### fromTokenString(String token)

    public static FacetRefinement fromTokenString(String token)

Converts a token string to a FacetRefinement object.


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

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `token` | `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` A token string returned by [FacetResultValue#getRefinementToken](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.FacetResultValue#com_google_appengine_api_search_FacetResultValue_getRefinementToken_) or [FacetRefinement#toTokenString](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.FacetRefinement#com_google_appengine_api_search_FacetRefinement_toTokenString_). |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.FacetRefinement` | A [FacetRefinement](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.FacetRefinement) object. |

### withRange(String name, FacetRange range)

    public static FacetRefinement withRange(String name, FacetRange range)

Create a [FacetRefinement](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.FacetRefinement) with the given `name` and `range`.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `name` | `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` the name of the facet. |
| `range` | `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.FacetRange` the range of the numeric facet. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.FacetRefinement` | an instance of [FacetRefinement](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.FacetRefinement). |

### withValue(String name, String value)

    public static FacetRefinement withValue(String name, String value)

Create a [FacetRefinement](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.FacetRefinement) with the given `name` and `value`.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `name` | `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` the name of the facet. |
| `value` | `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` the value of the facet (both numeric and atom). |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.FacetRefinement` | an instance of [FacetRefinement](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.FacetRefinement). |

## Methods

### getName()

    public String getName()

Returns the name of the facet.

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` |   |

### getRange()

    public FacetRange getRange()

Returns the range for numeric facets or null if there is no range.

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/appengine/docs/standard/java-gen2/reference/services/bundled/latest/com.google.appengine.api.search.FacetRange` |   |

### getValue()

    public String getValue()

Returns the value of the facet or null if there is no value.

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` |   |

### toString()

    public String toString()

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` |   |

**Overrides** [Object.toString()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#toString--)

### toTokenString()

    public 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** ||
|---|---|
| **Type** | **Description** |
| `https://docs.oracle.com/javase/8/docs/api/java/lang/String.html` | A token string safe to be used in HTML for this facet refinement. |