Funnelback data model

The data model is used with the Modern UI. It’s the structure holding all the data related to a single search transaction. It’s composed of:

  • A question, containing all the input parameters needed to run the search

  • A response, containing results

  • An error, containing any error message if the search wasn’t successful.

  • Extra searches, each of which have an equivalent question and response element.

The search lifecycle

When a search query runs the data model is progressively built over a number of search lifecycle phases. This includes setting up the question element based on the` input CGI parameters and configuration and the response element based on the XML response from the query processor.

See: search lifecycle for information on the search lifecycle and how to manipulate the question and response elements.

Various elements in the data model are initialized at different points in the search lifecycle. See: data model variable initialization for information on when various part of the data model are initialized.

Structure

The data model is basically a tree:

- question
 + query
 - collection
    id: "intranet"
    type: "web"
- response
 + facets
 - resultPacket
  - results
   - {
       title: "First result"
       rank: 1
     }
   - {
       title: "Second result"
       rank: 2
     }
- error

Each node can either be a container containing other nodes (e.g. question, response), or a leaf containing data (e.g. results, id, title). To access a specific value you need to specify its full path from the root, using dots as separator between nodes. For example to access the ID of the collection being searched you’ll use: question.collection.id.

Due to the JavaBeans specifications, accessing fields whose name starts with 2 consecutive upper case letters is different from the generic case: You must use the original name in this case, i.e. response.resultPacket.GScope or response.resultPacket.QSup (And not gScope or qSup). For standard properties that don’t start with 2 upper case letters, use the standard syntax, i.e. response.resultPacket

The values can be of different types:

  • String (e.g. The title of a result)

  • Number (e.g. The rank of a result)

  • Date (e.g. The date of a result)

  • List, also called sequences (e.g. The list of search results, within the result packet).

Knowing the type of a value is necessary when you need to format it, or test for it within a condition. Some FreeMarker built-ins will only work with Strings (e.g. ?replace("cat", "dog") and others will only work with numbers (e.g. ?round).

Funnelback data model

The extensive documentation of the data model can be found here: Modern UI data model. This documentation is automatically generated from the source code of the data model. Here are some tips to take advantage of this documentation:

  • The documentation layout is divided in 3 frames:

    • The top left frame lists packages. A package is a container for classes.

    • The bottom left frame lists the classes belonging to the currently selected package.

    • The right frame show information about the currently selected class or ''package.

    • Despite the field being marked private, they’re all accessible.

  • The root node of the data model is the SearchTransaction class, contained in the com.funnelback.publicui.search.model.transaction package. It holds the question, response and error object.

  • Each object of the model have a specific type, or class, each class having a set of fields that correspond to a data model node or leaf.

For example, suppose that you want to know more about the following node of the data model: response.resultPacket.resultsSummary. To do so you’ll:

  1. First navigate to the root of the data model, by clicking on the com.funnelback.publicui.search.model.transaction package then on the SearchTransaction class.

  2. On this class, search for the response field, then click on it.

  3. You’ll see that the response field is of type (or class) SearchResponse.

  4. Click on SearchResponse to display the documentation for this class.

  5. In the same fashion, you’ll look for the resultPacket field, from within SearchResponse.

  6. You’ll see that its type is ResultPacket, then click on it.

  7. Again, search for the resultsSummary field, of type ResultsSummary.

  8. Once you’ve reached the ResultsSummary page, you’ll now be presented with the documentation of this data model node, and see that it contains several leaves (currStart, currEnd, etc.).

Custom data elements

The Funnelback data model has various customData elements that can be used to hold custom data that can then be accessed from hook scripts and Freemarker templates.

  • question.customData: This should be used to hold any custom data that is added before the query runs.

  • response.customData: This should be used to hold any non-specific custom data that is added after the response is returned.

  • result.customData: This should be used to hold any result-specific custom data.

Use result.customData instead of injecting custom data into the result.metaData element as custom fields. Although it is possible to add to the existing element it can be confusing because other features may be dependent on the metaData element and not work as expected if you compare the output to what is in the data model. e.g. if you inject additional metadata fields to hold custom data you can’t then use metadata sorting on these fields (because this happens before the results are returned from Funnelback).