Query
– A search query¶
-
class
Query
(db, querystr)¶ Represents a search query on an opened
Database
.A query selects and filters a subset of messages from the notmuch database we derive from.
Query
provides an instance attributesort
, which contains the sort order (if specified viaset_sort()
) or None.Any function in this class may throw an
NotInitializedError
in case the underlying query object was not set up correctly.Note
Do remember that as soon as we tear down this object, all underlying derived objects such as threads, messages, tags etc will be freed by the underlying library as well. Accessing these objects will lead to segfaults and other unexpected behavior. See above for more details.
Parameters: -
create
(db, querystr)¶ Creates a new query derived from a Database
This function is utilized by __init__() and usually does not need to be called directly.
Parameters: Raises: NullPointerError
if the query creation failed(e.g. too little memory).
NotInitializedError
if the underlying db was notintitialized.
-
SORT
¶ Defines constants that are used as the mode in which to open a database.
- SORT.OLDEST_FIRST
- Sort by message date, oldest first.
- SORT.NEWEST_FIRST
- Sort by message date, newest first.
- SORT.MESSAGE_ID
- Sort by email message ID.
- SORT.UNSORTED
- Do not apply a special sort order (returns results in document id order).
-
set_sort
(sort)¶ Set the sort order future results will be delivered in
Parameters: sort – Sort order (see Query.SORT
)
-
sort
¶ Instance attribute
sort
contains the sort order (seeQuery.SORT
) if explicitely specified viaset_sort()
. By default it is set to None.
-
exclude_tag
(tagname)¶ Add a tag that will be excluded from the query results by default.
This exclusion will be overridden if this tag appears explicitly in the query.
Parameters: tagname – Name of the tag to be excluded
-
search_threads
()¶ Execute a query for threads
Execute a query for threads, returning a
Threads
iterator. The returned threads are owned by the query and as such, will only be valid until the Query is deleted.The method sets
Message.FLAG
.MATCH for those messages that match the query. The methodMessage.get_flag()
allows us to get the value of this flag.Returns: Threads
Raises: NullPointerError
if search_threads failed
-
search_messages
()¶ Filter messages according to the query and return
Messages
in the defined sort orderReturns: Messages
Raises: NullPointerError
if search_messages failed
-
count_messages
()¶ This function performs a search and returns Xapian’s best guess as to the number of matching messages.
Returns: the estimated number of messages matching this query Return type: int
-
count_threads
()¶ This function performs a search and returns the number of unique thread IDs in the matching messages. This is the same as number of threads matching a search.
Note that this is a significantly heavier operation than meth:Query.count_messages.
Returns: the number of threads returned by this query Return type: int
-