phorge / src / docs / user / userguide / search.diviner

@title Search User Guide
@group userguide

Introduction to searching for items and objects in Phorge.

Overview
========

Phorge has two major ways to search for items (like tasks,
code reviews, users, wiki documents, and so on): **global search** and
**application search**.

**Global search** allows you to search across multiple document types at once,
but has fewer options for refining a search. It's a good general-purpose
search, and helpful if you're searching for a text string.

**Application search** allows you to search within an application (like
Maniphest) for items of a specific type. Because application search is only
searching one type of object, it can provide more powerful options for
filtering, ordering, and displaying the results.

Both types of search share many of the same features. This document walks
through how to use search and how to take advantage of some of the advanced
options.


Global Search
=============

Global search allows you to search across multiple document types at once.
You can access global search by entering a search query in the main menu bar.

By default, global search queries search all document types: for example, they
will find matching tasks, commits, wiki documents, users, etc. You can use the
dropdown to the left of the search box to select a different search scope.

If you choose the **In Application Only** scope (instead of "Application",
Phorge displays the actual name of the application), Phorge will search for
open items in the current application. For example, if you're in Maniphest
and run a search, you'll get matching tasks. If you're in Phriction and run a
search, you'll get matching wiki documents.

Some pages (like the 404 page) don't belong to an application, or belong to an
application which doesn't have any searchable items. In these cases,
the **In Application Only** scope is not available for selection.

To quickly **jump to an object** like a task, enter the object's ID in the
global search box and search for it. For example, you can enter `T123` or
`D456` to quickly jump to the corresponding task or code review, or enter a Git
commit hash to jump to the corresponding commit. For a complete list of
supported commands, see @{article:Search User Guide: Shortcuts}.

After running a search, you can scroll up to add filters and refine the result
set. You can also press return in the search box without entering a query to go
here immediately.

This interface supports standard Phorge search and filtering features,
like **saved queries** and **typeaheads**. See below for more details on using
these features.


Application Search
==================

Application search gives you a more powerful way to search one type of document,
like tasks. Most applications provide application search interfaces for the
items they let you create: these pages have queries in the left
menu, show items in the main content area, and have controls
for refining the results.

These interfaces support **saved queries** and **typeaheads**.


Saving and Sharing Queries
=============

If you have a query which you run often, you can save it for easy access.
To do this, click "Save Custom Query..." on the result screen. Choose a name
for your query and it will be saved in the left nav so you can run it again
with one click.

You can use "Edit Queries..." to reorder queries or remove saved queries you
don't use anymore.

If you drag a query to the top of the list, it will execute by default when
you load the relevant search interface. You can use this to make your default
view show the results you most often want.

You can share queries with other users by sending them the URL. This will run
the same query for them with all the parameters you've set (they may see
different results than you do, because they may not have the same permissions).


Typeaheads
==========

Typeaheads are text inputs which suggest options as you type. Typeaheads make
it easy to select users, projects, document types, and other kinds of objects
without typing their full names.

For example, if you want to find tasks that a specific user created, you can
use the "Authors:" filter in Maniphest. The filter uses a typeahead control
to let you enter authors who you want to search for.

To use a typeahead, enter the first few letters of the thing you want to
select. It will appear in a dropdown under your cursor, and you can select it
by clicking it (or using the arrow keys to highlight it, then pressing return).

If you aren't sure about the exact name of what you're looking for, click the
browse button ({nav icon=search}) to the right of the input. This will let you
browse through valid results for the control. You can filter the results from
within the browse dialog to narrow them down.

Some typeaheads support advanced selection functions which can let you build
more powerful queries. If a control supports functions, the "Browse" dialog
will show that advanced functions are available and give you a link to details
on which functions you can use.

For example, the `members()` function lets you automatically select all of the
members of a project. You could use this with the "Authors" filter to find
tasks created by anyone on a certain team.

Another useful function is the `viewer()` function, which works as though you'd
typed your own username when you run the query. However, if you send the query
to someone else, it will show results for //their// username when they run it.
This can be particularly useful when creating dashboard panels.


Fulltext Search
===============

Global search and some applications provide **fulltext search**. In
applications, this is a field called {nav Query}.

Fulltext search allows you to search the text content of objects and supports
some special syntax. These features are supported:

  - Substring search with `~platypus`.
  - Field search with `title:platypus`.
  - Filtering out matches with `-platypus`.
  - Quoted terms with `"platypus attorney"`.
  - Matching entire fields with `=platypus`.
  - Combining features with `title:~"platypus attorney"`.
  - Testing a field for presence (`title:~`) or absence (`title:-`).

See below for more detail.

**Substrings**: Normally, query terms are searched for as words, so searching
for `read` won't find items which only contain the word `threaded`, even
though "read" is a substring of "threaded". With the substring operator, `~`,
you can search for substrings instead: the query `~read` will match items
which contain that text anywhere, even in the middle of a word.

**Quoted Terms**: When you search for multiple terms, items which match
each term will be returned, even if the terms are not adjacent in the document.
For example, the query `void star` will match a document titled `A star in the
void`, because it matches both `void` and `star`. To search for an exact
sequence of terms, quote them: `"void star"`. This query will only match
items which use those terms as written.

**Stemming**: Searching for a term like `rearming` will find items which
contain variations of the word, like `rearm`, `rearms`, and `rearmed`. To
search for an an exact word, quote the term: `"rearming"`.

**Field Search**: By default, query terms are searched for in the title, body,
and comments. If you only want to search for a term in titles, use `title:`.
For example, `title:platypus` only finds items with that term in the
title. This can be combined with other operators, for example `title:~platypus`
or `title:"platypus attorney"`. These scopes are also supported:

  - `title:...` searches titles.
  - `body:...` searches bodies (descriptions or summaries).
  - `core:...` searches titles and bodies, but not comments.
  - `comment:...` searches only comments.

**Filtering Matches**: You can remove items which match certain terms from
the result set with `-`. For example: `platypus -mammal`. Items which match
negated terms will be filtered out of the result set.

**Matching Entire Fields**: If you know the exact name of an object and want
to find only that object, you can use the `=` operator. A query like
`title:"warp drive"` will find a document titled "Warp Drive", but will also
find items with longer titles, like "Not a Warp Drive". The `=` operator
requires that the entire field match the query exactly, so //only// items
exactly titled "Warp Drive" will be matched by the query (but note that the
query is still case insensitive).

**Present and Absent Fields**: To find objects with //any// value in a
particular field, use `field:~` as a search term (with no additional text). For
example, searching Maniphest for `comment:~` will find tasks with any comments.

If you want to find objects that are //missing// a particular field, use
`field:-` with no additional argument. For example, searching Maniphest for
`body:-` will find tasks with no description.