Facet API

Facet Search

These endpoints calculate and return facets for matched documents.

Note: These endpoints require authentication which has been deliberately excluded from the example(s) below.

`GET /facets`

Performs a search and then computes the requested facets for the matched documents. Each request calculates a single facet.

Parameters

query (string, required): The search query.
type (string, optional, default: query): Specifies the type of search query.
facet (string, required): The document field name to group documents by (e.g., types, metadata/documentFormat).
is-facet-base64 (boolean, optional, default: false): If true, the facet field will be Base64 decoded.
range-start (string, optional): Start of a range filter.
range-end (string, optional): End of a range filter.
range-fields (string, optional): Fields for range filtering.
sample-size (integer, optional, default: 1000): The sample size used for computing facets (1-5000).
indices (string, optional): Specific indices to apply the operation on.

Example Call

curl -X GET  https://telicent.core.domain/api/search/facets?query=John&facet=types&sample-size=500

Responses

200 OK: Search was successful. Contains FacetResults object.
- query (string): The query used.
- type (string): The query type used.
- sampleSize (integer): The actual sample size used.
- results (array of FacetResult): List of computed facets.
  - value (string): The facet value.
  - count (integer): Number of occurrences of the facet value.
  - percentage (number): Relative frequency (0-1).
400 Bad Request: Invalid search parameters or unsupported query type/feature.
500 Internal Server Error: Server failed to process the request.
503 Service Unavailable: No underlying search index available.

Get Facet Values (POST)

`POST /facets`

Identical functionality to GET /facets, but allows parameters to be submitted via a application/x-www-form-urlencoded POST request.

Request Body (application/x-www-form-urlencoded)

query (string, required): The query string.
query-type (string, optional): The type of query.
facet (string, required): The facet to calculate.
is-facet-base64 (boolean, optional): Set to true if the facet is Base64 encoded.
range-start (string, optional, format: date-time): Start of the range filter.
range-end (string, optional, format: date-time): End of the range filter.
range-fields (array of string, optional): Fields for range filtering.
sample-size (integer, optional): Maximum sample size for calculating facets.
indices (string, optional): Specific indices to apply the operation to.

Example Call

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
     -d "query=document&facet=tags" \
     https://telicent.core.domain/api/search/facets

Responses

Same as GET /facets.