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

ItemNameDescription
1originalQuerySearch keywords as entered by the user. Useful to display messages like "10 results for <originalQuery>"
2selectedFacetsName of the currently selected facets (e.g. "Tabs", or "Product category"). Useful to know if a facet has been selected, regardless of its value
3selectedCategoryValuesPair of Key / Value for currently selected facets (e.g. "Tabs = News" or "Product category = Phones"). Useful to show the currently applied filters.
4locationMay contain information about the users' location derived from their IP address. This may not always be available.

Most commonly used response fields

ItemNameDescription
1resultPacketTop-level node to obtain results and more
2queryAsProcessedThe 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
3resultsSummaryGives a summary of the different result counts (how many results matched, which page the use is currently on, etc.). See corresponding section below
4spellSpelling suggestions
5bestBetsLegacy best-bets for pre-v15 Funnelback systems. Please ignore on recent systems and use the curator node instead
6resultsList of results returned by the search (See following sections)
7resultsWithTierBarsList of results, including tier bars (e.g. results are split in tiers depending how many of the search keywords are matching)
8contextualNavigationContextual navigation / related searches data
9queryHighlightRegexA 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
10facetsList of facets / filters relevant to the current search
11curatorCurator 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.

ItemNameDescription
1fullyMatchingHow 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"
2partiallyMatchingHow many search results contain some of the search keywords, but not all.
3totalMatchingThe total number of search results found (fullyMatching + partiallyMatching)
4estimatedCountsIndicate 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)
5numRanksThe number of results on each page
6currStartThe 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
7currEndSimilar 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
8prevStartThe 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
9nextStartThe 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

ItemNameDescription
1resultsTop-level results list. Usually contains 10 results objects
2titleResult title
3liveUrlThe URL of the result
4summaryThe result summary or snippet. This summary can be processed with response.resultPacket.queryHighlightRegex to highlight the search terms within the summary
5cacheUrlURL to obtain the cached copy of the result from Funnelback
6dateTimestamp associated with the result, usually from a date metadata. May be empty if no date was available
7fileSizeResult document size
8fileTypeResult document type (html, pdf, docx, etc.)
9metaDataKey / 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 "|"
10displayUrlThe 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
11clickTrackingUrlThe 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.
12indexUrlInternal URL of the result within the search index

Facets fields

Facets are used to provide results filtering, as well as tabs.

ItemNameDescription
1facetsList of facets configured on the search
2nameName of the facets (e.g. "Tabs", or "Product Category")
3categoriesList 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.
4valuesList of values for the facet and category (e.g. the actual list of tabs, or list of product categories: "Phone", "Tablet", etc.).
5dataData for the value, the actual data matched on the search index
6labelLabel for the value, to display in the front-end
7countAn estimate of how many search results are present for this value
8queryStringParamThe URL constraint to use to select this value. To select the value, use the current search URL and append the queryStringParam to it.
9selectedIndicates if this value is currently selected or not. Useful to display a value as "active" in the front-end
10categoriesList of sub-categories, for nested facets. Usually empty on simple facet setups.
Was this artcle helpful?

Comments