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
This commit is contained in:
31
src/docs/developer/using_edges.diviner
Normal file
31
src/docs/developer/using_edges.diviner
Normal file
@@ -0,0 +1,31 @@
|
||||
@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.
|
||||
Reference in New Issue
Block a user