Reading Data GO Go05

import Collapse from "components/Markdown/Collapse" import Code from "components/Markdown/Code" import Warning from "components/Markdown/Warning" import Info from "components/Markdown/Info"

export const meta = { title: 'Reading Data (Go)', position: 50, technology: "go", technologyOrder: 3, articleGroup: "Reading Data", }

Overview

The Prisma client is generated from your datamodel. Its API exposes CRUD and other operations for the models defined in the datamodel.

For this page, we'll assume your Prisma project is based on the following datamodel:

graphql

type Post {
  id: ID! @id
  createdAt: DateTime! @createdAt
  updatedAt: DateTime! @updatedAt
  title: String!
  published: Boolean! @default(value: false)
  author: User
  comments: [Comment!]!
}

type User {
  id: ID! @id
  name: String
  email: String! @unique
  role: Role! @default(value: USER)
  posts: [Post!]!
  comments: [Comment!]!
}

type Comment {
  id: ID! @id
  createdAt: DateTime! @createdAt
  text: String!
  post: Post!
  writtenBy: User!
}

enum Role {
  USER
  ADMIN
}

Whenever a database record is queried using the Prisma client, all scalar fields of that record are fetched. This is true no matter if a single record or a list of records is queried.

For example, the following query returns all scalar fields of a single User:

email := "[email protected]"
user, err := client.User(prisma.UserWhereUniqueInput{
  Email: &email,
}).Exec(ctx)

&prisma.User{
  ID:cjsx2j8bq028z0b253bstyggy 
  Name:0xc0002e8940 // "Ada"
  Email:[email protected]
}

</Code>

In this case, the returned user record will have four properties (that correspond to the scalar fields of the User model): id, name, email and role. The posts and comments fields are both relation fields and are therefore not included in the response.

Here is an example of fetching a list of User records:

users, err := client.Users(nil).Exec(ctx)

[]prisma.User{
	prisma.User{
		ID:"cjsx2j8bq028z0b253bstyggy",
		Name:(*string)(0xc0001202c0), 
		Email:"[email protected]"
	},
	prisma.User{
		ID:"cjsx2j8cb029k0b25nwwo9bkg",
		Name:(*string)(0xc000120420), 
		Email:"[email protected]"
	}, 
	prisma.User{
		ID:"cjsx2j8cz02a70b25law6s8y2",
		Name:(*string)(0xc0001205d0), 
		Email:"[email protected]"
	}
}

</Code>

Similar to the previous request, each object inside the users array only has the scalar and no relation fields.

Fetching single records

For each model in your datamodel, there is a method generated in the Prisma client API that allows to fetch single records of that model.

The method is named after the model. For the sample datamodel from above, the three generated methods for fetching single records are:

func (client *Client) User(params UserWhereUniqueInput) *UserExec for User
func (client *Client) Post(params PostWhereUniqueInput) *PostExec for Post
func (client *Client) Comment(params CommentWhereUniqueInput) *CommentExec for Comment

The params input argument for these methods is a struct that has as properties all unique fields of the model. This means, for all three methods, the id field is accepted (as the corresponding models each have an id field annotated as @unique). The params struct for the user method additionaly has an email field.

Examples

Fetch a single post by its id:

id := "cjsx2j8bw02920b25rl806l07"
post, err := client.Post(prisma.PostWhereUniqueInput{
  ID: &id,
}).Exec(ctx)

&prisma.Post{
	ID:"cjsx2j8bw02920b25rl806l07", 
	CreatedAt:"2019-03-06T10:37:43.526Z", 
	UpdatedAt:"2019-03-06T10:37:43.526Z", 
	Title:"Building General-Purpose Computers", 
	Published:true
}

</Code>

Fetch a single user by their email:

email := "[email protected]"
user, err := client.User(prisma.UserWhereUniqueInput{
  Email: &email,
}).Exec(ctx)

&prisma.User{
  ID:cjsx2j8bq028z0b253bstyggy 
  Name:0xc0002e8940 // "Ada"
  Email:[email protected]
}

</Code>

Fetching lists

For each model in your datamodel, there is a method generated in the Prisma client API that allows to fetch a list of the respective records.

The method is named after the model but starts uses the plural form. For the sample datamodel from above, the three generated methods for fetching single records are:

func (client *Client) Users(params *UsersParams) *UserExecArray for User
func (client *Client) Posts(params *PostsParamsExec) *PostExecArray for Post
func (client *Client) Comments(params *CommentsParamsExec) *CommentExecArray for Comment

The input arugment for these functions is a struct that has properties for:

filtering: where
ordering: orderBy
pagination: before, after, first, last, skip

Examples

Fetch all comments:

comments, err := client.Comments(nil).Exec(ctx)

