Customising Search

FAIR search is configured by default to map to the Standard Catalogue template available in all FAIR hubs.

However, where a hub owner has introduced one or more custom catalogue templates, they may want to update their search configuration to include fields from the new catalogue.

This article details how the search configuration can be managed and updated.

Search Configuration Endpoints:

Users with the appropriate permissions can customise the search config via the FAIR API using the following endpoints:

API Endpoint	Description
`GET search/configurations/`	Returns all available search configurations within a hub
`POST search/configurations/`	Post a new search configuration
`GET search/configurations/{code}`	Returns a specific search configuration using code
`PUT search/configurations/{code}`	Update an existing search configuration using code
`DELETE search/configuration/{code}`	Allows the user to delete an existing search configuration
`GET search/configurations/{code}/uiconfig`	Returns the uiconfig for a specific search configuration using code

A hub can have multiple available search configurations, but only one can be active. This can be managed via the following endpoints:

API Endpoint	Description
`GET /configurations/{code}`	Using the code `default-search-config' will return the current active search configuration
`PUT /configurations/{code}`	Used to update the default search configuration

Search Configuration

The search configuration has two main elements, fields and uiconfig, which contains elements and facets.

fieldsdetermines which catalogue fields will be mapped in the search configuration
elements under uiconfig this determines which features of the search tab are enabled
facets under uiconfigdetermines how the mapped fields are displayed as facets in the UI

The current default search configuration contains all of these elements and is shown below:

    {
    "name": "Example Search Configuration",
      "fields": [
        {
          "name": "keyword",
          "type": "strings",
          "mapping": "catalogue/keyword"
        },
        {
          "name": "publisher",
          "type": "string",
          "mapping": "catalogue/publisher/name"
        },
        {
          "name": "author",
          "type": "string",
          "mapping": "catalogue/creator"
        }
      ],
      "uiconfig": {
        "elements": [
          {
            "name": "searchbox",
            "enabled": true
          },
          {
            "name": "sidebar",
            "enabled": true
          },
          {
            "name": "dropdown",
            "enabled": true
          }
        ],
        "facets": [
          {
            "name": "keyword",
            "label": "Keywords",
            "config": {
              "count": 10,
              "sort": "count"
            },
            "enabled_sidebar": true,
            "enabled_dropdown": true
          },
          {
            "name": "publisher",
            "label": "Publisher",
            "enabled_sidebar": true,
            "enabled_dropdown": true
          },
          {
            "name": "author",
            "label": "Author",
            "enabled_sidebar": true,
            "enabled_dropdown": true
          },
          {
            "name": "request_enabled/supported",
            "label": "Access Request Supported?",
            "enabled_sidebar": true,
            "enabled_dropdown": false,
            "permission": "requests.create"
          },
          {
            "name": "query_enabled/supported",
            "label": "Cohort Supported?",
            "enabled_sidebar": true,
            "enabled_dropdown": false,
            "permission": "cohorts.create"
          }
        ]
      }
    }

Fields:

The fields section of the search configuration determines which catalogue fields are indexed, these have the following format:

{"name": "keyword",
"type": "strings",
"mapping": "catalogue/keyword"}

name - the name of the field in search
type - the type of data in the field
mapping - the catalogue field the search maps to

For more complex catalogue field types, such as object, the user may specify which elements of the field are indexed. The publisher field in the default search configuration is an example of this.

In the default catalogue template, the Publisher field has two elements, name and URL:

Publisher .png

Only the name of the publisher is indexed in the default search configuration:

        {
          "name": "publisher",
          "type": "string",
          "mapping": "catalogue/publisher/name"
        },

In this case the mapping details the catalogue field publisher and the specific element from it to be indexed name

We recommend this approach for indexing complex catalogue fields, as it allows users to index the elements of most value and easily create associated facets.

In addition to user defined fields a variety of common details are indexed for all datasets, including their name, description and request status among others.

uiconfig - elements:

The first section of the uiconfig section is elements:

        "elements": [
          {
            "name": "searchbox",
            "enabled": true
          },
          {
            "name": "sidebar",
            "enabled": true
          },
          {
            "name": "dropdown",
            "enabled": true
          }
        ],

This determines which UI elements are visible to users of search. By default the search UI is configure to display the following elements:

search box - free text search box at the top of the page
side bar - the side bar contains search facets as specified by the search configuration
drop down - provides an alternative way of displaying facets as drop down menus below the search bar

uiconfig - facets

The second section of the uiconfig is facets. Facets can relate to two aspects of a dataset:

Catalogue fields
Dataset properties

The default configuration contains examples of both, and further detail of each type is provided below.

Catalogue field facets

In the default configuration publisher is an example of a facet based on a catalogue field:

          {
            "name": "publisher",
            "label": "Publisher",
            "enabled_sidebar": true,
            "enabled_dropdown": true
          }

name - this should be the name of the catalogue field that the facet relates to
label - this is the display name for the facet in the search UI
enabled_sidebar - if true the facet is displayed on the sidebar
enabled_dropdown - if true the facet is displayed as a drop down

These are the minimum required fields for catalogue facet, for details of additional facet options see optional uiconfig below.

Dataset property facets

In the default configuration request_enabled/supported is an example of facet based on a dataset property

          {
            "name": "request_enabled/supported",
            "label": "Access Request Supported?",
            "enabled_sidebar": true,
            "enabled_dropdown": false,
            "permission": "requests.create"
          }

This type of facet relates to facts about the dataset that are not part of the catalogue definition. The default configuration contains three of these:

request_enabled/supported - can the dataset be requested
query_enabled/supported - can cohorts be created from the dataset
conditional_access/supported - does the dataset have any associated conditions

These facets will be relevant to all datasets in FAIR, and we do not recommend customising them.

Optional uiconfig:

In addition to the required uiconfig fields detailed above, users have a number of options that allow them to further customise their search facets. This section provides some examples of this:

Example String UI Configuration with Optional Count and Sort

{ "name": "publisher", "label": "Publisher", "enabled_sidebar": true, "enabled_dropdown": true, "config": { "count": 10 "sort": "-value" } }

'count' can be used to limit the maximum number of results returned by any search.

sort determines the order that results are displayed in. The default value is 'count' which orders the facets in descending order based on the count, but this can also be set to:

-count - orders facets in ascending order based on count
value - orders facets by value in descending order
-value - orders facets by value in ascending order

Example Date UI Configuration with Interval and Timeoffset

{ "name": "published", "label": "Published Date", "enabled_sidebar": true, "enabled_dropdown": false, "config": { "interval": "year" "timeoffset": "+01:00" } }

interval is for date and number fields only, and is used to generate search ranges. In this example the interval is a date, these can be configured to intervals of day and month. For numbers the range is set by integer e.g. '10' will create ranges with intervals in tens.

timeoffset can only be used in conjunction with date intervals, and is used to align the results with a specific timezone. FAIR defualts to UTC, so in this instance UTC 0000 becomes 0100.

Example Number UI Configuration with Values

{ "name": "participants", "label": "Participants", "enabled_sidebar": true, "enabled_dropdown": false, "config": { "values": "100|500|1000|2000" } }

'values' is also only for date and number fields. Where interval generates ranges based on the users input, values allows them to create their own pre-determined bins by entering a pipe-seperated list as shown above. This example would create the following search facets:

0 - 100
100 - 500
500 - 1000
1000 - 2000
2000+

Updated on July 31, 2024

Tagged: