Execute the query, loading all visible results.

Set the viewer who is executing the query. Results will be filtered according to the viewer's capabilities. You must set a viewer to execute a policy query.

Get the query's viewer.

Set the parent query of this query. This is useful for nested queries so that configuration like whether or not to raise policy exceptions is seamlessly passed along to child queries.

Get the parent query. See setParentQuery() for discussion.

Hook to configure whether this query should raise policy exceptions.

Execute the query, expecting a single result. This method simplifies loading objects for detail pages or edit views.

// Load one result by ID.
$obj = id(new ExampleQuery())
  ->setViewer($user)
  ->withIDs(array($id))
  ->executeOne();
if (!$obj) {
  return new Aphront404Response();
}

If zero results match the query, this method returns null. If one result matches the query, this method returns that result.

If two or more results match the query, this method throws an exception. You should use this method only when the query constraints guarantee at most one match (e.g., selecting a specific ID or PHID).

If one result matches the query but it is caught by the policy filter (for example, the user is trying to view or edit an object which exists but which they do not have permission to see) a policy exception is thrown.

Return a map of all object PHIDs which were loaded in the query but filtered out by policy constraints. This allows a caller to distinguish between objects which do not exist (or, at least, were filtered at the content level) and objects which exist but aren't visible.

Put a map of objects into the query workspace. Many queries perform subqueries, which can eventually end up loading the same objects more than once (often to perform policy checks).

For example, loading a user may load the user's profile image, which might load the user object again in order to verify that the viewer has permission to see the file.

The "query workspace" allows queries to load objects from elsewhere in a query block instead of refetching them.

When using the query workspace, it's important to obey two rules:

Never put objects into the workspace which the viewer may not be able to see. You need to apply all policy filtering before putting objects in the workspace. Otherwise, subqueries may read the objects and use them to permit access to content the user shouldn't be able to view.

Fully enrich objects pulled from the workspace. After pulling objects from the workspace, you still need to load and attach any additional content the query requests. Otherwise, a query might return objects without requested content.

Generally, you do not need to update the workspace yourself: it is automatically populated as a side effect of objects surviving policy filtering.

Retrieve objects from the query workspace. For more discussion about the workspace mechanism, see putObjectsInWorkspace(). This method searches both the current query's workspace and the workspaces of parent queries.

Mark PHIDs as in flight.

PHIDs which are "in flight" are actively being queried for. Using this list can prevent infinite query loops by aborting queries which cycle.

Get PHIDs which are currently in flight.

PHIDs which are "in flight" are actively being queried for.

Get the number of results loadPage() should load. If the value is 0, loadPage() should load all available results.

Hook invoked before query execution. Generally, implementations should reset any internal cursors.

Load a raw page of results. Generally, implementations should load objects from the database. They should attempt to return the number of results hinted by getRawResultLimit().

Update internal state so that the next call to loadPage() will return new results. Generally, you should adjust a cursor position based on the provided result page.

Hook for applying a page filter prior to the privacy filter. This allows you to drop some items from the result set without creating problems with pagination or cursor updates. You can also load and attach data which is required to perform policy filtering.

Generally, you should load non-policy data and perform non-policy filtering later, in didFilterPage(). Strictly fewer objects will make it that far (so the program will load less data) and subqueries from that context can use the query workspace to further reduce query load.

This method will only be called if data is available. Implementations do not need to handle the case of no results specially.

Hook for performing additional non-policy loading or filtering after an object has satisfied all policy checks. Generally, this means loading and attaching related data.

Subqueries executed during this phase can use the query workspace, which may improve performance or make circular policies resolvable. Data which is not necessary for policy filtering should generally be loaded here.

This callback can still filter objects (for example, if attachable data is discovered to not exist), but should not do so for policy reasons.

This method will only be called if data is available. Implementations do not need to handle the case of no results specially.

Hook for removing filtered results from alternate result sets. This hook will be called with any objects which were returned by the query but filtered for policy reasons. The query should remove them from any cached or partial result sets.

Hook for applying final adjustments before results are returned. This is used by PhabricatorCursorPagedPolicyAwareQuery to reverse results that are queried during reverse paging.

Allows a subclass to disable policy filtering. This method is dangerous. It should be used only if the query loads data which has already been filtered (for example, because it wraps some other query which uses normal policy filtering).

