src/docs/user/userguide/search.diviner

   1 @title Search User Guide
   2 @group userguide
   3
   4 Introduction to searching for documents in Phabricator.
   5
   6 Overview
   7 ========
   8
   9 Phabricator has two major ways to search for documents and objects (like tasks,
  10 code reviews, users, wiki documents, and so on): **global search** and
  11 **application search**.
  12
  13 **Global search** allows you to search across multiple document types at once,
  14 but has fewer options for refining a search. It's a good general-purpose
  15 search, and helpful if you're searching for a text string.
  16
  17 **Application search** allows you to search within an application (like
  18 Maniphest) for documents of a specific type. Because application search is only
  19 searching one type of object, it can provide more powerful options for
  20 filtering, ordering, and displaying the results.
  21
  22 Both types of search share many of the same features. This document walks
  23 through how to use search and how to take advantage of some of the advanced
  24 options.
  25
  26
  27 Global Search
  28 =============
  29
  30 Global search allows you to search across multiple document types at once.
  31 You can access global search by entering a search query in the main menu bar.
  32
  33 By default, global search queries search all document types: for example, they
  34 will find matching tasks, commits, wiki documents, users, etc. You can use the
  35 dropdown to the left of the search box to select a different search scope.
  36
  37 If you choose the **Current Application** scope, Phabricator will search for
  38 open documents in the current application. For example, if you're in Maniphest
  39 and run a search, you'll get matching tasks. If you're in Phriction and run a
  40 search, you'll get matching wiki documents.
  41
  42 Some pages (like the 404 page) don't belong to an application, or belong to an
  43 application which doesn't have any searchable documents. In these cases,
  44 Phabricator will search all documents.
  45
  46 To quickly **jump to an object** like a task, enter the object's ID in the
  47 global search box and search for it. For example, you can enter `T123` or
  48 `D456` to quickly jump to the corresponding task or code review, or enter a Git
  49 commit hash to jump to the corresponding commit. For a complete list of
  50 supported commands, see @{article:Search User Guide: Shortcuts}.
  51
  52 After running a search, you can scroll up to add filters and refine the result
  53 set. You can also select **Advanced Search** from the dropdown menu to jump
  54 here immediately, or press return in the search box without entering a query.
  55
  56 This interface supports standard Phabricator search and filtering features,
  57 like **saved queries** and **typeaheads**. See below for more details on using
  58 these features.
  59
  60
  61 Application Search
  62 ==================
  63
  64 Application search gives you a more powerful way to search one type of document,
  65 like tasks. Most applications provide application search interfaces for the
  66 documents or objects they let you create: these pages have queries in the left
  67 menu, show objects or documents in the main content area, and have controls
  68 for refining the results.
  69
  70 These interfaces support **saved queries** and **typeaheads**.
  71
  72
  73 Saving and Sharing Queries
  74 =============
  75
  76 If you have a query which you run often, you can save it for easy access.
  77 To do this, click "Save Custom Query..." on the result screen. Choose a name
  78 for your query and it will be saved in the left nav so you can run it again
  79 with one click.
  80
  81 You can use "Edit Queries..." to reorder queries or remove saved queries you
  82 don't use anymore.
  83
  84 If you drag a query to the top of the list, it will execute by default when
  85 you load the relevant search interface. You can use this to make your default
  86 view show the results you most often want.
  87
  88 You can share queries with other users by sending them the URL. This will run
  89 the same query for them with all the parameters you've set (they may see
  90 different results than you do, because they may not have the same permissions).
  91
  92
  93 Typeaheads
  94 ==========
  95
  96 Typeaheads are text inputs which suggest options as you type. Typeaheads make
  97 it easy to select users, projects, document types, and other kinds of objects
  98 without typing their full names.
  99
 100 For example, if you want to find tasks that a specific user created, you can
 101 use the "Authors:" filter in Maniphest. The filter uses a typeahead control
 102 to let you enter authors who you want to search for.
 103
 104 To use a typeahead, enter the first few letters of the thing you want to
 105 select. It will appear in a dropdown under your cursor, and you can select it
 106 by clicking it (or using the arrow keys to highlight it, then pressing return).
 107
 108 If you aren't sure about the exact name of what you're looking for, click the
 109 browse button ({nav icon=search}) to the right of the input. This will let you
 110 browse through valid results for the control. You can filter the results from
 111 within the browse dialog to narrow them down.
 112
 113 Some typeaheads support advanced selection functions which can let you build
 114 more powerful queries. If a control supports functions, the "Browse" dialog
 115 will show that advanced functions are available and give you a link to details
 116 on which functions you can use.
 117
 118 For example, the `members()` function lets you automatically select all of the
 119 members of a project. You could use this with the "Authors" filter to find
 120 tasks created by anyone on a certain team.
 121
 122 Another useful function is the `viewer()` function, which works as though you'd
 123 typed your own username when you run the query. However, if you send the query
 124 to someone else, it will show results for //their// username when they run it.
 125 This can be particularly useful when creating dashboard panels.
 126
 127
 128 Fulltext Search
 129 ===============
 130
 131 Global search and some applications provide **fulltext search**. In
 132 applications, this is a field called {nav Query}.
 133
 134 Fulltext search allows you to search the text content of objects and supports
 135 some special syntax. These features are supported:
 136
 137   - Substring search with `~platypus`.
 138   - Field search with `title:platypus`.
 139   - Filtering out matches with `-platypus`.
 140   - Quoted terms with `"platypus attorney"`.
 141   - Matching entire fields with `=platypus`.
 142   - Combining features with `title:~"platypus attorney"`.
 143   - Testing a field for presence (`title:~`) or absence (`title:-`).
 144
 145 See below for more detail.
 146
 147 **Substrings**: Normally, query terms are searched for as words, so searching
 148 for `read` won't find documents which only contain the word `threaded`, even
 149 though "read" is a substring of "threaded". With the substring operator, `~`,
 150 you can search for substrings instead: the query `~read` will match documents
 151 which contain that text anywhere, even in the middle of a word.
 152
 153 **Quoted Terms**: When you search for multiple terms, documents which match
 154 each term will be returned, even if the terms are not adjacent in the document.
 155 For example, the query `void star` will match a document titled `A star in the
 156 void`, because it matches both `void` and `star`. To search for an exact
 157 sequence of terms, quote them: `"void star"`. This query will only match
 158 documents which use those terms as written.
 159
 160 **Stemming**: Searching for a term like `rearming` will find documents which
 161 contain variations of the word, like `rearm`, `rearms`, and `rearmed`. To
 162 search for an an exact word, quote the term: `"rearming"`.
 163
 164 **Field Search**: By default, query terms are searched for in the title, body,
 165 and comments. If you only want to search for a term in titles, use `title:`.
 166 For example, `title:platypus` only finds documents with that term in the
 167 title. This can be combined with other operators, for example `title:~platypus`
 168 or `title:"platypus attorney"`. These scopes are also supported:
 169
 170   - `title:...` searches titles.
 171   - `body:...` searches bodies (descriptions or summaries).
 172   - `core:...` searches titles and bodies, but not comments.
 173   - `comment:...` searches only comments.
 174
 175 **Filtering Matches**: You can remove documents which match certain terms from
 176 the result set with `-`. For example: `platypus -mammal`. Documents which match
 177 negated terms will be filtered out of the result set.
 178
 179 **Matching Entire Fields**: If you know the exact name of an object and want
 180 to find only that object, you can use the `=` operator. A query like
 181 `title:"warp drive"` will find a document titled "Warp Drive", but will also
 182 find documents with longer titles, like "Not a Warp Drive". The `=` operator
 183 requires that the entire field match the query exactly, so //only// documents
 184 exactly titled "Warp Drive" will be matched by the query (but note that the
 185 query is still case insensitive).
 186
 187 **Present and Absent Fields**: To find objects with //any// value in a
 188 particular field, use `field:~` as a search term (with no additional text). For
 189 example, searching Maniphest for `comment:~` will find tasks with any comments.
 190
 191 If you want to find objects that are //missing// a particular field, use
 192 `field:-` with no additional argument. For example, searching Maniphest for
 193 `body:-` will find tasks with no description.