Getting started with the data model

This section provides an introduction to the more useful elements in the data model and is a great place to start when figuring out how to integrate your own application with Funnelback’s JSON or XML output.

Details

The data model is the structure returned by the JSON (search.json) and XML (search.xml) endpoints. The three 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.

Further information on the Funnelback data model.

Install a browser extension that can render JSON so that you can explore the data model more easily.

Most commonly used question fields

Common data model question elements
  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

Common data model response elements
  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.

Common data model results summary elements
  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

Common data model result elements
  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. listMetadata: Key / List pair for each metadata associated with the result (e.g. productCategory = ["phone","tablet"]). Each metadata field will be returned as a list of the different values that match the field.

  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.

Common data model facet elements
  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.

© 2015- Squiz Pty Ltd