Simple DBUS Search Interface
: This page is deprecated. See WasabiSearchLive
This page is only a draft, it is not a final specification.
This page is a part of the unified Wasabi specification. For a more advanced interface see WasabiSearchLive. Theres also a proposal for showing relevant dialogs at WasabiUI.
This page was originally a part of the WasabiDraft page.
The purpose of this interface specification is to provide a simple DBUS API for applications where searching is limited to text entry with only little if any means to modify the query beyond what is entered in the entry. The API must be simple and easy to use for end user-application developers. It is designed to be used directly without any native toolkit wrappers (think a Clinet object in QT/GObject).
There still need to be consensus on a shared query language. Drafting is going on at WasabiQueryLanguage.
Simple Search API
Important Concepts:
query_handle : A query object is identified by a query_handle string - which is an opaque handle that only makes sense to the search engine.
Query ( in s query_string, out s query_handle )
- Start a new query.
query_string: Whether this should be in the simple end user QL or the full XML query language is yet to be defined.
query_handle: Opaque identifier for this query. Used to retrieve hits and other query data.
CountHits ( in s query_handle , out i count )
- Count the number of items that match a particular query. Used for paging and suggestion popups with hit counts.
query_handle: Handle as returned by Query().
count: The number of objects that match the query. The count is not guaranteed to be exact.
GetHitProperties ( in s query_handle, in i offset, in i limit, in as properties, out a{sa{sas}} response )
Get properties for the given hits. URIs and snippets are just properties.
- query_handle: A handle that is used to uniquely identify a search - as return from Query().
- offset: The offset in the result list for the first returned
- result.
- limit: The maximum number of results that should be returned.
- properties: A list of properties to return. An empty list is a
- request for all properties.
- response: A map mapping object_indetifiers to a maps of
- property-list of values pairs.
Close ( in s query_handle )
- Close the given query for any further requests. The search engine can free all resources related to the query.
DEPRECATED org.freedesktop.search.simple
This section is here for historical reasons only
- Open a graphical interface for configuring the search tool.
CountHits ( in s query , out i count )
- Count the number of items that match a particular query. Used for paging and suggestion popups with hit counts.
query: The query being performed.
count: The number of documents that match the query.
Query ( in s query, in i offset, in i limit , out as hits )
- Perform a query and return a list of URIs that match the query.
query: The query being performed.
offset: The offset in the result list for the first returned result.
limit: The maximum number of results that should be returned.
hits: A list if URIs that are the result of the query. The URIs that are returned can be any valid URI and need not be just files on the harddisk. (should we demand that local file URIs start with file://?)
GetProperties ( in as uris, in as properties, out a{sa{sas}} response )
- Get properties for the given files.
uris: A list of uris for which properties should be returned.
properties: A list of properties to return. An empty list is a request for all properties.
response: A map mapping each input uri to a map of property-list of values pairs.
GetSnippets (in s query, in as uris, in as properties, out a{sa{sas}} response)
- Get snippets for a given query for a list of uris.
query: Query to use highlighting matching text
uris: A list of uris for which snippets should be extracted
properties: A list of properties which to return highlighted. An empty list is a request for relevant properties.
response: A map mapping each uri to a map of property-snippet pairs (as the GetProperties method return value). Only the uris that support snippets are returned (ie. passing an image among the input uris might not show up in the returned map). The matching text in each property value is highlighted with <b>match</b>. Any markup in the raw text is escaped.
FabriceColin: since CountHits and GetSnippets involve a query, how about merging both with Query, so that the latter also returns count and a list of snippets ?
MikkelKamstrupErlandsen: Well, I guess it is for performance reasons. There are various scenarios where many queries could be issued very fast and the overhead might be too big (especially for snippets), and example could be runtime result clustering. Also CountHits can be used in a suggestion popup where you list the hit count next to each suggestion. Performing a full query for each suggestion sounds like overkill. I think that Lucene (for example) can generate hit counts much lighter than processing a full query..?
FabriceColin: The thing is that getting an accurate hits count for a query most probably involves running the query. Also, would one want to see how many results match a query without wanting to see the actual results ?
JosvandenOever: For a count query, you dont have to score the matches, which saves cpu time.
MikkelKamstrupErlandsen: Fabrice, paging. Apps can do : "Showing results 1-20 of 517 hits". Also it can be used like suggestion popups like here. Try and type "hest" slowly into the entry.
FabriceColin: Mikkel !
If count is returned by Query, nothing prevents paging. OK so CountHits is probably nice to have after all... I still think Query should return the total number of hits too. MikkelKamstrupErlandsen: Yeah, you are absolutely right Fabrice. I am not against returning the total number of hits in Query, but how would you do it technically? Right now query return an array of uris and that seems like the right thing to my intuition (which has been known to be far out from time to time). Prepend an integer in string form as the first array element (which I don't utterly reject, but am reluctant to accept)?
FabriceColin: The description for CountHits should read "Count the number of files that match a particular query", shouldn't it ?
MikkelKamstrupErlandsen: Changed with s/files/items/.
JamesLivingston: Would it be useful for GetProperties to take an (optional) list of properties to get (returning them all if the list is empty)? If you want only one property for a large number of files, it could potentially save a fair bit of work for the backend gathering it all and marshalling it over dbus.
MikkelKamstrupErlandsen: I think that is a good idea. It does require a standardization of metadata to be useful though. Something that is scheduled at some point later on. The method could still work until the metadata spec is ready, it would just make the call backend dependable - which it is already infact. So +1 from me.
MikkelKamstrupErlandsen: Since no one objected to James' suggestion I added it to the api.
* JosvandenOever: I changed 'files' to 'URIs' in a few places. Also I added a parameter 'properties' to the getSnippets function, because just as for the getProperties call you'll want to avoid working for all properties when you are only interested in a few of them. I'm a bit ambivalent about the getSnippets function. It's something for which you dont really need to communicate with the server with. You could just let the client do the highlighting.
MikkelKamstrupErlandsen: Do you mean that the client could scan the uri itself and extract the snippet? How would a client scan a .doc attachment to a mail and find the snippet that incidentally match only the stemmed search phrase? Btw: Thanks for the cleanups