Create references on content of HIT upon search

[bidoubiwa]

In a search response you typically have the following

{
  hits: []
  query: ""
}

Inside hits you have multiple hit. These hit not only have the expected content of the document (id, title in the case of movies for example) but also additional fields depending on your search parameters:

For example _matchesInfo or _formatted.

{
  "id": "50393",
  "title": "Kung Fu Panda Holiday",
  "_formatted": {
    "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year <em>Shifu</em> informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between <em>Shifu</em> and Mr. Ping.",
  },
  "_matchesInfo": {
    "overview": [
      {
        "start": 159,
        "length": 5
      },
      {
        "start": 361,
        "length": 5
      }
    ]
  }
}
 

I think the content of hit should be described atleast in the API references.

[maryamsulemani97]

closing as the content of hit is documented in the Search API reference

[dichotommy]

@maryamsulemani97 I'm not convinced that this issue should be closed. I'm pretty sure there's still no comprehensive explanation of the hits array on the docs. This is all I could find currently:

We don't need much, but we do need more than "results of the query" (and I also find the type [result] to be confusing—will open a PR for that later today).

Basically, we need to explain that the elements of the hits array are not exactly identical to the originally added documents: they may contain additional attributes (i.e. _matchesInfo and _formatted) based on the provided search parameters. This is pretty easy to miss or misunderstand at the moment.

I also think that any explanation of the search response is incomplete without nested sub-fields like _matchesInfo and _formatted. Unfortunately, tables (like shown above) are not great for representing depth within objects 😓

Is this summary accurate in your opinion @bidoubiwa ?

[bidoubiwa]

Exactly my thoughts @dichotommy

[dichotommy]

Closed in favor of newer issue #1626

Will still be done! Never fear 🦁