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

doc/md: making the getting started section more consistent and clearer (#1713)

Browse Source 
* doc/md: making the getting started section more consistent and clerer

* Update doc/md/getting-started.md

Co-authored-by: Ariel Mashraki <7413593+a8m@users.noreply.github.com>

* cr changes

* cr changes

* removing imports

* Update doc/md/getting-started.md

Co-authored-by: Ariel Mashraki <7413593+a8m@users.noreply.github.com>
This commit is contained in:
Zeev Manilovich
2021-07-13 14:32:55 +03:00
committed by GitHub
parent a5d0088ca6
commit c8ed4e9d7a
1 changed files with 76 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

168
doc/md/getting-started.md
View File

@@ -42,15 +42,13 @@ Go to the root directory of your project, and run:
```console
go run entgo.io/ent/cmd/ent init User
```
The command above will generate the schema for `User` under `<project>/ent/schema/` directory:
```go
// <project>/ent/schema/user.go
```go title="<project>/ent/schema/user.go"
package schema
import "entgo.io/ent"
// User holds the schema definition for the User entity.
type User struct {
ent.Schema
@@ -70,15 +68,10 @@ func (User) Edges() []ent.Edge {
Add 2 fields to the `User` schema:
```go
```go title="<project>/ent/schema/user.go"
package schema
import (
"entgo.io/ent"
"entgo.io/ent/schema/field"
)
// Fields of the User.
func (User) Fields() []ent.Field {
return []ent.Field{
@@ -97,17 +90,15 @@ go generate ./ent
```
This produces the following files:
```
```console {12-20}
ent
├── client.go
├── config.go
├── context.go
├── ent.go
├── migrate
│ ├── migrate.go
│ └── schema.go
├── predicate
│ └── predicate.go
├── generate.go
├── mutation.go
... truncated
├── schema
│ └── user.go
├── tx.go
@@ -124,9 +115,10 @@ ent
## Create Your First Entity
To get started, create a new `ent.Client`. For this example, we will use SQLite3.
To get started, create a new `ent.Client`. For this example, we will use SQLite3.
```go title="<project>/start/start.go"
```go
package main
import (
@@ -152,7 +144,9 @@ func main() {
```
Now, we're ready to create our user. Let's call this function `CreateUser` for the sake of example:
```go
```go title="<project>/start/start.go"
func CreateUser(ctx context.Context, client *ent.Client) (*ent.User, error) {
u, err := client.User.
Create().
@@ -165,6 +159,7 @@ func CreateUser(ctx context.Context, client *ent.Client) (*ent.User, error) {
log.Println("user was created: ", u)
return u, nil
}
```
## Query Your Entities
@@ -172,7 +167,8 @@ func CreateUser(ctx context.Context, client *ent.Client) (*ent.User, error) {
`ent` generates a package for each entity schema that contains its predicates, default values, validators
and additional information about storage elements (column names, primary keys, etc).
```go
```go title="<project>/start/start.go"
package main
import (
@@ -209,13 +205,8 @@ go run entgo.io/ent/cmd/ent init Car Group
```
And then we add the rest of the fields manually:
```go
import (
"regexp"
"entgo.io/ent"
"entgo.io/ent/schema/field"
)
```go title="<project>/ent/schema/car.go"
// Fields of the Car.
func (Car) Fields() []ent.Field {
@@ -224,7 +215,9 @@ func (Car) Fields() []ent.Field {
field.Time("registered_at"),
}
}
```
```go title="<project>/ent/schema/group.go"
// Fields of the Group.
func (Group) Fields() []ent.Field {
@@ -243,24 +236,26 @@ can **have 1 or more** cars, but a car **has only one** owner (one-to-many relat
Let's add the `"cars"` edge to the `User` schema, and run `go generate ./ent`:
```go
import (
"log"
```go title="<project>/ent/schema/user.go"
"entgo.io/ent"
"entgo.io/ent/schema/edge"
)
// Edges of the User.
func (User) Edges() []ent.Edge {
return []ent.Edge{
// Edges of the User.
func (User) Edges() []ent.Edge {
return []ent.Edge{
edge.To("cars", Car.Type),
}
}
```
}
}
```
We continue our example by creating 2 cars and adding them to a user.
```go
```go title="<project>/start/start.go"
import (
"<porject>/ent"
"<porject>/ent/car"
"<porject>/ent/user"
)
func CreateCars(ctx context.Context, client *ent.Client) (*ent.User, error) {
// Create a new car with model "Tesla".
tesla, err := client.Car.
@@ -297,9 +292,12 @@ func CreateCars(ctx context.Context, client *ent.Client) (*ent.User, error) {
log.Println("user was created: ", a8m)
return a8m, nil
}
```
But what about querying the `cars` edge (relation)? Here's how we do it:
```go
```go title="<project>/start/start.go"
import (
"log"
@@ -339,13 +337,7 @@ edge in the database. It's just a back-reference to the real edge (relation).
Let's add an inverse edge named `owner` to the `Car` schema, reference it to the `cars` edge
in the `User` schema, and run `go generate ./ent`.
```go
import (
"log"
"entgo.io/ent"
"entgo.io/ent/schema/edge"
)
```go title="<project>/ent/schema/car.go"
// Edges of the Car.
func (Car) Edges() []ent.Edge {
@@ -363,12 +355,14 @@ func (Car) Edges() []ent.Edge {
```
We'll continue the user/cars example above by querying the inverse edge.
```go
```go title="<project>/start/start.go"
import (
"fmt"
"log"
"<project>/ent"
"<project>/ent/user"
)
func QueryCarUsers(ctx context.Context, a8m *ent.User) error {
@@ -399,45 +393,30 @@ a simple "many-to-many" relationship. In the above illustration, the `Group` sch
of the `users` edge (relation), and the `User` entity has a back-reference/inverse edge to this
relationship named `groups`. Let's define this relationship in our schemas:
- `<project>/ent/schema/group.go`:
```go title="<project>/ent/schema/group.go"
```go
import (
"log"
"entgo.io/ent"
"entgo.io/ent/schema/edge"
)
// Edges of the Group.
func (Group) Edges() []ent.Edge {
return []ent.Edge{
edge.To("users", User.Type),
}
}
```
// Edges of the Group.
func (Group) Edges() []ent.Edge {
return []ent.Edge{
edge.To("users", User.Type),
}
}
```
- `<project>/ent/schema/user.go`:
```go
import (
"log"
"entgo.io/ent"
"entgo.io/ent/schema/edge"
)
// Edges of the User.
func (User) Edges() []ent.Edge {
return []ent.Edge{
edge.To("cars", Car.Type),
// Create an inverse-edge called "groups" of type `Group`
// and reference it to the "users" edge (in Group schema)
// explicitly using the `Ref` method.
edge.From("groups", Group.Type).
Ref("users"),
}
}
```
```go title="<project>/ent/schema/user.go"
// Edges of the User.
func (User) Edges() []ent.Edge {
return []ent.Edge{
edge.To("cars", Car.Type),
// Create an inverse-edge called "groups" of type `Group`
// and reference it to the "users" edge (in Group schema)
// explicitly using the `Ref` method.
edge.From("groups", Group.Type).
Ref("users"),
}
}
```
We run `ent` on the schema directory to re-generate the assets.
```console
@@ -452,7 +431,7 @@ entities and relations). Let's create the following graph using the framework:
![re-graph](https://entgo.io/images/assets/re_graph_getting_started.png)
```go
```go title="<project>/start/start.go"
func CreateGraph(ctx context.Context, client *ent.Client) error {
// First, create the users.
@@ -526,7 +505,8 @@ Now when we have a graph with data, we can run a few queries on it:
1. Get all user's cars within the group named "GitHub":
```go
```go title="<project>/start/start.go"
import (
"log"
@@ -551,8 +531,9 @@ Now when we have a graph with data, we can run a few queries on it:
```
2. Change the query above, so that the source of the traversal is the user *Ariel*:
```go
```go title="<project>/start/start.go"
import (
"log"
@@ -590,7 +571,8 @@ Now when we have a graph with data, we can run a few queries on it:
3. Get all groups that have users (query with a look-aside predicate):
```go
```go title="<project>/start/start.go"
import (
"log"
@@ -612,4 +594,6 @@ Now when we have a graph with data, we can run a few queries on it:
}
```
## Full Example
The full example exists in [GitHub](https://github.com/ent/ent/tree/master/examples/start).