Facet filtering reference

Filtering facets

To filter facets, use the facet.types.filter object. You can specify whether you want to do AND or OR filtering, whether you want the values in this facet to change dynamically based on filters in other facets, and whether you want to use complex nested filters, among other things. Refer to the use cases and sample calls that showcase a variety of facet filtering.

This topic is specific to the search.facet.types.filter.values object. For general facet filtering reference, see the Search and Recommendation detailed API reference.

The following table describes the keys that the search.facet.types.filter.values object can take:

Key	Type	Description	Value
`values`	`array of strings` `array of filter objects`	Required. The filter details for this facet. To do simple facet filtering by facet IDs, pass an array of strings. To do complex facet filtering with operators like `lte` (less than or equal to), `geoDistance`, `not`, for example, pass an array of objects.	For simple facet filtering: `json<br>"values": ["facet_id123", "facet_id456", "facet_id789"]<br>` For complex facet filtering: `json<br>{<br> "type": "and",<br> "filters": [<br> {<br> "type": "lte",<br> "value": "1000"<br> },<br> {<br> "type": "gte",<br> "value": "200"<br> },<br> {<br> "type": "not",<br> "filter": {<br> "type": "eq",<br> "value": "350"<br> }<br> }<br> ]<br>}<br>`

To do simple facet filtering by facet IDs, pass an array of strings as the value for the search.facet.types.filter.values key. The Filtering a term facet section of Filtering facets has a sample call.

The following table describes the keys that the search.facet.types.filter.values object requires if it is of the array of strings type.

Key	Type	Description
`values`	`array of strings`	Optional. Pass an array of strings. Array of facet IDs that you want to filter by. Pass only facet IDs. Don't pass facet values. For example: `json<br>"values": ["facet_id123", "facet_id456", "facet_id789"]<br>`

To do complex facet filtering with operators like lte (less than or equal to), geoDistance, not, for example, pass an array of filter objects as the value for the search.facet.types.filter.values key. The Using complex facet filters section of Filtering facets has sample calls.

The following table describes the keys that the search.facet.types.filter.values object takes if it is of the array of filter objects type.

Key	Type	Description
values	Array of objects of the following types facet filter objectand facet filter objectanyOf facet filter objecteq facet filter objectgeoDistance facet filter objectgeoWithin facet filter objectgt facet filter objectgte facet filter objectlt facet filter objectlte facet filter objectnot facet filter objector facet filter object	Facet filtering objects you want to use.

Filter objects

To add nested facet filters, all of which have to match to get a result, use the and facet filter object. This facet filter object is recursive.

The following table describes the keys the and facet filter object takes:

Key	Type	Description
type	string	Required.Set as and.Operator of the facet filter object.
filters	Array of objects of the following types facet filter objectand facet filter objectanyOf facet filter objecteq facet filter objectgeoDistance facet filter objectgeoWithin facet filter objectgt facet filter objectgte facet filter objectlt facet filter objectlte facet filter objectnot facet filter objector facet filter object	Required.Array of facet filter objects or facet IDs. The filtering conditions of all objects must be satisfied.

For example, you nest lte, gte, and not facet filter objects within the and facet filter object. In doing this, you request results that satisfy the conditions of being greater than an amount, less than an amount, and not equal to an amount.

Here's a sample and facet filter object:

{
   "type": "and",
   "filters": [
      {
         "type": "lte",
         "value": "1000"
      },
      {
         "type": "gte",
         "value": "200"
      },
      {
         "type": "not",
         "filter": {
            "type": "eq",
            "value": "350"
         }
      }
   ]
}

To get results that match any given value, use the anyOf facet filter object.

The following table describes the keys the anyOf facet filter object takes:

Key	Type	Description
`type`	`string`	Required. Set as `anyOf`. Operator of the facet filter object.
`values`	Array of `string` or `number` values	Required. Facet values you want to filter by, any of which can match to get results. Only pass facet values. Don't pass facet IDs. The values must be of the type of the attribute on which the filter is applied on.

