From f9818f2cfc5a4335badc832d2256e8cd4796bed5 Mon Sep 17 00:00:00 2001
From: neo773 <62795688+neo773@users.noreply.github.com>
Date: Thu, 29 Feb 2024 04:56:22 +0530
Subject: [PATCH] docs: omit operator (#115)

* docs: omit operator

* fix: add changes

* chore: run prettier

* fix: add changes

* update title

* fix: add backlink to modify

* fix: typo

---------

Co-authored-by: Tushar Mathur <tusharmath@gmail.com>
---
 docs/operators/index.md  |  1 +
 docs/operators/modify.md |  4 ++++
 docs/operators/omit.md   | 37 +++++++++++++++++++++++++++++++++++++
 3 files changed, 42 insertions(+)
 create mode 100644 docs/operators/omit.md

diff --git a/docs/operators/index.md b/docs/operators/index.md
index b7aa9cdc0..7d4d406e1 100644
--- a/docs/operators/index.md
+++ b/docs/operators/index.md
@@ -19,5 +19,6 @@ Certainly! Here's the table with hyperlinks added back to the operator names:
 | [@grpc](grpc.md)          | Resolves a field or node by a gRPC API.                                                                      |
 | [@http](http.md)          | Resolves a field or node by a REST API.                                                                      |
 | [@modify](modify.md)      | Enables changes to attributes of fields or nodes in the schema.                                              |
+| [@omit](omit.md)          | Excludes fields or nodes from the generated schema, making them inaccessible through the GraphQL API.        |
 | [@server](server.md)      | Provides server configurations for behavior tuning and tailcall optimization in specific use-cases.          |
 | [@upstream](upstream.md)  | Controls aspects of the upstream server connection, including timeouts and keep-alive settings.              |
diff --git a/docs/operators/modify.md b/docs/operators/modify.md
index 927e14da9..ad36455da 100644
--- a/docs/operators/modify.md
+++ b/docs/operators/modify.md
@@ -27,3 +27,7 @@ type User {
 ```
 
 `@modify(omit: true)` instructs GraphQL to exclude the `id` field from the schema, making it inaccessible to the client.
+
+:::tip
+**@omit** is a standalone operator and is an alias/shorthand for `modify(omit: true)` checkout [documentation](/docs/operators/omit)
+:::
diff --git a/docs/operators/omit.md b/docs/operators/omit.md
new file mode 100644
index 000000000..d4b7235ae
--- /dev/null
+++ b/docs/operators/omit.md
@@ -0,0 +1,37 @@
+---
+title: "@omit"
+---
+
+Within a GraphQL schema, the **@omit** operator excludes fields or nodes from the generated schema, making them inaccessible through the GraphQL API. This operator is useful for hiding sensitive information or simplifying your API by removing unnecessary fields.
+
+## How it works
+
+When applied to a field or node, the **@omit** operator instructs the Tailcall not to include that field or node in the schema. This means that clients cannot query or mutate data in those fields.
+
+## Example
+
+Consider a scenario where you have a `User` type with an embedded `Address` type. If you want to exclude the `Address` type from the schema to simplify the API, you can use the **@omit** operator:
+
+```graphql showLineNumbers
+type Address {
+  city: String
+  street: String
+}
+
+type User {
+  name: String
+  address: Address @omit
+}
+```
+
+In this example, the `address` field will not be accessible or visible through the GraphQL API.
+
+## Comparison with `modify`
+
+The **@omit** operator and `@modify(omit: true)` essentially serve the same purpose in excluding fields from the schema, but they differ in syntax and flexibility. In fact, one can consider **@omit** as a shorthand or alias for the more verbose `@modify(omit: true)`.
+
+- **@omit** offers a concise way to directly exclude a field or node without additional arguments.
+
+- `@modify(omit: true)`, as part of the broader **@modify** operator, provides more options, such as field renaming through the `name` argument. This makes it a more flexible choice when you need more than field exclusion.
+
+For more details on the **@modify** operator and its capabilities, including omitting fields, see the [@modify documentation](/docs/operators/modify#omit).