[wip] add subscription docs

docs/graphql-api/subscriptions/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Subscriptions",
+  "position": 3
+}

docs/graphql-api/subscriptions/index.mdx

@@ -0,0 +1,191 @@
+---
+sidebar_label: Subscriptions
+sidebar_position: 0
+description:
+  "Comprehensive guide to working with GraphQL Subscriptions and leveraging the real-time capabilities of Hasura's
+  GraphQL API. Explore functionalities like live updates, filtering, and multiple concurrent subscriptions. Learn more
+  about managing subscriptions effectively, and the use of variables, fragments, and directives."
+keywords:
+  - graphql subscriptions
+  - hasura graphql api
+  - hasura subscriptions
+  - real-time api
+  - live updates
+toc_max_heading_level: 4
+---
+
+# GraphQL Subscriptions
+
+GraphQL subscriptions allow you to push real-time updates from your database to clients, making them ideal for building
+reactive applications without constant polling.
+
+Subscriptions are supported for the following queries:
+
+- [Select unique](/supergraph-modeling/models.mdx#model-selectuniquegraphqldefinition)
+- [Select many](/supergraph-modeling/models.mdx#model-selectmanygraphqldefinition)
+- [Aggregate](/supergraph-modeling/models.mdx#model-modelaggregategraphqldefinition)
+
+Example:
+
+```graphql
+subscription UserNotificationSubscription {
+  notifications(where: { user_id: { _eq: 123 } }) {
+    id
+    created_at
+    message
+  }
+}
+```
+
+## Enabling Subscriptions
+
+You can enable subscriptions on your GraphQL API in the following ways:
+
+### Fresh Hasura DDN Project
+
+If you're starting fresh, set up a Hasura DDN project using the [quickstart](/getting-started/quickstart.mdx) guide.
+Once your models are added to the supergraph using the [`ddn model add`](/cli/commands/ddn_model_add.mdx) command,
+subscription capabilities are automatically generated for them. For futher customization, you can manually
+[update the metadata](#manual-metadata-configuration).
+
+### Existing Project
+
+To enable subscriptions in an existing DDN project, use the following CLI command:
+
+```bash
+ddn codemod enable-model-subscriptions
+```
+
+This command updates the local metadata files, adding subscription-specific configurations. After running this, create a
+supergraph build and test the subscriptions on the API. For futher customization, you can manually
+[update the metadata](#manual-metadata-configuration).
+
+### Manual Metadata Configuration
+
+You can manually configure subscriptions by editing the metadata HML files in your DDN project.
+
+#### Root Type Name
+
+Set or update the subscription root type in your GraphQL API by modifying the `graphql-config.hml` file located at
+`globals/metadata/graphql-config.hml`. This ensures the subscription root type is defined, which is necessary for
+enabling subscriptions. You will have to add the following in the `definition` for
+[`GraphqlConfig`](/supergraph-modeling/graphql-config.mdx#graphqlconfig-graphqlconfig)
+
+```yaml
+subscription:
+  rootOperationTypeName: Subscription
+```
+
+Example:
+
+```yaml {8-9} title="<project-root>/globals/metadata/graphql-config.hml"
+kind: GraphqlConfig
+version: v1
+definition:
+  query:
+    rootOperationTypeName: Query
+  mutation:
+    rootOperationTypeName: Mutation
+  subscription:
+    rootOperationTypeName: Subscription
+```
+
+#### Model Root Field
+
+For each model, update the root field name for subscriptions in the corresponding model's HML file. You can also
+configure other optional parameters, such as the [polling interval](#polling-interval), the root field's description,
+and its deprecation status.
+
+An example of an `Article` [model definition](/supergraph-modeling/models.mdx#model-model) with subscriptions enabled
+for the `selectMany`, `selectUniques`, and `aggregate` root fields:
+
+```yaml {13-15,20-24,29-30} title="<project-root>/<subgraph-name>/metadata/Article.hml"
+kind: Model
+version: v1
+definition:
+  name: Article
+  objectType: Article
+  source:
+    dataConnectorName: my_connector
+    collection: article
+  aggregateExpression: ArticleAggExp
+  graphql:
+    selectMany:
+      queryRootField: article
+      subscription:
+        rootField: article
+        description: Subscribe to article model
+    selectUniques:
+      - queryRootField: articleById
+        uniqueIdentifier:
+          - id
+        subscription:
+          rootFIeld: articleById
+          description: Subscribe to article model by its unique id
+          deprecated:
+            reason: Use article root field with filters
+    orderByExpressionType: ArticleOrderBy
+    filterInputTypeName: ArticleFilterInput
+    aggregate:
+      queryRootField: articleAggregate
+      subscription:
+        rootField: articleAggregate
+```
+
+#### Polling Interval
+
+You can set the polling interval (in milliseconds) within the model's
+[GraphQL definition](/supergraph-modeling/models.mdx#model-modelgraphqldefinition) to determine how often the engine
+checks for updates. If not specified, the interval defaults to `1000` milliseconds (1 second).
+
+:::info Note
+
+Choosing the right polling interval is key to the performance and stability of your subscription API. Setting too short
+an interval can overburden your database, while setting it too long may cause delays in receiving critical updates.
+Ensure that your polling interval balances real-time performance with system load.
+
+:::
+
+An example of an `Article` [model definition](/supergraph-modeling/models.mdx#model-model) that has a custom polling
+interval configured for the `selectMany` subscription field:
+
+```yaml {15} title="<project-root>/<subgraph-name>/metadata/Article.hml"
+kind: Model
+version: v1
+definition:
+  name: Article
+  objectType: Article
+  source:
+    dataConnectorName: my_connector
+    collection: article
+  aggregateExpression: ArticleAggExp
+  graphql:
+    selectMany:
+      queryRootField: article
+      subscription:
+        rootField: article
+        pollingIntervalMs: 2000 # 2 seconds
+    orderByExpressionType: ArticleOrderBy
+    filterInputTypeName: ArticleFilterInput
+```
+
+#### Permissions
+
+Access to subscription root fields is managed through the `select`
+[permission definition](/supergraph-modeling/permissions.mdx#modelpermissions-selectpermission). To allow a role to use
+subscriptions for a specific model, set `allowSubscriptions` to `true` in the model's
+[permission definition](/supergraph-modeling/permissions.mdx#modelpermissions-modelpermissions).
+
+Example of a select permission for an `Article` model with subscriptions allowed for the `user` role:
+
+```yaml {9} title="<project-root>/<subgraph-name>/metadata/Article.hml"
+kind: ModelPermissions
+version: v1
+definition:
+  modelName: Article
+  permissions:
+    - role: user
+      select:
+        filter: null
+        allowSubscriptions: true
+```

docs/project-configuration/config.mdx

@@ -344,7 +344,7 @@ For example:
 - `auth-config.hml` contain the `AuthConfig` object which define the authentication configuration for the supergraph.
 - `compatibility-config.hml` file contains the compatibility date configuration for the supergraph.
 - `graphql-config.hml` file contains the GraphQL configuration for the supergraph, which allows you to customize the
-  available query and mutation capabilities along with the schema.
+  available query, mutation and subscription capabilities along with the schema.
 - `subgraph.yaml` contains the config that describes how to build the globals subgraph.
 
 ### App subgraph directory {#app}