Simple search API proposal, take 2

[Jean-Francois Dockes]

Just a few opinions/comments/votes on recent issues:

- Need for a query-closing call and backend resource management issues: It
  is up to the backend to manage its resources, and decide how processing
  should be split between Query() and GetHitProperties().  

  To make things easier, I am in favour of a CloseQuery() call which
  well-behaved applications will use, and also of specifying that
  query_handles can become stale, and that applications should then restart
  the query (which opens the question of error reports which is still a
  blank area). 
  
  I do not think that there is a need for an explicit timeout value.

- CountHits() / GetHitproperties() racy-ness: It is up to the backend to
  maintain consistency inside a single opened query, the current interface
  allows it (unlike the previous one using the query string as a bad
  query_handle).

  Ideally the Query() call would open some kind of database snapshot which
  would be preserved as long as the query_handle is valid. This may be
  feasible or not with the current backends, which are expected to just "do
  their best", which the current draft does not prevent. Aren't things such
  as CountHits() usually considered to only return estimates anyway ?

- GetHitProperties result list as map or sequence: as Fabrice wrote, the
  object identifiers are not useful. The results are requested as slices
  from of an ordered list (offset/limit), and should be returned as a
  simple sequence or array of (propertyName=>propertyValue) maps. 

  Magnus' initially proposed the response to be:
   "A map mapping each hit (sequence number) to a map of property-list of
     values pairs." 

  I think that the sequence number can be kept implicit:

    Query (in s query_string, out i query_handle)
    GetHitProperties ( in s query_handle, in i offset, in i limit, 
                       in as properties, out (sequence of maps) response )

  (Sorry I'm not too sure about the correct syntax for "sequence of maps",
   it would be nice if someone knowledgeable could state the proper dbus
   data definition syntax.)

- Getting a list of URIs: use:
    GetHitProperties(query_handle, offset, limit, ["URI"])

- Using URI as key: as previously stated I think that this is a bad idea.

- Accessing Snippets individually: no need for GetSnippets(), use:
  GetHitProperties(query_handle, offset, 1, ["Snippet"])

Regards,
J.F. Dockes