Facet

Description🔗

This object represents a search facet on the indexed documents.

A facet is bound to a metadata field, and it is used in the user interface to add add more search criteria on that field.

A Facet with all its configurations listed below is part of the static metadata returned by the getMetadata request of the search service. Facets are also returned as part of a search result. In that case only a small fraction of the static information is contained. Most configuration options are omitted, but item counts are returned if available.

Fields🔗

Parameter Name	Type	Description
field	string	The field name.
fieldLabel	string	The field label.
datatype	enum	The data type of the facet field. Possible values: TEXT, LONG_TEXT, NUMERIC, DATE, LOCATION
combinationtype	enum	The combination type defines how multiple facet selections are combined in a REQUIRED conditional query. Allowed values: AND, OR, SINGLE. AND means that the results must contain all selections, (e.g. English AND French language skill), OR means that the reuslts must contain one of the selections (e.g. Master OR Bachelor level), and SINGLE means that the facet is restricted to contain only one selection. OR is the default.
guitype	enum	The GUI type determines whether a facet should be displayed as a fixed item facet or as a tag cloud. Allowed values: FIXED, DYNAMIC, CLOUD, TEXTFIELD, LOCATION, or PROJECT. For the FIXED and DYNAMIC facet types the items are shown in the Search! UI as a list preceded by checkboxes. If the initially returned list of items is over 25, the display (in the Search! UI) will switch to an 'autocomplete select mode' to make it easier to search & select items in the list.
cloudtype	enum	The cloud type determines the display layout of the cloud. Allowed values: SPHERE, SPREAD, LIST, COLUMNS1, COLUMNS2, COLUMNS3
collapsed	boolean	If true the facet starts out collapsed instead of expanded.
hideFacetIfAllZero	boolean	If true the facet will be hidden when all items have zero counts.
hideZeroCountItems	boolean	If true items having a zero count will be hidden. This cannot be set when the fixed facet has showOnWidget set to True. This is also not adviced on FIXED and DYNAMIC type facets with an expected initial returned list of items higher than 25 as it hides selected values when in the 'autocomplete select mode' as described below
defaultCondition	enum	Default condition type. Allowed Values: FAVORED, STRONGLY_FAVORED, and REQUIRED.
hideConditionWidget	boolean	If true the condition widget will be hidden.
reverseItemOrder	boolean	If true, items will be displayed in reverse order.
sortItemsOnCodeDescription	boolean	If true the facet items will be sorted by code description instead of the codes themselves (only applicable on fixed text field facets with translations). Unlike reverseItemOrder this setting changes the order of items as returned by the API. The reverseItemOrder setting can be used additionally to reverse the items when displaying.
items	list of FacetItem	The items belonging to a FIXED item facet, null for a CLOUD facet
distances	list of strings	The selectable distances belonging to a LOCATION facet, otherwise empty.
defaultDistance	string	Optional default distance within a LOCATION facet's distance selector (if not defined it is the first entry).
textInputOnFacet	boolean	Determines whether for CLOUD facets the input box is displayed in the facet bar, otherwise within the tag-cloud.
searchEngine	string	Optional searchEngine name set only for exclusive facets.
dropdownSwitcherThreshold	integer	Optional attribute allows changing the default threshold number which controls the switching between checkboxes/dropdown components. If not present, the default value is 25. This attribute is only applicable when guitype is `fixed` or `dynamic`

Json Examples🔗

{
  "field": "educationdirection",
  "datatype": "TEXT",
  "combinationtype": "OR",
  "guitype": "CLOUD"
}

{
  "field": "educationlevel",
  "fieldLabel": "Education Level",
  "combinationtype": "OR",
  "guitype": "FIXED",
  "dropdownSwitcherThreshold": 5,
  "items": [
    {
      "value": "01",
      "label": "Bachelor",
      "count": 200
    },
    {
      "value": "02",
      "label": "Master",
      "count": 241
    }
  ]
}

{
  "field": "experienceyears",
  "datatype": "NUMERIC",
  "combinationtype": "OR",
  "guitype": "FIXED",
  "items": [
    {
      "value": "<1",
      "label": "less than 1"
    },
    {
      "value": "1..2",
      "label": "1 to 2"
    }
  ]
}

In case of facets on object fields, the search result will additionally contain a map of facet item counts for each ( object) query part item, called queryPartItemCounts. The keys of this map are positional references to the corresponding query part item in the query parts array, returned as within the same SearchResult object. The position indices have the following form:

part-position.item-position, e.g. 2.1 meaning query part 2, item 1.

All position counts start at zero, like array indices.

If any object query part item belonging to the same object field has no specific facet count set in this map, it's counts are equal to the overall facet counts related to this field.

Json Example🔗

{
  "field": "languages.level",
  "fieldLabel": "Level",
  "combinationType": "OR",
  "guiType": "FIXED",
  "items": [
    {
      "value": "Advanced",
      "label": "Advanced",
      "count": 5
    },
    {
      "value": "Native",
      "label": "Native",
      "count": 7
    },
    {
      "value": "Beginner",
      "label": "Beginner",
      "count": 5
    }
  ],
  "queryPartItemCounts": {
    "2.0": {
      "items": [
        {
          "value": "Advanced",
          "label": "Advanced",
          "count": 5
        },
        {
          "value": "Native",
          "label": "Native",
          "count": 2
        }
      ]
    },
    "2.1": {
      "items": [
        {
          "value": "Advanced",
          "label": "Advanced",
          "count": 3
        },
        {
          "value": "Beginner",
          "label": "Beginner",
          "count": 1
        }
      ]
    }
  }
}

Facet

Facet🔗

Description🔗

Fields🔗

Json Examples🔗

Facet Counts on Object Fields🔗

Json Example🔗