Beagle

Writing Clients

Applications using beagle can interact with beagle in different ways:

• Directly parse the output of beagle-query. This is done by Peagle.

• Use the C# API. The GNOME-based search tool included in Beagle uses the C# API. A limited version of the API documentation is available online.

• Use the libbeagle C API. The KDE based Kerry uses libbeagle, as well as Nautilus. There are several examples on using libbeagle in beagle repository. The API documentation is available online.

• Use the beagle python module. The pyKDE application yaBi uses the python module to communicate with beagle. Beagle repository has a few example python scripts. Deskbar-Applet has a beagle handler in python as well.

Search Results

A basic knowledge of how beagle works is required for the rest of this page. Read Architecture_Overview for a brief introduction.

The results of a beagle query are a collection of Hits. All the APIs provide methods to obtain information in a hit. A hit contains the following information:

• Uri: The uri of the result. This is a unique identifier to the result and may not be directly meaningful. The meaning of the URI is directly related to the backend. E.g. for the Files backend the URI points to the location of the file on the disk, for the KMail backend the URI points to the location of the message file but for the EvolutionMail backend the URI is an internal url understood by evolution.

• ParentUri: For backends which create multiple entries from a single file (e.g. emails with attachments, archives), this generally points to the physical file.

• Timestamp: The timestamp of the result. The meaning of the timestamp depends on the backend but usually this is the last modified or creation time of the content. For the mail backends, it generally denotes the sent or received time of the mail.

• Score: A relevancy score of the result. Beagle returns the results sorted by their timestamp, latest first and caps the number of results to a decent maximum. Hence, a document with a higher score might be favoured in comparison to another document created later. The score field gives approximate ordering of a result in the set of all returned results.

• Source: The name of the backend producing this result. The list of the available backends can be obtained by beagle-info --list-backends and the list of the currently running backends can be obtained by beagle-info --index-info. The backends currently shipped with beagle are
  • Files
  • EvolutionMail
  • KMail
  • Thunderbird
  • GaimLog
  • Kopete
  • Konversation
  • Opera
  • KonquerorHistory
  • Labyrinth
  • Tomboy
  • KNotes
  • Blam
  • Liferea
  • Akregator
  • KonqBookmark
  • EvolutionDataServer
  • KOrganizer
  • KAddressBook
  • IndexingService
    • The IndexingService backend is used by the Firefox beagle extension for indexing firefox browsing history. However, any application can use this backend to submit data to beagle for indexing.

• HitType: The type of the result. Any backend can produce results with different hit-types and any hit-type can be created by many backends. Backends can create their own hit-types. Some of the common hit-types are
  • File: Denotes all files, set by the Files backend and in the Static indexes.
  • MailMessage: Denotes mail messages. Set by the mail backends EvolutionMail, KMail and Thunderbird. Also, the Files backend sets this type for any mail files found on the disk.
  • WebHistory: Denotes web-browsing history. Set by the KonquerorHistory and the Opera backend and firefox beagle extension.
  • IMLog: Denotes chat conversations. Set by the GaimLog, the Kopete and the Konversation backends.
  • Task: Denotes tasks and TODOs. Set by the KOrganizer backend.
  • Calendar: Denotes events and calendar entries. Set by the KOrganizer and the EvolutionDataServer backend.
  • Bookmark: Denotes bookmark entry. Set by the KonqBookmark backend.
  • Note: Denotes notes. Set by the Tomboy, the Labyrinth and the KNotes backends.
  • FeedItem: Denotes RSS feed results. Set by the Blam, the Liferea and the Akregator backends.
  • Contact: Denotes contact entries. Set the KAddressBook and the EvolutionDataServer backend.

• MimeType: The mimetype of the result. For results based on files (on disk, inside archives or as mail attachments), they denote the mimetype that beagle used for indexing that file. For the non-file results the mime-type may not be meaningful, e.g. results from the KNotes backend, they refer to the mimetype internally used by the backend.

• FileType: Denotes the kind of file for file based results. This is present to facilitate detecting the kind of the file in clients. Clients can always ignore this and explicitly detect the type from the mimetype and other information. Filters can set their own filetypes. The filetypes used by the filters shipped with beagle are
  • document: PDF, word doc, HTML, text files etc.
  • archive: tar.gz, tag.bz, gzipped and zipped archives
  • audio: audio files
  • video: video files
  • image: pictures
  • source: C, C++, Java, C# etc. source files
  • documentation: Chm, docbook and monodoc files

• Properties: A list of properties. Each property has a name and a value. The meaning of the property depends on the backend or the filter that created the result. For a particular backend or filter, there are certain properties which will always be present but in general there are no fixed properties that are always present. If unsure, it is always safe to check if a certain property exists before trying to use it.

• Snippet: A snippet of text showing the occurrence of the query terms in the indexed data. This is not included in the hit, but has to be explicitly retrieved using separate API calls.