From e8eef2fb105059c600ef24a4a5c8ca2bba67bd96 Mon Sep 17 00:00:00 2001
From: Luca Steeb <contact@luca-steeb.com>
Date: Sun, 28 Apr 2024 17:09:19 +0100
Subject: [PATCH] docs(fields): add select & omit docs (#1253)

---
 docs/pages/docs/walkthrough/_meta.json |  1 +
 docs/pages/docs/walkthrough/fields.md  | 51 ++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)
 create mode 100644 docs/pages/docs/walkthrough/fields.md

diff --git a/docs/pages/docs/walkthrough/_meta.json b/docs/pages/docs/walkthrough/_meta.json
index f1ad07b43..22e707a21 100644
--- a/docs/pages/docs/walkthrough/_meta.json
+++ b/docs/pages/docs/walkthrough/_meta.json
@@ -14,5 +14,6 @@
   "raw": "",
   "transactions": "",
   "composite": "",
+  "fields": "",
   "limitations": ""
 }
diff --git a/docs/pages/docs/walkthrough/fields.md b/docs/pages/docs/walkthrough/fields.md
new file mode 100644
index 000000000..bd6d10a42
--- /dev/null
+++ b/docs/pages/docs/walkthrough/fields.md
@@ -0,0 +1,51 @@
+# Field selection and omission
+
+You can select or omit fields in the query API. This is useful for reducing the amount of data you need to fetch, or
+for reducing the amount of data you need to send from the database to the client (up until to the end user)
+
+The examples use the following prisma schema:
+
+```prisma
+model User {
+  id        String   @id @default(cuid())
+  name      String?
+  password  String?
+  age       Int?
+}
+```
+
+## Notes
+
+You can only select or omit fields in a query, not both.
+
+## Select
+
+Select returns only the fields you specify, and nothing else.
+
+```go
+users, err := client.User.FindMany(
+  User.Name.Equals("john"),
+).Select(
+  User.Name.Field(),
+).Exec(ctx)
+if err != nil {
+  panic(err)
+}
+```
+
+## Omit
+
+Omit returns all fields except the ones you specify.
+
+```go
+users, err := client.User.FindMany(
+  User.Name.Equals("a"),
+).Omit(
+  User.ID.Field(),
+  User.Password.Field(),
+  User.Age.Field(),
+  User.Name.Field(),
+).Exec(ctx)
+if err != nil {
+  panic(err)
+}