Configuring Search

Search Configuration Endpoints:

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

• GET search/configurations/ – List all search configurations
• POST search/configurations/ – Create a new search configuration
• PUT search/configurations/{code} – Update an existing search configuration
• GET configurations/default-search-config – Get the default search configuration
• PUT configurations/default-search-config – Update the default search configuration

Search Configuration

The search configuration has two sections, fields and uiconfig.

This is the current default configuration:

    {
    "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"
          }
        ]
      }
    }

Example field:

Fields determine which catalogue fields within the FAIR instance searchable.

{"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

Required uiconfig:

uiconfig determines which fields are displayed in the search UI, and where they are displayed.

The required fields for the UI config are:

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

• name - the name of the field to be displayed
• label - the display name for the field in the search UI
• enabled_sidebar - If true the field will appear as a facet in the search sidebar
• enabled_dropdown - If true the field will appear as a drop down at the top of the search UI

Optional uiconfig:

In addition to the required UI config values, users can also provide a number of optional configurations: ​

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+

Setting the default configuration

When a new search configuration has been added to FAIR it can be set as default using the PUT search/config/default-search-config endpoint.

The default is set by posting the code of the search config as shown below:

{ "value": { "value": "CODE_OF_SEARCH_CONFIG" } }

Search and custom catalogues

The introduction of custom catalogues to FAIR means that a FAIR instance can have multiple live catalogues, which may have different fields.

Search configurations can contain fields from any catalogue on a FAIR instance.