Skip to content

Results format and structure

floere edited this page Oct 19, 2010 · 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:

{"offset":0,"total":1,"duration":0.022148,"allocations":[["books",6.0,1,[["title","Pinchn~","pynchon"]],[27]]]}

The format

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

The structure

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 weight of the result. Allocations are ordered by their weights.
        [
          "title", // 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 weight, 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 weight 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.

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 weight of this allocation. You can increase this by setting weights in the Query configuration, see Query Configuration.
[[“title”,“Pinchn~”,“pynchon”],[“title”,“Novel”,“novel”]]: Search terms with categories and Picky-interpreted terms. They are ordered as the user entered them. Described below:
“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.