[]prisma.Comment{
	prisma.Comment{
		ID:"cjsx2j8cm029r0b256m1qjc1z", 
		CreatedAt:"2019-03-06T10:37:43.547Z", 
		Text:"Great work!"
	}, 
	prisma.Comment{
		ID:"cjsx2j8d502ac0b2573tfihhd", 
		CreatedAt:"2019-03-06T10:37:43.570Z", 
		Text:"I love this."
	}, 
	prisma.Comment{
		ID:"cjsx2j8d902af0b256ye4f162", 
		CreatedAt:"2019-03-06T10:37:43.571Z", 
		Text:"Very interesting!"
	}
}

</Code>

Fetch a list of users:

users, err := client.Users(nil).Exec(ctx)

[]prisma.User{
	prisma.User{
		ID:"cjsx2j8bq028z0b253bstyggy",
		Name:(*string)(0xc0000102c0), 
		Email:"[email protected]"}, 
	prisma.User{
		ID:"cjsx2j8cb029k0b25nwwo9bkg",
		Name:(*string)(0xc000010410), 
		Email:"[email protected]"}, 
	prisma.User{
		ID:"cjsx2j8cz02a70b25law6s8y2",
		Name:(*string)(0xc0000105d0), 
		Email:"[email protected]"
	}
}

</Code>

Relations

Prisma client has a fluent API to query relations in your database. Meaning you can simply chain your method calls to navigate the relation properties of the returned records.

Examples

Fetch all the posts of a single user:

posts, err := client.User(prisma.UserWhereUniqueInput{
		Email: &email,
	}).Posts(nil).Exec(ctx)

[]prisma.Post{
	prisma.Post{
		ID:"cjsx2j8bu02900b25uhpv083r", 
		CreatedAt:"2019-03-06T10:37:43.526Z", 
		UpdatedAt:"2019-03-06T10:37:43.526Z", 
		Title:"Introducing the Analytical Engine", 
		Published:false
},
	prisma.Post{
		ID:"cjsx2j8bw02920b25rl806l07", 
		CreatedAt:"2019-03-06T10:37:43.526Z", 
		UpdatedAt:"2019-03-06T10:37:43.526Z", 
		Title:"Building General-Purpose Computers", 
		Published:true
		}, 
	prisma.Post{
		ID:"cjsx2j8bz02940b25r5hy5jua", 
		CreatedAt:"2019-03-06T10:37:43.526Z", 
		UpdatedAt:"2019-03-06T10:37:43.526Z", 
		Title:"RESTful APIs Considered Harmful", 
		Published:false
	}, 
	prisma.Post{
		ID:"cjsx2j8c102960b25z0d6ihel", 
		CreatedAt:"2019-03-06T10:37:43.526Z", 
		UpdatedAt:"2019-03-06T10:37:43.526Z", 
		Title:"Why Algorithms are Awesome", 
		Published:true
	}
}

</Code>

Basic filters for lists

Basic filters let you specify certain criteria to constrain which records should be returned in a list. The filters are specified in the Where struct of the params argument which is accepted by any list query.

The type of the Where struct depends on the model for which it was generated.

It is also possible to combine multiple filters using the AND and OR fields.

Examples

Fetch users that have an A in their names:

letter := "A"
usersWithAInName, err := client.Users(&prisma.UsersParams{
	Where: &prisma.UserWhereInput{
		NameContains: &letter,
	},
}).Exec(ctx)

[]prisma.User{
	prisma.User{
		ID:"cjsx2j8bq028z0b253bstyggy", 
		Name:(*string)(0xc00026da40), // Ada
		Email:"[email protected]"}, 
	prisma.User{
		ID:"cjsx2j8cb029k0b25nwwo9bkg", 
		Name:(*string)(0xc00026dbb0), // Grace
		Email:"[email protected]"
	}
}

</Code> <Collapse title="Use auto-completion to explore the filter system">

</Collapse>

Fetch users called Ada or Grace:

names := []string{"Ada", "Grace"}
users, err := client.Users(&prisma.UsersParams{
  Where: &prisma.UserWhereInput{
    NameIn: names,
  },
}).Exec(ctx)

[]prisma.User{
	prisma.User{
		ID:"cjsx2j8bq028z0b253bstyggy", 
		Name:(*string)(0xc000093110), // Ada
		Email:"[email protected]"}, 
	prisma.User{
		ID:"cjsx2j8cb029k0b25nwwo9bkg", 
		Name:(*string)(0xc000093470), // Grace
		Email:"[email protected]"
	}
}

</Code>

Fetch comments created before December 24, 2019:

christmas := "2019-12-24"
comments, err := client.Comments(&prisma.CommentsParams{
  Where: &prisma.CommentWhereInput{
    CreatedAtLt: &christmas,
  },
}).Exec(ctx)

