facets
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. Note that the information below still applies to the old Adlib API facets command: information about the new facets implementation in the Axiell WebAPI will be forthcoming.
Syntax
command=facets&<parameter>=<value>&...
-
database
(String)
database on which to perform the facets function. The name of this database must have been specified in the adlibweb.xml file.
The facets command does not apply any stylesheet set in the configuration of the current database in adlibweb.xml
-
search
(String)
a search statement with the syntax used by the search command.
-
facet
(String)
the (English) field name or field tag to retrieve the facets (terms or names) from. The field (or its link reference tag if it is concerns a linked field) must have been indexed.
-
startfrom
(Integer)
[optional] the sequential number of the first term to return in the result (default 1).
-
limit
(Integer)
[optional] maximum amount of keys to return (default = 10).
-
output
(String)
[optional] output format to be returned. Values for
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.
Read more about JSON output here.
-
callback
(String)
[optional] returns JSON output wrapped in brackets with your callback function name, for AJAX requests: <callback function name>( <JSON output> ); You don't need to specify
output=json, because the output format is JSON by default.
Description
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.
Examples
-
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