Facets returns a list of terms or names appearing in a specified field in a search result, each accompanied by the number of records in which that term or name appears in the relevant search result.
command=facets&<parameter>=<value>&...
output can be either json or xml (xml is the default, so you don't need to specify that explicitly). However, the output format produced by jQuery applications is always JSON, so you don't need to specify the output type there either.output=json, because the output format is JSON by default.
Faceted searching is a way to narrow down a search result by using one of the keywords in the search result to perform a more specific search than the previous one. A facets query itself doesn't yield a list of records: for a search statement and a specific field (both provided in the query), it retrieves all terms or names from that field as they appear in the records resulting from said search statement. Moreover, each term or name is accompanied by the number of times that term or name appears in the field in the would-be search result, so that the user can be informed about the number of records that will remain when the search result is narrowed down to the relevant facet.
As mentioned, you can use such a list to offer the user of your application a way to narrow down an initial search result: just use the original search statement and extend it with the new partial search on the term or name selected by the user.
For example, if a museum website visitor searches on the name of a painter, she might also find drawings and etchings by this painter and early work as well as his later work. You could offer lists of object categories and production periods alongside the search result to allow the user to narrow down the search result quickly.
From wwwopac.ashx version 3.7.15132.1, results from facet searching will automatically be sorted on hits count. Sorting will be descending, so, from the list of found facets, the term with the highest count will end up on top of the list, the term with the second highest count will be second on the list, etc. Only when some terms appear the same number of times in the searched records, these specific terms will be sorted alphabetically within the larger sorting on hits count. The automatic sorting on hits count cannot be switched off.
From wwwopac.ashx version October 2016, there is a more efficient way to perform facets searching, as facets has become available as a parameter for the search command and q= searches, allowing the result of any search to include lists of retrieved facets, so that only a single search yields all required data to present a search result and multiple facet lists, whereas using the facets command means having to perform a search to obtain a search result plus a facets search for every facet list you need.
From a search for all records, retrieve a list of creator roles registered in those records. show
http://test2.adlibsoft.com/ais5/wwwopacx/wwwopac.ashx?command=facets&database=collect&search=all&facet=creator.role
From a search for all records, retrieve a list of up to five techniques registered in those records. show
http://test2.adlibsoft.com/ais5/wwwopacx/wwwopac.ashx?command=facets&database=collect&search=all&facet=technique&limit=5
From a search for all records, retrieve a list of collections registered in those records. show
http://test2.adlibsoft.com/ais5/wwwopacx/wwwopac.ashx?command=facets&database=collect&search=all&facet=CL