golang/ent
1
0
Fork 0
mirror of https://github.com/ent/ent.git synced 2026-05-24 09:31:56 +03:00
Code Issues Packages Projects Releases Wiki Activity

doc/edges: add erds to examples (#3268)

Browse Source
This commit is contained in:
Ariel Mashraki
2023-01-23 15:53:33 +02:00
committed by GitHub
parent c9445d2794
commit 307eb5e30b
20 changed files with 527 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
doc/md/schema-edges.mdx
View File

@@ -8,16 +8,33 @@ import TabItem from '@theme/TabItem';
## Quick Summary
Edges are the relations (or associations) of entities. For example, user's pets, or group's users.
Edges are the relations (or associations) of entities. For example, user's pets, or group's users:
<Tabs>
<TabItem value="graph" label="Graph" default>
![er-group-users](https://entgo.io/images/assets/er_user_pets_groups.png)
</TabItem>
<TabItem value="erd" label="ERD and SQL">
[![erd-group-users](https://entgo.io/images/assets/erd/edges-quick-summary.png)](https://gh.atlasgo.cloud/explore/38be6c19)
<div style={{textAlign: 'center'}}>
<a href={"https://gh.atlasgo.cloud/explore/38be6c19"} style={{fontSize: 12}}>ERD was generated by Atlas</a>
</div>
</TabItem>
</Tabs>
In the example above, you can see 2 relations declared using edges. Let's go over them.
1\. `pets` / `owner` edges; user's pets and pet's owner -
1\. `pets` / `owner` edges; user's pets and pet's owner:
```go title="ent/schema/user.go"
<Tabs>
<TabItem value="user" label="User" default>
```go title="ent/schema/user.go" {23}
package schema
import (
@@ -44,8 +61,10 @@ func (User) Edges() []ent.Edge {
}
}
```
</TabItem>
<TabItem value="pet" label="Pet">
```go title="ent/schema/pet.go"
```go title="ent/schema/pet.go" {23-25}
package schema
import (
@@ -74,6 +93,8 @@ func (Pet) Edges() []ent.Edge {
}
}
```
</TabItem>
</Tabs>
As you can see, a `User` entity can **have many** pets, but a `Pet` entity can **have only one** owner.
In relationship definition, the `pets` edge is a *O2M* (one-to-many) relationship, and the `owner` edge
@@ -88,9 +109,12 @@ references from one schema to other.
The cardinality of the edge/relationship can be controlled using the `Unique` method, and it's explained
more widely below.
2\. `users` / `groups` edges; group's users and user's groups -
2\. `users` / `groups` edges; group's users and user's groups:
```go title="ent/schema/group.go"
<Tabs>
<TabItem value="group" label="Group" default>
```go title="ent/schema/group.go" {23}
package schema
import (
@@ -117,8 +141,10 @@ func (Group) Edges() []ent.Edge {
}
}
```
</TabItem>
<TabItem value="user" label="User">
```go title="ent/schema/user.go"
```go title="ent/schema/user.go" {23-24}
package schema
import (
@@ -148,6 +174,8 @@ func (User) Edges() []ent.Edge {
}
}
```
</TabItem>
</Tabs>
As you can see, a Group entity can **have many** users, and a User entity can have **have many** groups.
In relationship definition, the `users` edge is a *M2M* (many-to-many) relationship, and the `groups`
@@ -175,13 +203,31 @@ Let's go over a few examples that show how to define different relation types us
## O2O Two Types
<Tabs>
<TabItem value="graph" label="Graph" default>
![er-user-card](https://entgo.io/images/assets/er_user_card.png)
</TabItem>
<TabItem value="erd" label="ERD and SQL">
[![edges-o2o-two-types](https://entgo.io/images/assets/erd/edges-o2o-two-types.png)](https://gh.atlasgo.cloud/explore/b6264668)
<div style={{textAlign: 'center'}}>
<a href={"https://gh.atlasgo.cloud/explore/b6264668"} style={{fontSize: 12}}>ERD was generated by Atlas</a>
</div>
</TabItem>
</Tabs>
In this example, a user **has only one** credit-card, and a card **has only one** owner.
The `User` schema defines an `edge.To` card named `card`, and the `Card` schema
defines a back-reference to this edge using `edge.From` named `owner`.
<Tabs>
<TabItem value="user" label="User" default>
```go title="ent/schema/user.go"
// Edges of the user.
func (User) Edges() []ent.Edge {
@@ -191,6 +237,8 @@ func (User) Edges() []ent.Edge {
}
}
```
</TabItem>
<TabItem value="card" label="Card">
```go title="ent/schema/card.go"
// Edges of the Card.
@@ -206,6 +254,8 @@ func (Card) Edges() []ent.Edge {
}
}
```
</TabItem>
</Tabs>
The API for interacting with these edges is as follows:
```go
@@ -251,8 +301,23 @@ The full example exists in [GitHub](https://github.com/ent/ent/tree/master/examp
## O2O Same Type
<Tabs>
<TabItem value="graph" label="Graph" default>
![er-linked-list](https://entgo.io/images/assets/er_linked_list.png)
</TabItem>
<TabItem value="erd" label="ERD and SQL">
[![edges-linked-list](https://entgo.io/images/assets/erd/edges-o2o-same-type.png)](https://gh.atlasgo.cloud/explore/6645164b)
<div style={{textAlign: 'center'}}>
<a href={"https://gh.atlasgo.cloud/explore/6645164b"} style={{fontSize: 12}}>ERD was generated by Atlas</a>
</div>
</TabItem>
</Tabs>
In this linked-list example, we have a **recursive relation** named `next`/`prev`. Each node in the list can
**have only one** `next` node. If a node A points (using `next`) to node B, B can get its pointer using `prev` (the back-reference edge).
@@ -346,8 +411,23 @@ The full example exists in [GitHub](https://github.com/ent/ent/tree/master/examp
## O2O Bidirectional
<Tabs>
<TabItem value="graph" label="Graph" default>
![er-user-spouse](https://entgo.io/images/assets/er_user_spouse.png)
</TabItem>
<TabItem value="erd" label="ERD and SQL">
[![edges-o2o-bidirectional](https://entgo.io/images/assets/erd/edges-o2o-bidirectional.png)](https://gh.atlasgo.cloud/explore/e2e76d55)
<div style={{textAlign: 'center'}}>
<a href={"https://gh.atlasgo.cloud/explore/e2e76d55"} style={{fontSize: 12}}>ERD was generated by Atlas</a>
</div>
</TabItem>
</Tabs>
In this user-spouse example, we have a **symmetric O2O relation** named `spouse`. Each user can **have only one** spouse.
If user A sets its spouse (using `spouse`) to B, B can get its spouse using the `spouse` edge.
@@ -441,15 +521,33 @@ The full example exists in [GitHub](https://github.com/ent/ent/tree/master/examp
## O2M Two Types
<Tabs>
<TabItem value="graph" label="Graph" default>
![er-user-pets](https://entgo.io/images/assets/er_user_pets.png)
</TabItem>
<TabItem value="erd" label="ERD and SQL">
[![edges-o2m-two-types](https://entgo.io/images/assets/erd/edges-o2m-two-types.png)](https://gh.atlasgo.cloud/explore/8a360fce)
<div style={{textAlign: 'center'}}>
<a href={"https://gh.atlasgo.cloud/explore/8a360fce"} style={{fontSize: 12}}>ERD was generated by Atlas</a>
</div>
</TabItem>
</Tabs>
In this user-pets example, we have a O2M relation between user and its pets.
Each user **has many** pets, and a pet **has one** owner.
If user A adds a pet B using the `pets` edge, B can get its owner using the `owner` edge (the back-reference edge).
Note that this relation is also a M2O (many-to-one) from the point of view of the `Pet` schema.
```go title="ent/schema/user.go"
<Tabs>
<TabItem value="user" label="User" default>
```go title="ent/schema/user.go" {4}
// Edges of the User.
func (User) Edges() []ent.Edge {
return []ent.Edge{
@@ -457,8 +555,10 @@ func (User) Edges() []ent.Edge {
}
}
```
</TabItem>
<TabItem value="pet" label="Pet">
```go title="ent/schema/pet.go"
```go title="ent/schema/pet.go" {4-6}
// Edges of the Pet.
func (Pet) Edges() []ent.Edge {
return []ent.Edge{
@@ -468,6 +568,8 @@ func (Pet) Edges() []ent.Edge {
}
}
```
</TabItem>
</Tabs>
The API for interacting with these edges is as follows:
@@ -520,7 +622,7 @@ func Do(ctx context.Context, client *ent.Client) error {
Note that, the foreign-key column can be configured and exposed as an entity field using the
[Edge Field](#edge-field) option as follows:
```go {4,15}
```go title="ent/schema/pet.go" {4,15}
// Fields of the Pet.
func (Pet) Fields() []ent.Field {
return []ent.Field{
@@ -544,8 +646,23 @@ The full example exists in [GitHub](https://github.com/ent/ent/tree/master/examp
## O2M Same Type
<Tabs>
<TabItem value="graph" label="Graph" default>
![er-tree](https://entgo.io/images/assets/er_tree.png)
</TabItem>
<TabItem value="erd" label="ERD and SQL">
[![edges-o2m-same-type](https://entgo.io/images/assets/erd/edges-o2m-same-type.png)](https://gh.atlasgo.cloud/explore/74c74ac7)
<div style={{textAlign: 'center'}}>
<a href={"https://gh.atlasgo.cloud/explore/74c74ac7"} style={{fontSize: 12}}>ERD was generated by Atlas</a>
</div>
</TabItem>
</Tabs>
In this example, we have a recursive O2M relation between tree's nodes and their children (or their parent).
Each node in the tree **has many** children, and **has one** parent. If node A adds B to its children,
B can get its owner using the `owner` edge.
@@ -674,8 +791,23 @@ The full example exists in [GitHub](https://github.com/ent/ent/tree/master/examp
## M2M Two Types
<Tabs>
<TabItem value="graph" label="Graph" default>
![er-user-groups](https://entgo.io/images/assets/er_user_groups.png)
</TabItem>
<TabItem value="erd" label="ERD and SQL">
[![edges-m2m-two-types](https://entgo.io/images/assets/erd/edges-m2m-two-types.png)](https://gh.atlasgo.cloud/explore/25b70c29)
<div style={{textAlign: 'center'}}>
<a href={"https://gh.atlasgo.cloud/explore/25b70c29"} style={{fontSize: 12}}>ERD was generated by Atlas</a>
</div>
</TabItem>
</Tabs>
In this groups-users example, we have a M2M relation between groups and their users.
Each group **has many** users, and each user can be joined to **many** groups.
@@ -780,8 +912,23 @@ The full example exists in [GitHub](https://github.com/ent/ent/tree/master/examp
## M2M Same Type
<Tabs>
<TabItem value="graph" label="Graph" default>
![er-following-followers](https://entgo.io/images/assets/er_following_followers.png)
</TabItem>
<TabItem value="erd" label="ERD and SQL">
[![edges-m2m-same-type](https://entgo.io/images/assets/erd/edges-m2m-same-type.png)](https://gh.atlasgo.cloud/explore/8cb4fd4e)
<div style={{textAlign: 'center'}}>
<a href={"https://gh.atlasgo.cloud/explore/8cb4fd4e"} style={{fontSize: 12}}>ERD was generated by Atlas</a>
</div>
</TabItem>
</Tabs>
In this following-followers example, we have a M2M relation between users to their followers. Each user
can follow **many** users, and can have **many** followers.
@@ -888,8 +1035,23 @@ The full example exists in [GitHub](https://github.com/ent/ent/tree/master/examp
## M2M Bidirectional
<Tabs>
<TabItem value="graph" label="Graph" default>
![er-user-friends](https://entgo.io/images/assets/er_user_friends.png)
</TabItem>
<TabItem value="erd" label="ERD and SQL">
[![edges-m2m-bidirectional](https://entgo.io/images/assets/erd/edges-m2m-bidirectional.png)](https://gh.atlasgo.cloud/explore/74c5bd30)
<div style={{textAlign: 'center'}}>
<a href={"https://gh.atlasgo.cloud/explore/74c5bd30"} style={{fontSize: 12}}>ERD was generated by Atlas</a>
</div>
</TabItem>
</Tabs>
In this user-friends example, we have a **symmetric M2M relation** named `friends`.
Each user can **have many** friends. If user A becomes a friend of B, B is also a friend of A.
@@ -1058,8 +1220,23 @@ In the following example, we demonstrate how to model the friendship between two
required fields of the relationship (`user_id` and `friend_id`), and an additional field named `created_at` whose value
is automatically set on creation.
<Tabs>
<TabItem value="graph" label="Graph" default>
![er_edgeschema_bidi](https://entgo.io/images/assets/er_edgeschema_bidi.png)
</TabItem>
<TabItem value="erd" label="ERD and SQL">
[![edges-schema](https://entgo.io/images/assets/erd/edges-schema.png)](https://gh.atlasgo.cloud/explore/90e2415f)
<div style={{textAlign: 'center'}}>
<a href={"https://gh.atlasgo.cloud/explore/90e2415f"} style={{fontSize: 12}}>ERD was generated by Atlas</a>
</div>
</TabItem>
</Tabs>
<Tabs
defaultValue="user"
values={[