Results format and structure

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.