[Wasabi Proposal] Live search API

[Magnus Bergman]

On Sun, 21 Jan 2007 01:41:47 +0100
"Mikkel Kamstrup Erlandsen" <mikkel.kamstrup at gmail.com> wrote:

> Here's an actual proposal for unifying the simple and live apis. I'm
> not saying that we really really should do this, just that it is
> doable, and it still allows for quite simple use cases (see below).
> It is actually very much in spirit with Magnus' very first proposal a
> while back. Praise late insight :-)
> 
> == Unified API Proposal ==
> 
> NewSession (out s session)
>  *
> 
> SetProperty (in s session, in s prop, in s val)
>  * Set a property on the session. Prominent ones are
>    - live : whether or not to be in live mode. Default false.
>    - hit.properties : semi colon separated list of field names.
> Default "uri".

Does the (potentially) expensive properties need to be included in
hit.properties, or are they considered special?

> 
> GetProperty (in s session, in s prop)
>  *
> 
> CloseSession (in s session)
>  * Close the session and all child searches
> 
> Search (in s session, in s query_xml, out s search)
>  * Start a new search from a query
> 
> CountHits (in s search, out i count)
>  * Returns the current number of found hits. If live=false this call
> blocks until the index has been fully searched.
> 
> GetHits (in s search, in i num, out aav hits)
>  * Return num hits. If live=false this call blocks until there is num
> hits available or the index has been fully searched.
>    The client should keep track of each hit's serial number if it
> want to use GetHitData later.
> 
> GetHitData (in s search, in ai hit_ids, in as properties, out aav
> hit_data)
>  * Get hit metadata. Intended for snippets or modified hits. hit_ids
> are serial numbers as obtained from GetHits.

The GetHits/GetsHitsData functions was a quite elegant solution, I must
say. But one thing isn't clear to me. Can any property be requested
with GetHitsData (restarting the search if needed)? Or just
those that are included in hit.properties? Or perhaps those that are
either expensive *or* included in hit.properties?

Perhaps the "current hit_id" (the implicit offset used in GetHits) could
be a property of the search?

> 
> CloseSearch (in s search)
>  * Close and free a search.
> 
> SIGNAL HitsAdded (in i count)
> SIGNAL HitsRemoved (in ai hit_ids)
> SIGNAL HitsModified (in ai hit_ids)

All in all I'm very happy with this proposal.