diff --git a/docs/graphql-api/subscriptions/_category_.json b/docs/graphql-api/subscriptions/_category_.json new file mode 100644 index 000000000..83249768b --- /dev/null +++ b/docs/graphql-api/subscriptions/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Subscriptions", + "position": 3 +} diff --git a/docs/graphql-api/subscriptions/index.mdx b/docs/graphql-api/subscriptions/index.mdx new file mode 100644 index 000000000..b14b2c48c --- /dev/null +++ b/docs/graphql-api/subscriptions/index.mdx @@ -0,0 +1,198 @@ +--- +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="/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="//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 with excessive queries, which can degrade performance, especially in +high-traffic environments. Conversely, setting too long an interval may delay critical updates, making your real-time +application less responsive. + +For example, a short interval might be necessary for live sports score updates or stock trading platforms where +real-time precision is critical. A longer interval could be suitable for use cases like updating daily sales reports, or +sending periodic system health metrics—scenarios where updates are not urgent, and system stability is prioritized over +immediate data freshness. The default setting of 1 second is chosen to accommodate most use cases, but should be +adjusted based on your specific real-time needs. + +::: + +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="//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="//metadata/Article.hml" +kind: ModelPermissions +version: v1 +definition: + modelName: Article + permissions: + - role: user + select: + filter: null + allowSubscriptions: true +``` diff --git a/docs/project-configuration/config.mdx b/docs/project-configuration/config.mdx index 450007729..62cddac3b 100644 --- a/docs/project-configuration/config.mdx +++ b/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}