Notice: Over the next few months, we're reorganizing the App Engine documentation site to make it easier to find content and better align with the rest of Google Cloud products. The same content will be available, but the navigation will now match the rest of the Cloud products.

Python 2 is no longer supported by the community. We recommend that you migrate Python 2 apps to Python 3.

The FacetRefinement Class

Stay organized with collections Save and categorize content based on your preferences.

Class FacetRefinement is used to narrow search results based on a facet value.

The recommended way to use facet refinement is to use its token string. Each FacetResult will have a token that is acceptable instead of this class. To provide manual FacetRefinement, an instance of this class can be passed to SearchOptions.

Caution: **This solution is no longer recommended:** Apps that use this API can only run in the Python 2 runtime and will need to upgrade to a [recommended solution](/appengine/docs/legacy/standard/python/migrate-to-python3/migrating-services#migration_paths_for_bundled_services) before migrating to the Python 3 runtime.

FacetRefinement is defined in the module


The constructor for class FacetRefinement is defined as follows:

class FacetRefinement(name, value=None, facet_range=None)

Construct an instance of class FacetRefinement.

NOTE: Either the value or the facet_range should be set but not both.



Sets the name property


Sets the value property


Sets the facet_range property

Result value

A new instance of class FacetRefinement.



If any of the parameters have invalid types, or an unknown attribute is passed.


If any of the parameters have invalid values.


An instance of class FacetRefinement has the following properties:


name of the facet refinement.


string value of the facet refinement.


numeric range of the facet refinement.

Instance Methods

Instances of class FacetRefinement have the following methods:


Converts this refinement to a token string safe to be used in HTML. The format of this string may change.

Result value

A token string safe to be used in HTML for this facet refinement.


This static method converts a token string to a FacetRefinement object. Do not store token strings between different versions of API as key could be incompatible.



A token string created by ToTokenString method or returned by a search result.

Result value

A FacetRefinement object.



If the token_string is invalid.