git.roojs.org Git - web.mtrack/blob - defaults/help/Searching

   1 = Searching mtrack =
   2
   3 mtrack maintains a searchable index of the textual portions of tickets
   4 and wiki pages, so that you can quickly find that elusive note when
   5 you need it.
   6
   7 == Search shortcuts ==
   8
   9 If you type one of the following special strings into the search box
  10 and hit the search button, instead of searching, mtrack will redirect
  11 you to the appropriate page:
  12
  13  !#123::
  14         will take you to the ticket page for that numbered ticket
  15
  16
  17 == Querying the search index ==
  18
  19 A search query may be broken up into a series of search terms and special
  20 operators.
  21
  22 === Terms ===
  23
  24 A query is broken up into terms and operators. There are three types of terms:
  25
  26  Single Term::
  27         is a single word such as "test" or "hello"
  28  Phrase::
  29         is a group of words surrounded by double quotes such as "hello dolly".
  30  Subquery::
  31         is a query surrounded by parentheses such as "(hello dolly)".
  32
  33 Multiple terms can be combined together with boolean operators to form complex
  34 queries.
  35
  36 === Fields ===
  37
  38 When performing a search you can either specify a field to query against, or
  39 leave the field unspecified to query against all possible fields.
  40
  41 You can search specific fields by entering the field name followed by a colon, followed by the term you are looking for.
  42
  43 For example, if you want to search wiki content for the word "search" you might enter the following:
  44
  45 {{{
  46         wiki:search
  47 }}}
  48
  49 If you are looking for a ticket with a particular summary and a specific word
  50 in the description:
  51
  52 {{{
  53         summary:"failed open" description:"file not found"
  54 }}}
  55
  56 Note that the following is not the same as the above, as it will only search
  57 the summary field for the word "failed", the description field for the word
  58 "file" and all the rest of the words will be searched against all of the
  59 possible fields:
  60
  61 {{{
  62         summary:failed open description:file not found
  63 }}}
  64
  65 ==== Available fields ====
  66
  67 ||Item||Field||Purpose||
  68 ||Ticket||summary||The one-line ticket summary||
  69 ||Ticket||description||The ticket description||
  70 ||Ticket||changelog||The changelog field||
  71 ||Wiki||wiki||The content of the wiki page||
  72
  73 === Wildcards ===
  74
  75 You may use single and multiple character wildcard searches within single
  76 terms, but not within phrase queries.
  77
  78 To perform a single character wildcard search, use the "?" symbol.
  79
  80 To perform a multiple character wildcard search, use the "*" symbol.
  81
  82 The single character wildcard search looks for strings that match the term with the "?" replaced by any single character.  For example, to search for "text" or "test" you can use the search:
  83
  84 {{{
  85                 te?t
  86 }}}
  87
  88 Multiple character wildcard searches look for 0 or more characters when
  89 matching strings against terms.  For example, to search test, tests or tester,
  90 you can use the search:
  91
  92 {{{
  93                 test*
  94 }}}
  95
  96 You can use "?", "*" or both at any position of the term, but wildcard matches
  97 require a non-wildcard prefix of at least 3 characters, otherwise the search
  98 will not be allowed to continue.
  99
 100 === Fuzzy Searching ===
 101
 102 You may append the tilde "~" character to a search term to specify
 103 that a fuzzy search be used, based on the Levenshtein Distance between
 104 similar words.
 105
 106 To search for a word similar in spelling to "roam":
 107
 108 {{{
 109                 roam~
 110 }}}
 111
 112 The above will find terms like "foam" and "roams".
 113
 114 Additional (optional) parameters can specify the required similarity, with
 115 possible values being fractional numbers between 0 and 1.  As this parameter
 116 gets closer to 1, it increases the level of similarity required between the two
 117 words before they will match.
 118
 119 {{{
 120                 roam~0.8
 121 }}}
 122
 123 If you do not specify the fuzzy factor, the default value of {{{0.5}}} will be
 124 used.
 125
 126
 127 === Range Searches ===
 128
 129 Range queries allow the developer or user to match field(s) whose values are
 130 between an upper and lower bound, either inclusively or exclusively.  Sorting
 131 is performed lexicographically, and is not limited to numeric values.
 132
 133 mtrack stores dates and times in the form {{{YYYY-MM-DDTHH:MM:SS}}} so that
 134 they can be meaningfully compared in this fashion.
 135
 136 To perform an inclusive range query:
 137
 138 {{{
 139                 updated:[2009-08-01 TO 2009-09-01]
 140 }}}
 141
 142 To perform an exclusive range query:
 143
 144 {{{
 145                 summary:{bug TO feature}
 146 }}}
 147
 148
 149 === Proximity Searches ===
 150
 151 To find words from a phrase that are within a certain number of words apart
 152 from each other in a document, you can append the tilde "~" character to the
 153 end of the phrase.  For example, to match text where the words "bug" and
 154 "report" appear within 10 words of each other:
 155
 156 {{{
 157         "bug report"~10
 158 }}}
 159
 160
 161 === Boosting a Term ===
 162
 163 The search results are returned based on the relevance of the match, as
 164 computed by the search engine for the terms that it found.  To boost the
 165 relevance of a term you may use the caret "^" symbol followed by a boost factor
 166 at the end of the term or subquery that you are searching.  The higher the
 167 boost factor, the more relevant the term will be and the higher ranking it will
 168 have in the results when it matches:
 169
 170 {{{
 171                 "crash trace"^4 analysis
 172 }}}
 173
 174 === Boolean Operators ===
 175
 176 Boolean operators allow terms to be combined through logic operators.  If you
 177 include multiple terms in your search, and do not specify a logic operator to
 178 combine them, then the search engine assumes that you meant to use the "OR"
 179 operator and will match documents that match any of your criteria.
 180
 181 You may use parentheses to group terms together to construct complex criteria.
 182
 183 The following operators are defined:
 184
 185 ==== AND ====
 186
 187 The AND operator means that all terms in the group must match some part of the
 188 search field(s).
 189
 190 {{{
 191         bug AND report
 192 }}}
 193
 194 {{{
 195         "stack trace" and valgrind
 196 }}}
 197
 198 You may use {{{&&}}} as a synonym for AND.
 199
 200 ==== OR ====
 201
 202 The OR operator divides the query into several optional terms.
 203
 204 {{{
 205         bug or crash
 206 }}}
 207
 208 You may use {{{||}}} as a synonym for OR.
 209
 210 ==== NOT ====
 211
 212 The NOT operator excludes documents that contain the term after NOT.
 213
 214 {{{
 215         bug and not crash
 216 }}}
 217
 218 You may use "!" as a synonym for NOT.
 219
 220 ==== + ==== #required
 221
 222 The "+", or "required", operator stipulates that the term after the "+" symbol
 223 must match the document.
 224
 225 The following matches text that must contain the word "bug" and may contain the
 226 word "report":
 227
 228 {{{
 229         +bug report
 230 }}}
 231
 232 ==== - ==== #prohibit
 233
 234 The "-", or "prohibit", operator excludes documents that match the term after
 235 the "-" symbol.
 236
 237 This matches documents that may contain the word "bug" and that do not contain
 238 the word "report":
 239
 240 {{{
 241         bug -report
 242 }}}
 243
 244 === Escaping Special Characters ===
 245
 246 The following characters are recognized as special characters by the search
 247 engine, and must be escaped if you need to use them as part of your search
 248 terms:
 249
 250 {{{
 251         + - && || ! ( ) { } [ ] ^ " ~ * ? : \
 252 }}}
 253
 254 The "+" and "-" characters are only special when they appear at the start or
 255 end of a search term and do not need to be escaped when they appear in the
 256 middle of a term.
 257
 258 The backslash character {{{\}}} can be used to escape these special characters.
 259 For example, if you intend to search for {{{(1+1):2}}}:
 260
 261 {{{
 262         \(1\+1\)\:2
 263 }}}
 264