Clustered search - Fluid Topics

This web service makes it possible to retrieve clusters of documents matching the query conditions through a paginated response.

The spellcheck option is active by default. If the query contains a misspelling, the request is launched again with the new spelling suggested by the spellchecker.

It is possible to add facets to filter the matching publications.

Method	Endpoint
`POST`	`/api/khub/clustered-search`

Query string parameter	Type	Required?	Description
`page`	Number	No	Expects the page number. Starts at `1`.
`per_page`	Number	No	Expects the number of results per page. Starts at `1`. The maximum accepted value is `500`.
`from`	String	No	The inclusive start date of the period on which to filter results based on the value of the `ft:lastTechChange` metadata for the documents in the cluster. If unspecified, the default value is `1970-01-01`.
`to`	String	No	The inclusive end date of the period. The inclusive start date of the period. If unspecified, the default value is the current day.

It is necessary to set the Content-Type: application/json header parameter when calling this web service.
This web service requires authentication on portals with mandatory authentication.

It is possible to use pagination with this web service.
- Using pagination when retrieving clusters is recommended. Pagination applies by default (default values available in the request example table).
- It is possible to specify a period or paging for this web service using either query parameters or fields in the request body. When using both methods, the values of the query parameters take precedence.
When the HTTP header does not include user credentials, this web service only returns public results.
When a user is authenticated, Fluid Topics retrieves user groups to determine how to filter the content returned in the responses of the search web services.

As a USER_ADMIN user, it is possible to impersonate another user when using this web service.

Request body

The request body expects at least one of the following parameters:

Field	Type	Required?	Description
`query`	String	No	Expects the string query used to return publications with matching keywords. If not set, the content returned is based on other parameters such as `contentLocale` and `metadataFilters`.
`contentLocale`	String	No	Expects the content language's ISO code.
`uiLocale`	String	No	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.
`scope`	String	No	Restricts the `type` of results. Can be `DEFAULT` (results are of `TOPIC`, `MAP`, or `DOCUMENT` type), `DOCUMENTS` (results are of `MAP` or `DOCUMENT` type), or `ALL_TOPICS` (results are of `TOPIC` type).
`virtualField`	String	No	Defines whether to search in all content (`EVERYWHERE`) or in document titles only (`TITLE_ONLY`).
`metadataFilters`	Array	No	Filters the results based on selected criteria including metadata and date ranges. Defaults to an empty list.
`key`	String	Yes	Expects a metadata key.
`valueFilter`	Object	No	Contains the filtering conditions based on metadata values.
`values`	Array	Yes	Defines the value for the selected key. When multiple values are defined, they are combined with an `AND` or an `OR` operator depending on the tenant's configuration.
`negative`	Boolean	No	When `true`, this parameter excludes results matching the previously defined values. By default, the `negative` parameter is implicit and `false`.
`dateFilter`	Object	No	Specifies the date-based filtering conditions using predefined periods.
`type`	String	Yes	Restricts results to those within a predefined period. Acceptable values are `LAST_WEEK`, `LAST_MONTH`, `LAST_QUARTER`, `LAST_YEAR`.
`rangeFilter`	Object	No	Specifies custom date range filtering.
`from`	String	Yes	The inclusive start date of the period. If unspecified, the default value is `1970-01-01`.
`to`	String	Yes	The inclusive end date of the period. If unspecified, the default value is the current day.
`priors`	Array	No	Search business rules used to prioritize results based on metadata values. Defaults to an empty list.
`key`	String	Yes	Metadata key for which the prior is set.
`value`	String	Yes	Defines the value for the given metadata `key`.
`weight`	Number	Yes	A positive integer representing the importance of the key/value pair.
`sort`	Array	No	Specifies a custom sort on any metadata. The `sort` parameter is incompatible with the `priors` parameter.
`key`	String	Yes	Sort criterion keys can be any user metadata or technical facets, for example: `ft:lastPublication`, `ft:topicTitle`, `ft:relevance` is a special keyword provided to sort by relevance.
`order`	String	Yes	Each criterion can be ascending (`ASC`) or descending (`DESC`). By default, the standard Fluid Topics sort order is used.
`facets`	Array	No	Defines which facets are in the results. Users can then filter content through these facets. Facets appear in the same order as declared. If `facets` is absent or present but empty, no facet appears.
`id`	String	Yes	The facet ID.
`maxDepth`	Number	No	Defines the maximum depth level for the facet. By default, `maxDepth` has a value of `8`.
`lastModified`	Object	No	The date range applied to the query based on the modification date of the content.
`from`	String	No	The start date of the `CUSTOM` period. If unspecified, the default value is `1970-01-01`.
`to`	String	No	The end date of the `CUSTOM` period. If unspecified, the default value is the current day.
`paging`	Object	No	Information about paging. Expects the `page` and `perPage` parameters.
`page`	Number	No	Defines the page number. If undefined, the default value is `1`.
`perPage`	Number	No	Defines the number of results to display per page. If undefined, the default value is `20`.

If the priors parameter is used, the sort parameter cannot be used and vice versa.

The request body can be empty ({}), which returns results to their relevance.

Request examples

The following lines show an example of a JSON request body using the sort field:

{
  "query": "foo",
  "contentLocale": "en-US",
  "metadataFilters": [
    {
      "key": "Category",
      "valueFilter": {
        "values": [
          "Screencasts"
        ],
        "negative": false
      }
    },
    {
      "key": "Version",
      "valueFilter": {
        "values": [
          "2.0"
        ],
        "negative": false
      }
    }
  ],
  "sort": [
    {
      "key": "ft:title",
      "order": "ASC"
    }
  ],
  "facets": [
    {
      "id": "version"
    }
  ]
}

The following lines show an example of a JSON request body using the prior field:

{
  "query": "foo",
  "contentLocale": "en-US",
  "metadataFilters": [
    {
      "key": "Category",
      "valueFilter": {
        "values": [
          "Screencasts"
        ],
        "negative": false
      }
    }
  ],
  "priors": [
    {
      "key": "Version",
      "value": "latest",
      "weight": 2
    }
  ],
  "facets": [
    {
      "key": "version",
      "order": "ASC"
    }
  ]
}

Response body

{
  "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",
          "topic": {}
        }
      ]
    }
  ],
  "lastModified": {
    "from": "2022-01-01",
    "to": "2022-09-30"
  },
  "paging": {
    "currentPage": 1,
    "totalResultsCount": 165,
    "totalClustersCount": 114,
    "isLastPage": false
  }
}

Field	Type	Description
`spellcheck`	Object	The string displayed in the suggestion box. A specific HTML class is attributed to the suggested term.
`facets`	Array	Identifies the facets with their ID and their display name. Gives each facet types: hierarchical or multi-select. If the facet is hierarchical, parent facets appear in `rootNodes` elements and their child facets are in the `childNodes` elements. See Hierarchical facet output.
`results`	Array	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: `TOPIC` `MAP` `DOCUMENT` `entries` elements depend on the `type`.
`paging`	Object	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.

Clustered search - Fluid Topics - Latest

Fluid Topics API Reference Guide