Clustered search - Fluid Topics - Latest

Fluid Topics API Reference Guide

Category
Reference Guides
Audience
public
Version
Latest

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

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.

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.
per_page Number No Expects the number of results per page.
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.

  • It is possible to use pagination with this web service.
  • Using pagination when retrieving clusters is recommended.
  • It is possible to specify a period for this web service using either query parameters or fields in the request body. If both methods are used, the values of the query parameters take precedence.
  • 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.
  • When no user credentials are provided in the HTTP header, this web service only returns public results.

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 filters.
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.
filters Array No Filter the results based on metadata values.

The filter array expects the following parameters:
  • key (mandatory).
  • 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 an empty list.
priors Array No
  • Priors prioritize results based on metadata values.
  • Priors are an element of the Taruqa search engine.
  • The priors parameter is incompatible with the sort parameter.
  • The prior array expects the following parameters:
    • key (mandatory).
    • value (mandatory): Defines the value for the given metadata key.
    • weight (mandatory): A positive integer representing the importance of the key/value pair.
Defaults to an empty list.
sort Array No Specifies a custom sort on any metadata.

The sort parameter is incompatible with the priors parameter.

The sort array expects the following parameters:
  • 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 provided to sort by relevance.
  • order (mandatory): 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 returned in the results. 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 array expects the following parameters:
  • 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.
periodFilter Object No The date range applied to the query.
    periodType String No Defines the type of period used to filter the results of the query. Possible values are LAST_WEEK, LAST_MONTH, LAST_YEAR, or CUSTOM.
    period Object No The CUSTOM period if one was defined.
        from String No The start date of the CUSTOM period.
        to String No The end date of the CUSTOM period.
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.

Request examples

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

{
  "query": "foo",
  "contentLocale": "en-US",
  "filters": [
    {
      "key": "Category",
      "values": ["Screencasts"]
    },
    {
      "key": "Version",
      "values": ["2.0"]
    },
    ...
  ],
  "sort": [
    {
      "key": "ft:title",
      "order": "ASC"
    },
    ...
  ],
  "facet": [
    {
      "id": "version"
    },
    ...
  ]
}

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

{
  "query": "foo",
  "contentLocale": "en-US",
  "filters": [
    {
      "key": "Category",
      "values": ["Screencasts"]
    },
    ...
  ],
  "priors": [
    {
      "key": "Version",
      "value": "latest",
      "weight": 2
    },
    ...
  ],
  "facet": [
    {
      "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 are indicated in rootNodes elements and their child facets 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: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.