Help Center

Menu

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.

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. collection: Includes information about the search package that is being queried. This includes the search package ID, faceted navigation definitions, included data sources.

  3. profile: This is the results page ID of the results page that is being queried

  4. form: This is the ID of the template that is applied to the search (only applicable if using the HTML search endpoint).

  5. inputParameters: A map of all the request/CGI parameters supplied with the query.

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. results: List of results returned by the search (See following sections)

  6. contextualNavigation: Contextual navigation / related searches data

  7. facets: List of facets / filters relevant to the current search

  8. 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 (fullyMatching1 + partiallyMatching2)

  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 (numRanks5), this will be 21

  7. currEnd: Similar to currStart6, 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. rank: This indicates the result number.

  3. title: Result title

  4. collection: This is the data source where the result was retrieved from.

  5. liveUrl: The URL of the result

  6. summary: The result summary or snippet.

  7. date: Timestamp associated with the result, usually from a date metadata. May be empty if no date was available

  8. fileSize: Result document size in bytes

  9. fileType: Result document type (html, pdf, docx, etc.)

  10. 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.

  11. displayUrl: The URL to display to the user for this result. This may differ from the liveUrl5 because of internal transformations. Prefer to use this field to display the result URL in the front-end

  12. 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.

  13. indexUrl: Internal URL of the result within the search index

See also