| = Bloodhound Search = |
| |
| Bloodhound Search is currently in prototype phase. Read more about proposed functionality on [wiki:Proposals/BEP-0004 BEP-0004] |
| |
| == How to enable Bloodhound Search== |
| Currently, 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 |
| }}} |
| |
| Run initial index rebuild using trac-admin command line tool. TODO: reindexing using admin web interface should be supported later |
| {{{ |
| trac-admin <path_to_trac_environment> bhsearch rebuild |
| }}} |
| |
| == How to search == #search |
| Click Apps menu and select Bloodhound Search item. 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 Meta-keywords] chapter |
| For more information on query syntax see wiki:Proposals/BEP-0004/ResourceQuery. |
| |
| Currently, you can search in tickets, wiki pages and milestones (later more resources will be added). Use All | Ticket | Wiki | Milestone tabs to search entries of specific type. |
| |
| 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. |
| |
| == Supported fields #fields |
| === 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 |
| * component |
| * status |
| * resolution |
| * keywords |
| * milestone |
| * summary |
| * changes - ticket comments |
| |
| === Milestone specific fields |
| * status - possible values are "completed" or "open" |
| * due - milestone due value in date-time format |
| |
| == Meta-keywords #meta-keywords |
| Consider Bloodhound Search meta-keywords as shortcuts for commonly used query expressions. Meta-keyword starts 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}}} |
| {{{ |
| #!comment |
| Add wiki macro in order to automatically generate list of supported meta-keywords and help description |
| }}} |
| |
| == URL query parameters #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}}} |
| |