If this query belongs to an application, return the application class name here. This will prevent the query from returning results if the viewer can not access the application.

If this query does not belong to an application, return null.

Determine if the viewer has permission to use this query's application. For queries which aren't part of an application, this method always returns true.

Return the alias this query uses to identify the primary table.

Some automatic query constructions may need to be qualified with a table alias if the query performs joins which make column names ambiguous. If this is the case, return the alias for the primary table the query uses; generally the object table which has id and phid columns.

Simplifies the task of constructing a paging clause across multiple columns. In the general case, this looks like:

A > a OR (A = a AND B > b) OR (A = a AND B = b AND C > c)

To build a clause, specify the name, type, and value of each column to include:

$this->buildPagingClauseFromMultipleColumns(
  $conn_r,
  array(
    array(
      'table' => 't',
      'column' => 'title',
      'type' => 'string',
      'value' => $cursor->getTitle(),
      'reverse' => true,
    ),
    array(
      'table' => 't',
      'column' => 'id',
      'type' => 'int',
      'value' => $cursor->getID(),
    ),
  ),
  array(
    'reversed' => $is_reversed,
  ));

This method will then return a composable clause for inclusion in WHERE.

Select a result ordering.

This is a high-level method which selects an ordering from a predefined list of builtin orders, as provided by getBuiltinOrders(). These options are user-facing and not exhaustive, but are generally convenient and meaningful.

You can also use setOrderVector() to specify a low-level ordering across individual orderable columns. This offers greater control but is also more involved.

Set a grouping order to apply before primary result ordering.

This allows you to preface the query order vector with additional orders, so you can effect "group by" queries while still respecting "order by".

This is a high-level method which works alongside setOrder(). For lower-level control over order vectors, use setOrderVector().

Get builtin orders for this class.

In application UIs, we want to be able to present users with a small selection of meaningful order options (like "Order by Title") rather than an exhaustive set of column ordering options.

Meaningful user-facing orders are often really orders across multiple columns: for example, a "title" ordering is usually implemented as a "title, id" ordering under the hood.

Builtin orders provide a mapping from convenient, understandable user-facing orders to implementations.

A builtin order should provide these keys:

• vector (list<string>): The actual order vector to use.
• name (string): Human-readable order name.

Set a low-level column ordering.

This is a low-level method which offers granular control over column ordering. In most cases, applications can more easily use setOrder() to choose a high-level builtin order.

To set an order vector, specify a list of order keys as provided by getOrderableColumns().

Get the effective order vector.

Constrain the query with an ApplicationSearch index, requiring field values contain at least one of the values in a set.

This constraint can build the most common types of queries, like:

• Find users with shirt sizes "X" or "XL".
• Find shoes with size "13".

Constrain the query with an ApplicationSearch index, requiring values exist in a given range.

This constraint is useful for expressing date ranges:

• Find events between July 1st and July 7th.

The ends of the range are inclusive, so a $min of 3 and a $max of 5 will match fields with values 3, 4, or 5. Providing null for either end of the range will leave that end of the constraint open.

Get the name of the query's primary object PHID column, for constructing JOIN clauses. Normally (and by default) this is just "phid", but it may be something more exotic.

See getPrimaryTableAlias() if the column needs to be qualified with a table alias.

Determine if the JOINs built by ApplicationSearch might cause each primary object to return multiple result rows. Generally, this means the query needs an extra GROUP BY clause.

Construct a GROUP BY clause appropriate for ApplicationSearch constraints.

Construct a JOIN clause appropriate for applying ApplicationSearch constraints.

Construct a WHERE clause appropriate for applying ApplicationSearch constraints.

Convenience method for specifying edge logic constraints with a list of PHIDs.

Select certain edge logic constraint values.

Validate edge logic constraints for the query.

Constrain the query to return results from only specific Spaces.

Pass a list of Space PHIDs, or null to represent the default space. Only results in those Spaces will be returned.

Queries are always constrained to include only results from spaces the viewer has access to.

Constrain the query to include only results in valid Spaces.

This method builds part of a WHERE clause which considers the spaces the viewer has access to see with any explicit constraint on spaces added by withSpacePHIDs().