Getting started with the data model
Managed by | Updated .
The data model is the structure returned by the JSON (search.json) and XML (search.xml) endpoints. The 3 main top-level nodes are:
- question: contains all the input parameters needed to run the search
- response: contains the search results and associated data (facets, etc.)
- error: contains an error message if the search failed
This page gives an overview of the most commonly fields used withing the question and response nodes, needed to implement a standard search results page when integrating with the JSON or XML endpoint.
For more details about the data model, see the official documentation page. See also the complete data model reference with the list of all existing nodes.
It is highly recommended to install a browser extension to pretty-print JSON and XML, to make it easier to explore the data model.
Most commonly used question fields
| Item | Name | Description |
|---|---|---|
| 1 | originalQuery | Search keywords as entered by the user. Useful to display messages like "10 results for <originalQuery>" |
| 2 | selectedFacets | Name of the currently selected facets (e.g. "Tabs", or "Product category"). Useful to know if a facet has been selected, regardless of its value |
| 3 | selectedCategoryValues | Pair of Key / Value for currently selected facets (e.g. "Tabs = News" or "Product category = Phones"). Useful to show the currently applied filters. |
| 4 | location | May contain information about the users' location derived from their IP address. This may not always be available. |
Most commonly used response fields
| Item | Name | Description |
|---|---|---|
| 1 | resultPacket | Top-level node to obtain results and more |
| 2 | queryAsProcessed | The search keywords as processed by Funnelback. This could differ from question.originalQuery as it will include any additional query item generated by Funnelback, such as synonyms of facet constraints. It may be preferable in some cases to use this node to display the current query being run to indicate to the user how the keywords were processed |
| 3 | resultsSummary | Gives a summary of the different result counts (how many results matched, which page the use is currently on, etc.). See corresponding section below |
| 4 | spell | Spelling suggestions |
| 5 | bestBets | Legacy best-bets for pre-v15 Funnelback systems. Please ignore on recent systems and use the curator node instead |
| 6 | results | List of results returned by the search (See following sections) |
| 7 | resultsWithTierBars | List of results, including tier bars (e.g. results are split in tiers depending how many of the search keywords are matching) |
| 8 | contextualNavigation | Contextual navigation / related searches data |
| 9 | queryHighlightRegex | A regular expression to use to highlight the search keywords in the results titles, metadata and summaries. Especially useful for the results readability, to indicate to the user why a specific result matched their search keywords |
| 10 | facets | List of facets / filters relevant to the current search |
| 11 | curator | Curator and Best Bets messages relevant to the current search |
Results summary fields
The results summary contains information used to display result counts (e.g. "Showing result 1 - 10 out of 3,240 for <query>") and implement pagination.
| Item | Name | Description |
|---|---|---|
| 1 | fullyMatching | How many search results match the entire search keywords. For example with the search keywords "chocolate cake recipe", only 11 documents may match those 3 words, but 44 documents may match "recipe" |
| 2 | partiallyMatching | How many search results contain some of the search keywords, but not all. |
| 3 | totalMatching | The total number of search results found (fullyMatching + partiallyMatching) |
| 4 | estimatedCounts | Indicate if the result counts are estimated or exact. Counts may be estimated on large indexes. If that is the case, it is recommended to surface this information to the user in the front-end (e.g. "About 3,200 results for <query>" as opposite to "3,214 results for <query>" where 3,214 is an estimate) |
| 5 | numRanks | The number of results on each page |
| 6 | currStart | The offset of the first result on the current page. For example when viewing the first page of result, this will be 1. When viewing the 3rd page, with 10 results per page (numRanks), this will be 21 |
| 7 | currEnd | Similar to currStart, the offset of the last result on the current page. For example when viewing the first page of results, this will be 10. When viewing the 3rd page, with 10 results per page (numRanks), this will be 30 |
| 8 | prevStart | The offset of the first result on the previous page of result. This is unset on the first result page, and for example on the 3rd result page this will be 11 |
| 9 | nextStart | The offset of the first result on the next page. For example when viewing the first page of results this will be 11, and 31 on the 3rd page of results |
Individual result fields
| Item | Name | Description |
|---|---|---|
| 1 | results | Top-level results list. Usually contains 10 results objects |
| 2 | title | Result title |
| 3 | liveUrl | The URL of the result |
| 4 | summary | The result summary or snippet. This summary can be processed with response.resultPacket.queryHighlightRegex to highlight the search terms within the summary |
| 5 | cacheUrl | URL to obtain the cached copy of the result from Funnelback |
| 6 | date | Timestamp associated with the result, usually from a date metadata. May be empty if no date was available |
| 7 | fileSize | Result document size |
| 8 | fileType | Result document type (html, pdf, docx, etc.) |
| 9 | metaData | Key / Value pair for each metadata associated with the result (e.g. "productCategory = phone"). Note that if a metadata field has multiple values, they will be separated by the pipe character "|" |
| 10 | displayUrl | The URL to display to the user for this result. This may differ from the liveUrl because of internal transformations. Prefer to use this field to display the result URL in the front-end |
| 11 | clickTrackingUrl | The URL to use for clicking on the result, so that Funnelback can track the click in Analytics. This URL will record the click then transparently redirect the user to the original result URL. |
| 12 | indexUrl | Internal URL of the result within the search index |
Facets fields
Facets are used to provide results filtering, as well as tabs.
| Item | Name | Description |
|---|---|---|
| 1 | facets | List of facets configured on the search |
| 2 | name | Name of the facets (e.g. "Tabs", or "Product Category") |
| 3 | categories | List of categories configured for the facet. This list may contain a single entry, with multiple values inside (see next row), or multiple entries with a single value inside, depending on the facets configuration. |
| 4 | values | List of values for the facet and category (e.g. the actual list of tabs, or list of product categories: "Phone", "Tablet", etc.). |
| 5 | data | Data for the value, the actual data matched on the search index |
| 6 | label | Label for the value, to display in the front-end |
| 7 | count | An estimate of how many search results are present for this value |
| 8 | queryStringParam | The URL constraint to use to select this value. To select the value, use the current search URL and append the queryStringParam to it. |
| 9 | selected | Indicates if this value is currently selected or not. Useful to display a value as "active" in the front-end |
| 10 | categories | List of sub-categories, for nested facets. Usually empty on simple facet setups. |
Was this artcle helpful?
Latest In this section
- Replace diacritic (accented) characters
- Accessing data model variables that start with a single lower case letter
- Adding numeric metadata constraints via a hook script
- Modifying geo-spatial parameters in the data model (origin, maxdist)
- Storing custom data within the data model
- Writing hook script code for specific search types