Global Clustered Search - Fluid Topics - 3.6

Use Fluid Topics Web API

Product
Fluid Topics
FT_Version
3.6
Category
Technical Notes
language
English

This web service is used to search publications. It returns clustered publications matching the query conditions through a paginated output.

The spellcheck option is activated by default. If the query is misspelled, the request is launched again with the new spelling suggested by the spellchecker.

Facets can be added for users to filter the matching publications.

Method

Endpoint

POST

/api/khub/clustered-search

The request must set the Content-Type: application/json header.

User rights are taken into account when the Authorization header is provided, otherwise only public results are returned.

Input Example

The input JSON expects the following parameters:

Parameter

Cardinality

Type

Description

query

Optional

String

Expects the string query used to return matching publications. If not set, an empty search is queried.

contentLocale

Mandatory

String

Expects the content language ISO code. If not set, the query fails.

uiLocale

Optional

String

Expects the UI language ISO code. If not set, Fluid Topics tries to detect the user locale. This locale is used to return facet labels in the correct language, for instance.

filters

Optional

filter Array

Enables to filter the results on some metadata values.

The filter object expects the following criteria:

  • key (mandatory): Filter keys can be any user metadata or technical facets.
  • values (mandatory): Defines the value for the given key. When multiple values are given, they are combined with an AND or an OR operator depending on the tenant configuration.
  • negative (optional): When set to true, the results matching the previously set values are excluded. By default, the negative parameter is implicit and set to false.

Defaults to empty list.

sort

Optional

sort Object

Enables to specify a custom sort on any metadata.

The sort object expects the following criteria:

  • key (mandatory): Sort criterion keys can be any user metadata or technical facets, for example:
    • ft:lastPublication
    • ft:topicTitle
    • ft:relevance is a special keyword is provided to sort by relevance.
  • order (mandatory): Each criterion can be ascendant (ASC) or descendant (DESC). By default, the standard Fluid Topics sort order is used.

facets

Optional

facet Array

Enables to display facets from their facet ID. Users can then filter content through these facets.

Facets are displayed in the same order as they are declared.

If facets is absent or present but empty, no facet is displayed.

The facet object expects the following criteria:

  • id (mandatory): Is the facet ID.
  • maxDepth (optional): Defines the maximum depth level for the facet. When displaying a hierarchical facet, by default, the whole hierarchy is displayed.

paging

Optional

paging Object

Expects the following paging information:

  • page (mandatory): Is the number of the queried result page.
  • perPage (optional): Is the number of result clusters for each page.

By default, the pagination is set to page 1 and 20 result clusters per page.

The following lines display an example of JSON input:

{
"query": "$KEYWORDS",
"contentLocale": "$LOCALE",
"filters": [
{
"key": "$FACET_ID_1",
"values": ["$FACET_VALUE_A", "$FACET_VALUE_B"]
},
{
"key": "$FACET_ID_2",
"values": ["$FACET_VALUE_C"]
},
...
],
"sort": [
{
"key": "$FACET_ID_1",
"order": "DESC|ASC"
},
...
],
"facets": [
{
"id": "$FACET_ID_2",
"maxDepth": 2
},
...
],
"paging": {
"page": 1,
"perPage": 20
}
}

Output Example

{
"spellcheck": {
"suggestedQuery": "correctedKeywords",
"htmlSuggestedQuery": "<span class=\"kwicmatch\">correctedKeywords</span>"
},
"facets": [
{
"key": "versions",
"label": "versions",
"hierarchical": true,
"multiSelectionable": true,
"rootNodes": [
{
"value": "Fluid Topics",
"label": "Fluid Topics",
"selected": false,
"totalResultsCount": 6,
"childNodes": [...],
"descendantSelected": false
}
]
}
],
"results": [
{
"metadataVariableAxis": "dita:ditaval",
"entries": [
{
"type": "TOPIC|MAP|DOCUMENT",
"topic|map|document": {...}
...}
]
}
],
"paging": {
"currentPage": 1,
"totalResultsCount": 165,
"totalClustersCount": 114,
"isLastPage": false
}
}

Where:

  • kwicstring is the part of the original query which was correctly spelled.
  • kwicmatch is the part of the query corrected by the spellchecker.

The output provides the following parameters:

Parameter

Description

spellcheck

The string displayed in the suggestion box. A specific <span class> is attributed to the suggested term to highlight its occurrences in the Search Results page.

facets

Identifies the facets with their ID and their display name.

Gives each facet types: hierarchical and/or multi-select.

If the facet is hierarchical, parent facets are indicated in rootNodes elements and their child facets in the childNodes elements.

results

Indicates all publications returned for the query.

Each group of elements comprised in the results element corresponds to a cluster.

In the cluster, if the metadataVariableAxis is present, it indicates the metadata used to generate the cluster selector.

Each publication is given in an entries element. entries provides the publication type, ID, name, an excerpt where the search keyword is mentioned, the publication metadata and values, and so on.

entries takes one of the following types:

entries elements depend on the type.

Note: The element following the type element is a redundant piece of information. It is named after the type value.

paging

Indicates

  • The number of the current result page
  • The total number of results for the query
  • The number of result clusters for the query
  • If the current page is the last one