diff --git a/doc/md/getting-started.md b/doc/md/getting-started.md index 1e4d9adec..43d202e97 100755 --- a/doc/md/getting-started.md +++ b/doc/md/getting-started.md @@ -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 `/ent/schema/` directory: -```go -// /ent/schema/user.go +```go title="/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="/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="/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="/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="/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="/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="/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="/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="/start/start.go" + +import ( + "/ent" + "/ent/car" + "/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="/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="/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="/start/start.go" + import ( "fmt" "log" "/ent" + "/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: -- `/ent/schema/group.go`: +```go title="/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), + } +} +``` -- `/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="/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="/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="/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="/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="/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).