facet(attribute, option)

Performs a faceted search over one attribute to obtain structured results for individual values of it.

Applicable to attributes of the string, stringlist, enum and multienum types.

Note that there is a precision limit for faceting: Only the first 50 characters of a string are guaranteed to be considered for faceting. If two string values have the same first 50 characters, they may be grouped into the same facet value.

Params

  • attribute (String) – The name of the attribute to be inspected.
  • option (optional) (Object) – The options to facet a request with (facet query options).
    • limit (Number) – The maximum number of unique values to return. Defaults to 10.
    • includeObjs (Number) – The number of Objs to fetch for each unique value. Defaults to 0.

Throws

  • ArgumentError if an invalid option has been provided.
  • ClientError if the maximum number of results has been exceeded. The number of results is limited to 100 with respect to the facets themselves and the included Objs.

Returns

Array<ObjFacetValue> – A list of unique values that were found for the given attribute name. The list is ordered by frequency, i.e. values occurring more frequently come first.

Example

Find blog posts whose “tags” stringlist includes “design”, and fan out those articles' tags, including up to five hits for each tag:

Note that you could also use the equals operator here for exact matches. Each facet in the facets array above is an instance of ObjFacetValue. The includedObjs of an ObjFacetValue can be accessed analogously to its name and count, via facet.includedObjs in this example.