Search documents - Fluid Topics - Latest

Fluid Topics API Reference Guide

Category
Reference Guides
Audience
public
Version
Latest

This web service lets users search unstructured documents. It returns unclustered 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.

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

Method Endpoint
POST /api/khub/documents/search
Query string parameter Type Required? Description
page Number No Expects the page number. Starts at 1 and defaults to 1.
per_page Number No Expects the number of results per page. Defaults at -1, meaning that all results are returned. 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 a document's ft:lastTechChange metadata. If unspecified, the default value is 1970-01-01.
to String No The inclusive end date of the period. If unspecified, the default value is the current day.
  • It is possible to use pagination with this web service.
  • Using pagination when searching documents 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.

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

Return code Description
200 OK Returns 0 or more results.
400 BAD REQUEST Invalid JSON request body.
500 INTERNAL SERVER ERROR The Query Manager failed to respond.

Request body

The following lines display an example of a JSON request body:

{
  "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": "ASC"
      },
      {
        "key": "$FACET_ID_2",
        "order": "DESC"
      }
    ],
    "lastModified": {
      "from": "2022-01-01",
      "to": "2022-09-30"
    },
    "paging": {
        "page": 1,
        "perPage": 20
    }
}

The JSON request body expects the following fields:

Field Type Required? Description
query String No Expects the string query used to return matching publications. If not set, an empty search is queried.
contentLocale String Yes Expects the content language ISO codes (language and country). If not set, the query fails. If set with an unknown value, Fluid Topics attempts to correct the value. For example, Fluid Topics replaces fr by fr-FR.
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 Filters 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 Array No Specifies 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 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 Array No 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.
lastModified Object No Restricts results to those with a value for the ft:lastTechChange metadata that is in the specified period.
from String No The inclusive start date of the period. If unspecified, the default value is 1970-01-01.
to String No The inclusive end date of the period. If unspecified, the default value is the current day.
paging Object No 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 results per page.

Response body

{
    "spellcheck": {
        "suggestedQuery": "correctedKeywords",
        "htmlSuggestedQuery": "<span class=\"kwicmatch\">correctedKeywords</span>"
    },
    "facets": [
        {
            "key": "ft:isPublication",
            "label": "ft:isPublication",
            "hierarchical": false,
            "multiSelectionable": true,
            "rootNodes": [
                {
                    "value": "true",
                    "label": "true",
                    "selected": false,
                    "totalResultsCount": 1,
                    "childNodes": [],
                    "descendantSelected": false
                }
            ]
        }
    ],
    "results": [
        {
            "documentId": "wuq~8lXw7YHaFWfTkn~CFA",
            "title": "Fluid Topics unstructured document Bar",
            "htmlTitle": "... succession of <span> with .kwicstring or .kwicmatch CSS classes ...",
            "htmlExcerpt": "... succession of <span> with .kwicstring or .kwicmatch CSS classes ...",
            "filename": "bar-ud.jpg",
            "mimeType": "image/jpeg",
            "metadata": [
                {
                    "key": "dataset",
                    "label": "dataset",
                    "values": [
                        "test-checking-publication-types"
                    ]
                },
                {
                    "key": "cdata:openMode",
                    "label": "cdata:openMode",
                    "values": [
                        "fluidtopics"
                    ]
                }
            ],
            "source": {
                "id": "source_42",
                "name": "My_source",
                "type": "${source_type}",
                "description": "This is the source through which I retrieve content"
            },
            "lastEditionDate": "2020-11-24",
            "openMode": "FLUIDTOPICS",
            "originUrl": "http://origin-url/...",
            "documentUrl": "https://api.my_site.fluidtopics.net/khub/documents/:documentId/topics/:contentId",
            "contentUrl": "https://api.my_site.fluidtopics.net/khub/documents/:documentId/content",
            "viewerUrl": "http://my_site.fluidtopics.net/v/u/Fluid-Topics-unstructured-document-Bar"
        }
    ],
    "lastModified": {
      "from": "2022-01-01",
      "to": "2022-09-30"
    },
    "paging": {
        "currentPage": 1,
        "totalResultsCount": 1,
        "isLastPage": true
    }
}

Where:

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