Results format and structure

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

The Picky Results


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


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.