Bloodhound Search is an improved version of Trac Search that uses the Whoosh full text index. It will be enabled by default from version 0.6, until then, you need no manually enable it.
How to enable Bloodhound Search
In versions prior to 0.6, Bloodhound Search is available only for dev configuration. Make sure that Bloodhound was installed using requirements-dev.txt:
pip install -r requirements-dev.txt
Enable bhsearch.* components in trac.ini file and set Bloodhound Search as default search component
[components] ... bhsearch.* = enabled [bhsearch] is_default = true
Upgrading trac environment will create the index and process all of the existing resources:
trac-admin <path_to_trac_environment> upgrade
How to search
BloodhoundSearch is integrated into the quick search box on top of the page. You can search use free text search or combine search with query syntax. Please consider below a few search samples:
- Free text search through multiple fields e.g. "some text"
- Combination of free text and field specific query e.g. "test status:new keyword:starter" (default operator is AND)
- Field specific query e.g. "status:new keyword:starter" (default operator is AND)
- Boolean queries e.g. "test OR (status:new and keyword:starter)"
- Use meta-keywords e.g. "some text $resolved". Read more in Meta-keywords chapter
- Search tickets based on relations e.g. "duplicatedby:*"
For more information on query syntax see wiki:Proposals/BEP-0004/ResourceQuery.
Bloodhound Search provides basic faceting functionality. Facets are specific for each resource type. More complex faceting can be introduced later, for example: date rages, pivot faces etc.
Common fields for all resources
- id - resource id. For ticket it is ticket id, for wiki it is wiki page name.
- type - resource type e.g. ticket, wiki, milestone etc.
- time - resource change time
- author - resource author. For ticket it is ticket reporter.
- content - ticket description, wiki page content
Ticket specific fields
- changes - ticket comments
Milestone specific fields
- status - possible values are "completed" or "open"
- due - milestone due value in date-time format
Relation specific fields
- any other custom relation type defined in trac.ini
Meta-keywords are shortcuts for commonly used query expressions. Meta-keywords start with "$" character. Bloodhound Search supports the following meta-keywords:
- $resolved - resolved to status:(resolved OR closed) query
- $unresolved - resolved to NOT $resolved query
- $ticket, $milestone, $wiki - resolved to type:ticket|milestone|wiki query
- $me - resolved to currently logged in user name
- $my - resolved to owner:$me
URL query parameters
Bloodhound Search supports the following URL query parameters:
- q - query string, for example: .../bhsearch?q=test
- type - type of resource to search in. Currently, supported types are ticket, wiki and milestone, for example: .../bhsearch?type=ticke
- fq - filter query. Filter queries are not boosted and used to additionally filter search output. Bloodhound Search joins multiple filter queries using AND operator, for example: .../bhsearch?fq=status:"new"&fq=component:"c1" results to filter query: status:"new" AND component:"c1"
- pagelen - number of rows that should be returned in a single page, for example .../bhsearch?pagelen=20. Default pagelen value is 10
- page - number of page in the current result set that should be returned
- view - the parameter specify hor search results should presented. Currently supported value is grid. If parameter is missing, free text presentation will be used. Usage sample: view=grid
- sort - specifies search results sorting. By default, results are sorted by relevance score and resource time (sort=score, time desc).
- A sort parameter must include a field name (or the pseudo-field score), optionally followed by whitespace (escaped as + or %20 in URL strings) and followed by a sort direction (asc or desc). If if direction is missing, asc is used by default.
- Multiple sort orderings can be separated by a comma, ie: sort=<field name>+<direction>[,<field name>+<direction>]... For example: sort=component, milestone desc