phorge-phorge/src/docs/contributor/using_edges.diviner

@title Using Edges
@group developer

Guide to the Edges infrastructure.

= Overview =

Edges are a generic way of storing a relationship between two objects (like
a Task and its attached files). If you are familiar with the Facebook
associations framework, Phabricator Edges are substantially similar.

An edge is defined by a source PHID (the edge origin), a destination PHID
(the edge destination) and an edge type (which describes the relationship,
like "is subscribed to" or "has attached file").

Every edge is directional, and stored alongside the source object. Some edges
are configured to automatically write an inverse edge, effectively building
a bidirectional relationship. The strength of storing relationships like this
is that they work when databases are partitioned or sharded.

= Reading Edges =

You can load edges with @{class:PhabricatorEdgeQuery}.

= Writing Edges =

You can edit edges with @{class:PhabricatorEdgeEditor}.

= Edges and Lisk =

@{class:PhabricatorLiskDAO} includes some builtin support for edges.
Add an assocations-like "Edges" framework Summary: We have a lot of cases where we store object relationships, but it's all kind of messy and custom. Some particular problems: - We go to great lengths to enforce order stability in Differential revisions, but the implementation is complex and inelegant. - Some relationships are stored on-object, so we can't pull the inverses easily. For example, Maniphest shows child tasks but not parent tasks. - I want to add more of these and don't want to continue building custom stuff. - UIs like the "attach stuff to other stuff" UI need custom branches for each object type. - Stuff like "allow commits to close tasks" is notrivial because of nonstandard metadata storage. Provide an association-like "edge" framework to fix these problems. This is nearly identical to associations, with a few differences: - I put edge metadata in a separate table and don't load it by default, to keep edge rows small and allow large metadata if necessary. The on-edge metadata seemed to get abused a lot at Facebook. - I put a 'seq' column on the edges to ensure they have an explicit, stable ordering within a source and type. This isn't actually used anywhere yet, but my first target is attaching commits to tasks for T904. Test Plan: Made a mock page that used Editor and Query. Verified adding and removing edges, overwriting edges, writing and loading edge data, sequence number generation. Reviewers: btrahan Reviewed By: btrahan CC: aran, 20after4 Differential Revision: https://secure.phabricator.com/D2088 2012-04-05 00:30:21 +02:00			`@title Using Edges`
			`@group developer`

			`Guide to the Edges infrastructure.`

			`= Overview =`

			`Edges are a generic way of storing a relationship between two objects (like`
			`a Task and its attached files). If you are familiar with the Facebook`
			`associations framework, Phabricator Edges are substantially similar.`

			`An edge is defined by a source PHID (the edge origin), a destination PHID`
			`(the edge destination) and an edge type (which describes the relationship,`
			`like "is subscribed to" or "has attached file").`

			`Every edge is directional, and stored alongside the source object. Some edges`
			`are configured to automatically write an inverse edge, effectively building`
			`a bidirectional relationship. The strength of storing relationships like this`
			`is that they work when databases are partitioned or sharded.`

			`= Reading Edges =`

			`You can load edges with @{class:PhabricatorEdgeQuery}.`

			`= Writing Edges =`

			`You can edit edges with @{class:PhabricatorEdgeEditor}.`

			`= Edges and Lisk =`

			`@{class:PhabricatorLiskDAO} includes some builtin support for edges.`