docs: omit operator (tailcallhq#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 <[email protected]>

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. |

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)
+:::

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).