Skip to main content

Search Results

This page documents the output data in one of three formats: 1) by ID, 2) search results, or 3) suggestion request.

By ID​

The output from a by-ID request is an object with the following properties:

  • item <HunchItem | null> - The item, or null if not found.
info

For request results by ID, the HunchItem has _chunks set instead of _chunk.

The output from a Hunch search is an object with the following properties:

Suggestion​

The output from a Hunch suggestion request is an object with the following properties:

Example:

{
    "suggestions": [
        { "q": "march madness", "score": 12.709 },
        { "q": "marching shoes", "score": 5.324 }
    ]
}

Types​

The object type definitions are as follows:

HunchChunk​

Each document (Markdown file) can be split into one or more "chunks". Each chunk has the following potential properties:

  • name <String> - The name of the chunk, if named.
  • id <String> - The identifier of the chunk, if an ID is set.
  • metadata <Any> - If metadata is set on the chunk, it will be that value.
  • content <String> - The text contents of the chunk.
info

The chunks are split using Blockdown syntax by default. See the configuration documentation for more details.

HunchFacets​

This is a map of facet keys to a HunchFacetValues map.

Example: this whole object is a HunchFacets object, containing two HunchFacetValues objects.

{
    "series": {
        "Animals": { "all": 21, "search": 6 },
        "Book Reviews": { "all": 17, "search": 3 }
    },
    "tags": {
        "cats":  { "all": 9, "search": 3 },
        "dogs": { "all": 12, "search": 9 }
    }
}

HunchFacetValues​

This is a map of unique metadata values (converted to Strings) from a facet key, to a HunchFacetValue object.

Example:

{
    "cats":  { "all": 9, "search": 3 },
    "dogs": { "all": 12, "search": 9 }
}

HunchFacetValue​

An object containing the number of documents containing this value across all searchable items (as all) and across all paginated results (as search). It has the following properties:

  • all <Integer> - The number of all searchable items that contain this facet value.
  • search <Integer> - The number of items in all search results, pre-pagination, that contain this facet value.

Example:

{
    "all": 9,
    "search": 3
}

HunchItem​

This is an object representing the content document. It has the following properties:

  • _id <String> - This is the filename, e.g. posts/2022-12-29-cats-and-dogs.md
  • _chunk <HunchChunk> - Only present for search results. This is the most relevant HunchChunk for the provided search query.
  • _chunks <Array<HunchChunk>> - Only present for by-ID results. This is the full list of HunchChunks for the item.
  • _score <Float> - The score of the search result, rounded to 3 decimal points, e.g. 0.158 for a weak relevance, or 127.300 for a high relevance.

In addition, any metadata specified as an aggregation or additional stored field will be present.

Example: from a search result.

{
    "series": "Animals",
    "tags": [ "cats", "dogs" ],
    "title": "About Cats & Dogs",
    "_chunk": { "content": "Fancy words about cats and dogs." },
    "_id": "2022-12-29/cats-and-dogs.md",
    "_score": 0.1580
}

Example: from a by-ID request.

{
    "series": "Animals",
    "tags": [ "cats", "dogs" ],
    "title": "About Cats & Dogs",
    "_chunks": [
        { "content": "Fancy words about cats and dogs." }
    ],
    "_id": "2022-12-29/cats-and-dogs.md",
    "_score": 0.1580
}

HunchPagination​

A simple object containing the pagination information. It has the following properties:

  • items <Integer> - The total number of items found, outside of pagination.
  • offset <Integer> - The zero-index pagination offset, e.g. from the search request.
  • pages <Integer> - The total number of pages available.
  • size <Integer> - The page size, either from the search request or the internal default.

Example:

{
    "items": 137,
    "offset": 0,
    "pages": 6,
    "size": 25
}

HunchSuggestion​

An object containing a suggested search query and a relevance score. It has the following properties:

  • q: String - The suggested query string.
  • score: Float - The relevance score, rounded to 3 decimal places.
{
    "q": "march madness",
    "score": 12.709
}