Multiple faceted search

Learn how to run a facet search for multiple attributes in a single request.

Use this function to run a faceted search across multiple attributes in a single request.

Request

POST {TenantURL}/entities/_facets

Reltio recommends that you pass the parameters through the request body.

Note: For interaction objects, you can perform the same facet search request by using the following request: POST {{api_uri}}/{{tenant}}/interactions/_facets.

Table 1. Parameters
Parameter		Required	Description
Headers	`Authorization`	Yes	Information about authentication access token in format "Bearer `<accessToken>`" (see details in Authentication API).
Query (optional if provided in body)	`filter`	No	Enables entities filtering by a condition. Format for filter query parameter: `filter=({Condition Type}[AND/OR {Condition Type}]*)` For more information see Filtering Entities.
	`options`	No	This is comma-separated list of different options. Available option is `searchByOv`: search and sort by all attributes with ov only; disabled by default. Example: `options=searchByOv`
	`activeness`	No	Available options: `active`: allows search among active entities. `all`: allows search among all (active/expired) entities. `not_active`: allows search among expired entities. Example: `activeness=active`
Body			Indicates a JSON array of facet request specifications or a JSON object with facets fields. The same fields are supported as query parameters as well. Note: The query parameters have priority and override the body parameters. Example: JSON array of facet request specifications `[ { "fieldName" : "type" }, { "fieldName" : "attributes.Education.GPA", "orderType" : "reversedCount", "pageSize" : 3, "pageNo" : 2, "includeFilter" : [ "2.1", "5.1", "3.3" ] } ]` Example: JSON object `{ "filter": "(equals(type,'configuration/entityTypes/Organization'))", "activeness": "active", "options": "sortByOV,ovOnly", "facets": [ { "fieldName": "type" }, { "fieldName": "attributes.Education.GPA", "orderType": "reversedCount", "pageSize": 3, "pageNo": 2, "includeFilter": [ "2.1", "5.1", "3.3" ] } ] }`

Table 2. Facet Request Specification Parameters
Parameter	Value	Value type
`fieldName`	Facet attribute (same as "facet" in basic facet request)	string
`orderType`	Sorting type: Could be "`term`", "`count`", "`reversedTerm`" and "`reversedCount`", sorting by facet term or facet count	ENUM
`pageSize`	Size of page in result	integer
`pageNo`	Number of page to return	integer
`includeFilter`	JSON array of strings (terms to return)	array of strings

Note: To protect the Search service from resource exhaustion, limits are imposed in the Multiple Faceted Search requests. If the combination of pageSize and pageNo exceed 3,333 terms, then an error is returned. In such cases, the request must be adjusted to not exceed the limit. (In practice, it is not anticipated that real world applications may reach this limit.) For example, if pageSize is 100, then pageNo must not exceed 33 as pageNo 34 requires terms 3,300 to 3,399 to be returned, which exceeds the 3,333-term limit.

Response

JSON array with facet terms and counts.

Request - Find Individual Entities

You can use one of the following body formats in the API:

A JSON array of facet request objects where the query parameters are included in the header.
A JSON object with optional fields filter, activeness, options, and a facets array where the query parameters are included in the request body.

The following request contains a JSON array of facet request objects :

POST {TenantURL}/entities/_facets?filter=(equals(type,'configuration/entityTypes/Individual'))
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512
[
  {
    "fieldName" : "type"
  },
  {
    "fieldName" : "attributes.Education.GPA",
    "orderType" : "reversedCount",
    "pageSize" : 3,
    "pageNo" : 2,
    "includeFilter" : [ "2.1", "5.1", "3.3" ]
  },
  {
    "fieldName" : "attributes.FirstName",
    "orderType" : "term",
    "pageSize" : 10,
    "pageNo" : 1
  }
]

The following request contains a JSON object including any of the supported query parameters plus a facets array:

POST {TenantURL}/entities/_facets
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512
{
  "filter": "(equals(type,'configuration/entityTypes/Individual'))",
  "facets": [
    { "fieldName": "type" },
    {
      "fieldName": "attributes.Education.GPA",
      "orderType": "reversedCount",
      "pageSize": 3,
      "pageNo": 2,
      "includeFilter": ["2.1", "5.1", "3.3"]
    }
  ]
}

Response

{
	"type": {
		"individual": 222,
		"organization": 333,
		"location": 444
	},
	"attributes.Education.GPA": {
		"2.1": 1,
		"2.2": 2,
		"3.3": 5,
		"5.1": 7
	},
	"attributes.FirstName: : {
		"John " : 17,
		"Peter " : 32,
		"Alex " : 6
	}}

Limitations of `_facets` requests

The _facets endpoint is optimized to return the most frequent values for a given attribute. However, its accuracy may be limited in certain scenarios:

High cardinality fields: When faceting on fields with many unique values — such as IDs, email addresses, or timestamps — the response may undercount or exclude valid values. These fields aren't recommended for faceted queries.
Reverse sorting: Using orderType: reversedCount to identify less common values can lead to incomplete results. Values with low frequency may be omitted.

Why this happens: Because distributed systems aggregate top values from individual shards, some values might be excluded from the final result — even if present in the full data set.

Recommendation: For best results, use _facets on attributes with moderate cardinality where top N values are meaningful — such as product categories, countries, or status types.

Unify and manage your data

Multiple faceted search

Request - Find Individual Entities

Limitations of `_facets` requests

Footer

Unify and manage your data

Multiple faceted search

Request - Find Individual Entities

Limitations of _facets requests

Footer

Limitations of `_facets` requests