[]prisma.Comment{
	prisma.Comment{
		ID:"cjsx2j8cm029r0b256m1qjc1z", 
		CreatedAt:"2019-03-06T10:37:43.547Z", 
		Text:"Great work!"}, 
	prisma.Comment{
		ID:"cjsx2j8d502ac0b2573tfihhd", 
		CreatedAt:"2019-03-06T10:37:43.570Z", 
		Text:"I love this."}, 
	prisma.Comment{
		ID:"cjsx2j8d902af0b256ye4f162", 
		CreatedAt:"2019-03-06T10:37:43.571Z", 
		Text:"Very interesting!"
	}
}

</Code>

Dates and times in the Prisma client API follow the ISO 8601 standard which generally is of the form: YYYY-MM-DDThh:mm:ss. Learn more.

Fetch posts that have prisma or graphql in their title and were created in 2019:

filter1 := "prisma"
filter2 := "graphql"
filteredPosts, err := client.Posts(&prisma.PostsParams{
	Where: &prisma.PostWhereInput{
		Or: []prisma.PostWhereInput{
			prisma.PostWhereInput{
				TitleContains: &filter1,
			},
			prisma.PostWhereInput{
				TitleContains: &filter2,
			},
		},
	},
}).Exec(ctx)

[]prisma.Post{
	prisma.Post{
		ID:"cjsx2j8ci029n0b25iadtorzi", 
		CreatedAt:"2019-03-06T10:37:43.547Z", 
		UpdatedAt:"2019-03-06T10:37:43.547Z", 
		Title:"GraphQL - The Query Language of the Future", 
		Published:true
	},
	prisma.Post{
		ID:"cjsviiljr0g9j0b43vntjbys1", 
		CreatedAt:"2019-03-06T10:38:43.547Z", 
		UpdatedAt:"2019-03-06T10:38:43.547Z", 
		Title:"Prisma replaces traditional ORMs", 
		Published:true
	},
}

</Code>

Relational filters for lists

Relational filters can be used to constrain the returned records on a relation list field. The types used for filtering are similar to basic filters, the major difference is that the filters are not applied on the root level of the method call but when querying a relation (via the fluent API) on a later level.

Examples

Fetch posts by a certain user that were created before christmas:

email := "[email protected]"
christmas := "2019-12-24"
posts, err := client.User(prisma.UserWhereUniqueInput{
	Email: &email,
}).Posts(&prisma.PostsParamsExec{
	Where: &prisma.PostWhereInput{
		CreatedAtLt: &christmas,
	},
}).Exec(ctx)

[]prisma.Post{
	prisma.Post{
		ID:"cjsx2j8bu02900b25uhpv083r", 
		CreatedAt:"2019-03-06T10:37:43.526Z", 
		UpdatedAt:"2019-03-06T10:37:43.526Z", 
		Title:"Introducing the Analytical Engine", 
		Published:false
	},
	prisma.Post{
		ID:"cjsx2j8bw02920b25rl806l07", 
		CreatedAt:"2019-03-06T10:37:43.526Z", 
		UpdatedAt:"2019-03-06T10:37:43.526Z", 
		Title:"Building General-Purpose Computers", 
		Published:true
	}, 
	prisma.Post{
		ID:"cjsx2j8bz02940b25r5hy5jua", 
		CreatedAt:"2019-03-06T10:37:43.526Z", 
		UpdatedAt:"2019-03-06T10:37:43.526Z", 
		Title:"RESTful APIs Considered Harmful", 
		Published:false
	}, 
	prisma.Post{
		ID:"cjsx2j8c102960b25z0d6ihel", 
		CreatedAt:"2019-03-06T10:37:43.526Z", 
		UpdatedAt:"2019-03-06T10:37:43.526Z", 
		Title:"Why Algorithms are Awesome", 
		Published:true
	}
}

</Code>

Ordering

When querying a list of records, you can order (sort) the list by any scalar field of that model. Each generated method to query a list of records therefore accepts the OrderBy field on the params input struct.

The type of the OrderBy field depends on the scalar fields of the model for which it was generated.

Note that you can always order by createdAt and updatedAt, even when the fields have not been added to your models.

Examples

Sort comments by their creation date (ascending):

orderBy := prisma.CommentOrderByInputCreatedAtAsc
comments, err := client.Comments(&prisma.CommentsParams{
  OrderBy: &orderBy,
}).Exec(ctx)

