Results format and structure

Dan Calinescu edited this page Apr 2, 2014 · 30 revisions

The Picky Results

Example

Consider a library search. You search for “Pinchn~”, and Picky has a result with Pynchon in the title.

You get back a JSON formatted string from Picky that looks like this:

{"offset":0, "total":2, "duration":0.000148, "allocations":[["books", 6.0, 1, [["title", "Gravity", "gravity"], ["author", "Pinchn~", "pynchon"]], [27, 53]]]}

What does it all mean?

The format

JSON. A very lightweight data interchange format. Picky is using a very fast, C-based lib (Ruby bindings) to put the JSON strings together. The client is using the same lib to unwrap the JSON-formatted results.

The structure

Note: If you use the Picky client and frontend JS, you never need the JSON directly.

Picky gives you a hash:

{
  offset: 0 // The results have this offset. An offset of 10 will omit the first 10 ids and
            // give you ids from the 11th position and up.
  total: 1 // The total amount of results found, covering all allocations.
  duration: 0.000807 // How long it took Picky to find the results. Rack time, transfer time,
                     // and HTTP header adding not included. Just the time it took Picky itself to find the result.
  allocations: // An array of possible allocations of search terms to categories (see below). Using the example above we get:
    [
      ["books", // The index name.
        6.0, // The score of the result. Allocations are ordered by their scores (which includes the boost).
        2, // The total of ids in this allocation.
        [
          [
            "title", // Name of the category of the following search terms.
            "Gravity", // The original search term (upper case and all).
            "gravity" // The search term as picky interpreted it.
          ],
          [
            "author", // Name of the category of the following search terms.
            "Pinchn~", // The original search term (upper case and all).
            "pynchon" // The search term as picky interpreted it.
          ],
          ... // More search terms in this allocation.
        ],
        [
          27, // An array of the found ids. Up to 20 per default, or more or less if you define otherwise.
          53
        ],
      ],
      ... // More allocations, ordered by score, descending.
    ]
}

That’s it. Simple and easy to remember :)

What is an allocation?

It’s a number of results, with additional metadata:

  • Which index it came from. (Helpful if you use multiple indexes in a Query)
  • What score it has.
  • How many results are in this allocation.
  • The core of the allocation: What search terms were found in which categories. In the example below, both terms were found in the title.
  • An array of ids. Up to 20, by default.

An example allocation

Say you’ve searched for “Pinchn~ Novel”. You’ll get an allocation from Picky, like this:

["books", 7.39, 1, [["title", "Pinchn~", "pynchon"], ["title", "Novel", "novel"]], [27]]
  • "books": The name of the index this allocation is coming from.
  • 7.39: The score of this allocation. You can increase this by setting boosts in the Query configuration, see Query Configuration.
  • 1: The number of results.
  • [["title","Pinchn~","pynchon"],["title","Novel","novel"]]: Search terms with categories and Picky-interpreted terms. They are ordered as the user entered them:
    • "title": The category where “pynchon” has been found.
    • "Pinchn~": The original search term the user entered.
    • "pynchon": The search term that has been normalized by Picky. This one can be reused for a future query, as the interface actually does.
  • [27]: An array of ids.

Help!

If all this sounds complicated, it really isn’t.

Just take a look at the results that Picky returns, using FireBug on the simple example. I think that helps.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.