Beagle Query Syntax

Search Syntax

By default beagle:/ searches only in files. The type of data to search can be specified in the hostname part as shown below:

To search in files, use beagle://file/query.
To search in emails, use beagle://email/query.
To search in bookmarks and browsing history, use beagle://link/query.
To search everywhere, use beagle://all/query.

Beagle supports a search syntax similar to the major search engines you are probably familiar with. If you see too many results for a query, consider refining your search.

Required words: By default, Beagle will return results containing all of the words you specify, with the exception of common "stop words" such as "a", "the", and "is".

Phrases: To search for specific phrases (one word next to another), place the words in quotation marks. For example:

"White Album"

Partial words: Beagle supports partial word searches using asterisks as wildcards. For example, to find words like "black", "blackbird", and "blacksmith":

black*

Excluding words: To exclude a word or phrase from your search, prefix it with minus sign ("-"). For example, to find items with "Beatles" but not the word "George":

Beatles -George

Optional words: To indicate that the word A or word B be in results, use OR, i.e. to find items which contain either "George" or "Ringo" (or both). The OR is case-sensitive.

George OR Ringo

Date queries: (Added post 0.2.16) Beagle allows querying for items with a particular date or within a date range. The queries look like

`date:d1`	On date d1
`date:d1-d2`	From date d1 to d2, both inclusive
`date:-d2`	On or before date d2
`date:d1-`	On or after date d1

where, d1 and d2 are specified as

Year with 4 digits

date:2007 denotes year 2007

YearMonth with 4 digits year, 2 digits month

date:200612-2007 denotes the range December, 2006 to end of 2007

YearMonthDate with 4 digits year, 2 digits month and 2 digits date

date:-20050119 denotes any date on and upto 19th January, 2005

Searching file extensions: You can use either *.mp3 or ext:mp3 to search for documents by file extension. (In this example, MP3s.)

Uri queries: You can retrieve all indexed metadata about a particular URI. For file paths, remember to correctly convert it to a URI (by escaping certain characters and using file:// as the prefix). This can be used for any URI indexed by beagle e.g. URIs for email results, for browsing history, for notes etc.

uri:file:///home/user/somefile

uri:http://beagle-project.org

uri:knotes:///abcd

Property queries: By default, Beagle looks for your search terms in the text of the documents and their metadata. If you want to search for a specific property, use the format property:keyword. Property queries follow all the rules mentioned above; so you can search for properties by phrase, using wildcards, exclude terms, or provide optional terms. For example, the following query will return all of your Beatles MP3s or Ogg/Vorbis files that aren't on the Abbey Road album:

artist:Beatles ext:mp3 OR ext:ogg -album:"Abbey Road"

Beagle allows additional filters and backends to be written as plugins. These plugins might define additional properties for querying. You can find a list of supported properties by running beagle-query --keywords. Here is a list of properties defined in beagle:

property	applies to	description
title	Document	Title of document, mapped to dc:title e.g. title tag of HTML files
creator	Document	Creator of the document, mapped to dc:creator e.g. creator of PDF files
author	Document	Author of the document
summary	File	Brief description of the content, mapped to dc:subject
artist	Music file	Name of artist
album	Music file	Name of album
genre	Music file	Genre of music
mailtoaddr	Email	Email address of receipient
mailto	Email	Name of receipient
mailfromaddr	Email	Email address of sender
mailfrom	Email	Name of sender
mailinglist	Email	Id of mailing list e.g. <dashboard-hackers.gnome.org>
speakingto	Chat	Speaker
email	Addressbook	Email address
imagetag	Image file	IPTC keywords and F-Spot, Digikam image tags
imagecomment	Image file	Comments and descriptions found in image including IPTC caption, Exif comment
imagemodel	Jpeg image	Model of camera e.g. EOS2D
inarchive	File	Use `inarchive:true` to search in archive contents
inattachment	Email	Use `inattachment:true` to search in email attachments
pkggroup	Package	Group to which the package belongs e.g. Configuration

Improving search scope: Beagle indexes data of different kinds and from various sources. If you are getting too many results, you can improve the scope of your query by specifying the type or origin of the results. The syntax is similar to Property query. The meaning of source, hittype, filetype, mimetype is explained in Search Results.

keyword	description
source	Source of the content e.g. `source:EvolutionDataServer` to search in EDS calendar and contact entries
type	Hittype of the content e.g. `type:IMLog` to search in chat logs
filetype	Specific type for file results e.g. `filetype:image` to search in image files
mimetype	Mimetype of the content e.g. `mimetype:text/plain` to search in files with mime-type text/plain

Expressions for date queries, extension queries, property queries, uri queries and limiting search scope can be used with - (to exclude all hits matching that expression) and OR (optional matching).