Here's a sample anyOf facet filter object:

{
   "type": "anyOf",
   "values": [
      "History",
      "Science Fiction",
      "Classics"
   ]
}

To get results that match all the given values, use the allOf facet filter object.

The following table describes the keys the allOf facet filter object takes:

Key	Type	Description
`type`	`string`	Required. Set as `allOf`. Operator of the facet filter object.
`values`	Array of `string` or `number` values	Required. Facet values you want to filter by, all of which must match to get results. Only pass facet values. Don't pass facet IDs. The values must match the type of the attribute on which the filter is applied on.

To get results that match a given value, use the eq facet filter object.

The following table describes the keys the eq facet filter object takes:

Key	Type	Description
`type`	`string`	Required. Set as `eq`. Operator of the facet filter object.
`value`	`string` or `number`	Required. Facet value that must be matched to get a result. Only pass facet values. Don't pass facet IDs. The value must be of the type of the attribute on which the filter is applied on.

Here's a sample eq facet filter object:

{
   "type": "eq",
   "value": "Science Fiction"
}

To get results within a circular area you define, use the geoDistance facet filter object.

The following table describes the keys the geoDistance facet filter object takes:

Key	Type	Description
type	string	Required.Set as geoDistance.Operator of the facet filter object.
distance	string	Required.Radius of the circular geographical area where you want Search to find suitable content items.Enter a number followed by a unit of distance. Don't add spaces. For example, enter 8.6ft or 86km.Supported units are (inches)ft (feet)yd (yards)mi (miles)nmi (nautical miles)km (kilometers)m (meters)cm (centimeters)mm (millimeters)
lat	number	Latitude of the visitor's location. Together, lat and lon define the center of the circle where you want to filter results.Use the decimal degrees (DD) format. Don't use spaces.For example, pass -77.0089.If you do not specify a value here, Search looks in the geo context object for a latitude value. If there is no geo context object, Search infers the approximate latitude from the visitor's IP address.
lon	number	Longitude of the visitor's location. Together, lat and lon define the center of the circle where you want to filter results.Use the decimal degrees (DD) format. Don't use spaces.For example, pass -120.0017.If you do not specify a value here, Search looks in the geo context object for a latitude value. If there is no geo context object, Search infers the approximate latitude from the visitor's IP address.

Here's a sample geoDistance facet filter object:

{
   "type": "geoDistance",
   "distance": "50km",
   "lat": -59.11309610169502,
   "lon": -37.329354589260596
}

To get results within a defined polygonal area, use the geoWithin facet filter object.

The following table describes the keys the geoWithin facet filter object takes:

Key	Type	Description
`type`	`string`	Required. Set as `geoWithin`. Operator of the facet filter object.
`coordinates`	Array of `coordinates` objects.	Coordinates that form the polygonal area where Search looks for results. The `lat` and `lon` keys of this object define one vertex of the polygon. For example, if you define four vertexes, Search creates a four-sided area to filter results within. Define at least three points.

coordinates object

Pass at least three coordinates objects for Search to create a polygonal area.

The following table describes the keys the coordinates object takes:

Key	Type	Description
`lat`	`number`	Latitude of a vertex of the polygonal area where you want Search to look for results. Use the decimal degrees (DD) format. Don't use spaces. For example, pass `-77.0089`.
`lon`	`number`	Longitude of a vertex of the polygonal area where you want Search to look for results. Use the decimal degrees (DD) format. Don't use spaces. For example, pass `-120.0017`.

Here's a sample geoWithin facet filter object:

{
   "type": "geoWithin",
   "coordinates": [
      {
         "lat": 43.194852,
         "lon": -79.570522
      },
      {
         "lat": 43.176515,
         "lon": -79.929493
      },
      {
         "lat": 43.521512,
         "lon": -79.912504
      },
      {
         "lat": 43.871014,
         "lon": -78.780655
      }
   ]
}

To get results greater than a given value, use the gt facet filter object. You can only use this facet filter object with histogram facets.