[]prisma.Comment{
	prisma.Comment{
		ID:"cjsyqxws1001a0982d3kqnulb", 
		CreatedAt:"2019-03-07T14:48:45.349Z", 
		Text:"Great work!"}, 
	prisma.Comment{
		ID:"cjsyqxwsp001v098231rodyl5", 
		CreatedAt:"2019-03-07T14:48:45.378Z", 
		Text:"I love this."}, 
	prisma.Comment{
		ID:"cjsyqxwss001y0982eg18knnm", 
		CreatedAt:"2019-03-07T14:48:45.378Z", 
		Text:"Very interesting!"
	}
}

</Code>

Sort users alphabetically by their names (descending):

orderBy := prisma.UserOrderByInputNameDesc
users, err := client.Users(&prisma.UsersParams{
	OrderBy: &orderBy,
}).Exec(ctx)

[]prisma.User{
	prisma.User{
		ID:"cjsyqxwsi001q09823az58z8v", 
		Name:(*string)(0xc0000117f0), // "Lynn"
		Email:"[email protected]"
	}, 
	prisma.User{
		ID:"cjsyqxwrr0013098281m7ajy9", 
		Name:(*string)(0xc000011920), // "Grace"
		Email:"[email protected]"
	}, 
	prisma.User{
		ID:"cjsyqxwq2000i0982qumb1o55", 
		Name:(*string)(0xc000011a50), // "Ada"
		Email:"[email protected]"
	}
}

</Code>

Pagination

When querying a list of records, you can fetch certain parts (i.e. pages) of that list by supplying pagination arguments.

Seeking forward and backward with `first` and `last`

You can seek forwards or backwards through the list and supply an optional starting point:

To seek forward, use first; specify the id of a starting record with after.
To seek backward, use last; specify the id of a starting record with before.

You cannot combine first with before or last with after. If you do so, before/after will simply be ignored and only first or last is actually applied (at the very beginning or end of the list, depending on which you're using).

Note that you can query for more records than actually exist in the database without an error message.

Skipping elements with `skip`

You can also skip an arbitrary amount of records in whichever direction you are seeking by supplying the skip argument:

When using first, skip skips records at the beginning of the list.
When using last, skip skips records from the end of the list.

For the following examples, we're assuming a list of exactly 30 records:

Fetch the first 3 posts (seeking forward):

first := int32(3)
posts, err := client.Posts(&prisma.PostsParams{
	First: &first,
}).Exec(ctx)

</Code>

Fetch the posts from position 6 to position 10 (seeking forward):

skip := int32(5)
first := int32(5)
posts, err := client.Posts(&prisma.PostsParams{
	First: &first,
	Skip:  &skip,
}).Exec(ctx)

</Code>

Fetch the last 3 posts (seeking backward):

last := int32(3)
posts, err := client.Posts(&prisma.PostsParams{
	Last: &last,
}).Exec(ctx)

</Code>

Fetch the posts from position 21 to position 27 (seeking backward):

skip := int32(3)
last := int32(7)
posts, err := client.Posts(&prisma.PostsParams{
	Last: &last,
	Skip:  &skip,
}).Exec(ctx)

</Code>

Fetch the first 3 posts after the posts with cixnen24p33lo0143bexvr52n as id:

first := int32(3)
after := "cjsyqxwqo000j0982da8cvw7o"
posts, err := client.Posts(&prisma.PostsParams{
  First: &first,
  After: &after,
}).Exec(ctx)

</Code>

Fetch the first 5 posts after the post with cixnen24p33lo0143bexvr52n as id and skipping 3 posts:

first := int32(5)
skip := int32(3)
after := "cjsyqxwqo000j0982da8cvw7o"
posts, err := client.Posts(&prisma.PostsParams{
  First: &first,
  After: &after,
  Skip: &skip,
}).Exec(ctx)

</Code>

Fetch the last 5 posts before the post with cixnen24p33lo0143bexvr52n as id:

last := int32(5)
before := "cixnen24p33lo0143bexvr52n"
posts, err := client.Posts(&prisma.PostsParams{
  Last:  &last,
  Before: &before,
}).Exec(ctx)

</Code>

Fetch the last 3 posts before the record with cixnen24p33lo0143bexvr52n as id and skipping 5 posts:

last := int32(3)
before := "cixnen24p33lo0143bexvr52n"
skip: := int32(5)
posts, err := client.Posts(&prisma.PostsParams{
  Last:  &last,
  Before: &before,
  Skip: &skip,
}).Exec(ctx)

</Code>

Aggregations

Aggregrations are currently not supported in the Prisma Go client. You can track the progress of this feature in this GitHub issue.

Overview

Fetching single records

Examples

Fetching lists

Examples

Relations

Examples

Basic filters for lists

Examples

Relational filters for lists

Examples

Ordering

Examples

Pagination

Seeking forward and backward with first and last

Skipping elements with skip

Aggregations

Seeking forward and backward with `first` and `last`

Skipping elements with `skip`