DC 5.7 Using faceted search

Owned by Mathias Mattson (MHM)
Feb 17, 2023
2 min read

Some searches support faceted search and filtering. This can be used to obtain more details about the filters available and provide a better user experience

Fetching the faceted filters

Information about faceted filters will be returned as part of the same search response, if enabled.

URL : /SearchService.js

Method : POST

Auth required : Yes

Required parameters

NameExampleDescription
SearchNameDigiZuite_System_Framework_SearchFixed parameter that identifies the endpoint search.
configfacet=trueEnables the faceting search.
configfacet.limit=101Limits the number of options returned for each filter .
config
facet.field={!ex=sAssetType}sAssetType
Enabled faceted result for the filter sAssetType. A list of all filters can be obtain using the DC 5.7 GetVisibleSearchFields endpoint.
configf.sAssetType.facet.sort=count

Sorts the options returns or the sAssetType filter. Available values:

  • count - sorts the options by usage(most used to lease used)
  • index - sorts the options alphabetically
accessKey2d8319f4-7a57-4ca0-a027-c44c2f259aacAccessKey for API

Optional parameters

More than 1 facet fields can be added to a search.

It is recommended to avoid faceting field of type date(datebetween) as they increase significantly the size of the search response.

cUrl data example

--data "SearchName=DigiZuite_System_Framework_Search&config=facet=true&config=facet.field=%7B!ex=sAssetType%7DsAssetType&config=f.sAssetType.facet.sort=count"

Success Response

Code : 200 OK

Content example

{
	"success":true,
	"error":"",
	"total":"3396",
	"items":[ /* ...items returned by the search... */ ],
	"extra":[
		{
			"responseHeader":{
				"warnings":[
					"Raising facet.mincount from 0 to 1, because field sAssetType is Points-based.",
				],
				"status":"0",
				"QTime":"2",
				"params":{
					"facet.field":[
						"{!ex=sAssetType}sAssetType",
					],
					"f.sAssetType.facet.sort":"count",
					"start":"0",
					"sort":"sortAssetidDesc desc",
					"rows":"1",
					"facet.limit":"101",
					"wt":"xml",
					"facet":"true"
				}
			}
		},
		{
			"facet_counts":{
				"facet_queries":{},
				"facet_fields":{
					"sAssetType":{
						"4":"3013", // Number of asset of asset type 4
						"1":"135", // Number of asset of asset type 1
						"8":"72",
						"14":"43",
						"15":"37",
						"9":"21",
						"2":"17",
						"10":"13",
						"16":"10",
						"17":"10",
						"11":"9",
						"5":"6",
						"7":"4",
						"18":"2",
						"19":"2",
						"100":"2"
					},
				},
				"facet_ranges":{},
				"facet_intervals":{},
				"facet_heatmaps":{}
			}
		}
	]
}

Error Response

Code : 200 OK

Content  example

{
	"success": false,
	"total": 0,
	"error": "A critical exception occurred while we executed the search.\r\n",
	"items": null,
	"warnings": [{
		"Severity": 150,
		"Code": 420,
		"Description": "A critical exception occurred while we executed the search."
	}]
}

Using faceted filters

URL : /SearchService.js

Method : POST

Auth required : Yes

Required parameters

NameExampleDescription
SearchNameDigiZuite_System_Framework_SearchFixed parameter that identifies the endpoint search.
configfacet=trueEnables the faceting search.
configfacet.limit=101Limits the number of options returned for each filter .
config
facet.field={!ex=sAssetType}sAssetType
Enabled faceted result for the filter sAssetType. A list of all filters can be obtain using the DC 5.7 GetVisibleSearchFields endpoint.
configf.sAssetType.facet.sort=count

Sorts the options returns or the sAssetType filter. Available values:

  • count - sorts the options by usage(most used to lease used)
  • index - sorts the options alphabetically
configfq={!tag=sAssetType}sAssetType:("1" OR "4")Filters the results of the search by setting  sAssetType filter to either 1 or 4
accessKey2d8319f4-7a57-4ca0-a027-c44c2f259aacAccessKey for API

cUrl data example

--data "SearchName=DigiZuite_System_Framework_Search&config=facet=true&config=facet.field=%7B!ex=sAssetType%7DsAssetType&config=f.sAssetType.facet.sort=count&config=fq=%7B!tag=sAssetType%7DsAssetType:(%221%22%20OR%20%224%22)"

Success Response

Code : 200 OK

Content example

{
	"success":true,
	"error":"",
	"total":"3396",
	"items":[ /* ...items returned by the search... */ ],
	"extra":[
		{
			"responseHeader":{
				"warnings":[
					"Raising facet.mincount from 0 to 1, because field sAssetType is Points-based.",
				],
				"status":"0",
				"QTime":"2",
				"params":{
					"facet.field":[
						"{!ex=sAssetType}sAssetType",
					],
					"f.sAssetType.facet.sort":"count",
					"start":"0",
					"sort":"sortAssetidDesc desc",
					"rows":"1",
					"facet.limit":"101",
					"wt":"xml",
					"facet":"true"
				}
			}
		},
		{
			"facet_counts":{
				"facet_queries":{},
				"facet_fields":{
					"sAssetType":{
						"4":"3013", // Number of asset of asset type 4
						"1":"135", // Number of asset of asset type 1
						"8":"0",
						"14":"0",
						"15":"0",
						"9":"0",
						"2":"0",
						"10":"0",
						"16":"0",
						"17":"0",
						"11":"0",
						"5":"0",
						"7":"0",
						"18":"0",
						"19":"0",
						"100":"0"
					},
				},
				"facet_ranges":{},
				"facet_intervals":{},
				"facet_heatmaps":{}
			}
		}
	]
}

Error Response

Code : 200 OK

Content  example

{
	"success": false,
	"total": 0,
	"error": "A critical exception occurred while we executed the search.\r\n",
	"items": null,
	"warnings": [{
		"Severity": 150,
		"Code": 420,
		"Description": "A critical exception occurred while we executed the search."
	}]
}