The following table describes the keys the gt facet filter object takes:

Key	Type	Description
`type`	`string`	Required. Set as `gt`. Operator of the facet filter object.
`value`	`string` or `number`	Required. Facet value to use as a threshold to get results greater than. Only pass facet values. Don't pass facet IDs.

Here's a sample gt facet filter object:

{
   "type": "gt",
   "value": 999
}

To get results greater than or equal to a given value, use the gte facet filter object. You can only use this facet filter object with histogram facets.

The following table describes the keys the gte facet filter object takes:

Key	Type	Description
`type`	`string`	Required. Set as `gte`. Operator of the facet filter object.
`value`	`string` or `number`	Required. Facet value to use as a threshold to get results greater than or equal to. Only pass facet values. Don't pass facet IDs.

Here's a sample gte facet filter object:

{
   "type": "gte",
   "value": 1000
}

To get results less than a given value, use the lt facet filter object. You can only use this facet filter object with histogram facets.

The following table describes the keys the lt facet filter object takes:

Key	Type	Description
`type`	`string`	Required. Set as `lt`. Operator of the facet filter object.
`value`	`string` or `number`	Required. Facet value to use as a threshold to get results less than. Only pass facet values. Don't pass facet IDs.

Here's a sample lt facet filter object:

{
   "type": "lt",
   "value": 1000
}

To get results less than or equal to a given value, use the lte facet filter object. You can only use this facet filter object with histogram facets.

The following table describes the keys the lte facet filter object takes:

Key	Type	Description
`type`	`string`	Required. Set as `lte`. Operator of the facet filter object.
`value`	`string` or `number`	Required. Value to use as a threshold to get results less than or equal to. Only pass facet values. Don't pass facet IDs.

Here's a sample lte facet filter object:

{
   "type": "lte",
   "value": 999
}

To add nested facet filters, none of which have to match to get a result, use the not facet filter object. This facet filter object is recursive.

The following table describes the keys the not facet filter object takes:

Key	Type	Description
type	string	Required.Set as not.Operator of the facet filter object.
filter	Object of the following types or string facet IDstringallOf facet filter objectand facet filter objectanyOf facet filter objecteq facet filter objectgeoDistance facet filter objectgeoWithin facet filter objectgt facet filter objectgte facet filter objectlt facet filter objectlte facet filter objectnot facet filter objector facet filter object	Required.Facet filter object or string facet ID.

Here's a sample not facet filter object:

{
   "type": "not",
   "filter":"facet_id123"
}

To add nested facet filters, any of which have to match to get a result, use the or facet filter object. This facet filter object is recursive.

The following table describes the keys the or facet filter object takes:

Key	Type	Description
type	string	Required.Set as or.Operator of the facet filter object.
filters	Array of objects of the following types facet filter objectand facet filter objectanyOf facet filter objecteq facet filter objectgeoDistance facet filter objectgeoWithin facet filter objectgt facet filter objectgte facet filter objectlt facet filter objectlte facet filter objectnot facet filter objector facet filter object	Required.Array of facet filter objects or string facet IDs. The filtering conditions of at least one object or facet ID must be satisfied.

For example, you nest lte, gte, and eq facet filter objects within the or facet filter object. In doing this, you request results that satisfy the conditions of either being greater than an amount, less than an amount, or equal to an amount.

Here's a sample or facet filter object:

{
   "type": "or",
   "filters": [
      {
         "type": "lte",
         "value": "150"
      },
      {
         "type": "gte",
         "value": "350"
      },
      {
         "type": "eq",
         "value": "200"
      }
   ]
}

If you have suggestions for improving this article, let us know!

Facet filtering reference

Simple facet filtering

Complex facet filtering

Filter objects

and facet filter object

anyOf facet filter object

allOf facet filter object

eq facet filter object

geoDistance facet filter object

geoWithin facet filter object

gt facet filter object

gte facet filter object

lt facet filter object

lte facet filter object

not facet filter object

or facet filter object

Documentation Assistant