diff --git a/docs/docs/graphql/core/databases/postgres/subscriptions/index.mdx b/docs/docs/graphql/core/databases/postgres/subscriptions/index.mdx index 065cdf3c46d..f28cc6c8953 100644 --- a/docs/docs/graphql/core/databases/postgres/subscriptions/index.mdx +++ b/docs/docs/graphql/core/databases/postgres/subscriptions/index.mdx @@ -18,21 +18,6 @@ an update whenever the value of any field changes upstream. Subscriptions are supported for all kinds of queries. All the concepts of [queries](/graphql/core/databases/postgres/queries/index.mdx) hold true for subscriptions as well. -## Implementation - -The Hasura GraphQL engine subscriptions are actually **live queries**, -i.e. a subscription will return the latest result of the query being -made and not necessarily all the individual events leading up to the -result. By default, updates are delivered to clients every **1 sec**. - -See more details on -`subscriptions execution and performance [subscriptions execution and performance](/graphql/core/databases/postgres/subscriptions/execution-and-performance.mdx). - -## Convert a query to a subscription - -You can turn any query into a subscription by simply replacing `query` -with `subscription` as the operation type. - :::info Caveat Hasura follows the [GraphQL spec](https://graphql.github.io/graphql-spec/June2018/#sec-Single-root-field) @@ -40,11 +25,84 @@ which allows for only one root field in a subscription. ::: -## Use cases +## Types of subscriptions -- [Subscribe to the latest value of a particular field](/graphql/core/databases/postgres/subscriptions/use-cases.mdx#pg-subscribe-field) -- [Subscribe to changes to a table’s entries](/graphql/core/databases/postgres/subscriptions/use-cases.mdx#pg-subscribe-table) -- [Subscribe to the latest value of some derived data](/graphql/core/databases/postgres/subscriptions/use-cases.mdx#pg-subscribe-derived) +### Live queries + + +A live query subscription will return the latest result of the query being made +and not necessarily all the individual events leading up to the result. +By default, updates are delivered to clients every **1 sec**. + +See more details [here](/graphql/core/databases/postgres/subscriptions/livequery/index.mdx). + +### Streaming subscriptions + +A streaming subscription streams the response according to the cursor input +by the user. A streaming subscription is different from a live query as it sends individual rows +at a time and not the entire result set. + +See more details [here](/graphql/core/databases/postgres/subscriptions/streaming/index.mdx). + +### Live query vs Streaming subscriptions + +Suppose we need to display the messages of a group chat on a page, this can be done either via +live queries or streaming subscriptions. Let's see how they can be used and how they differ from each other. + +1. Using **live query** + + With live query, we'll make the following query: + + ```graphql + + subscription { + messages ( + where: {group_id: 1}, + order_by: {created_at: asc} + ) { + id + sender + reciever + content + created_at + edited_at + } + } + ``` + + The initial response for this subscription will be all the messages of the group. Let's say the initial + response contained 100 messages. Now, if there is one more message sent to the group, then all 101 messages + will be sent in a new response. + + +2. Using **streaming subscriptions** + + With streaming subscriptions, we'll make the following query: + + ```graphql + + subscription { + messages_stream ( + where: {group_id: 1}, + cursor: {initial_value: {created_at: now}}, + batch_size: 10 + ) { + id + sender + reciever + content + created_at + edited_at + } + } + ``` + + Here, we'll start getting all messages of the group in batches given by ``batch_size`` with ``created_at`` + greater than ``now``. + + Following the example of the live query, if we have 100 messages corresponding to the group and only + 5 messages with ``created_at`` greater than the current value of the cursor maintained by the cursor, then + we will get only the 5 messages. ## Communication protocol diff --git a/docs/docs/graphql/core/databases/postgres/subscriptions/execution-and-performance.mdx b/docs/docs/graphql/core/databases/postgres/subscriptions/livequery/execution-and-performance.mdx similarity index 100% rename from docs/docs/graphql/core/databases/postgres/subscriptions/execution-and-performance.mdx rename to docs/docs/graphql/core/databases/postgres/subscriptions/livequery/execution-and-performance.mdx diff --git a/docs/docs/graphql/core/databases/postgres/subscriptions/livequery/index.mdx b/docs/docs/graphql/core/databases/postgres/subscriptions/livequery/index.mdx new file mode 100644 index 00000000000..13d6aeb168c --- /dev/null +++ b/docs/docs/graphql/core/databases/postgres/subscriptions/livequery/index.mdx @@ -0,0 +1,40 @@ +--- +description: Manage subscriptions on Postgres with Hasura +sidebar_label: Live queries +keywords: + - hasura + - docs + - postgres + - subscription + - live queries +slug: index +--- + +# Postgres: Live query subscriptions + +## Introduction + +A Live query subscription will return the latest result of the query being made +and not necessarily all the individual events leading up to the result. + +By default, updates are delivered to clients every **1 sec**. + +See more details on [subscriptions execution and performance](/graphql/core/databases/postgres/subscriptions/livequery/execution-and-performance.mdx). + +## Convert a query to a subscription + +You can turn any query into a subscription by simply replacing `query` +with `subscription` as the operation type. + +:::info Caveat + +Hasura follows the [GraphQL spec](https://graphql.github.io/graphql-spec/June2018/#sec-Single-root-field) +which allows for only one root field in a subscription. + +::: + +## Use cases + +- [Subscribe to the latest value of a particular field](/graphql/core/databases/postgres/subscriptions/livequery/use-cases.mdx#pg-subscribe-field) +- [Subscribe to changes to a table’s entries](/graphql/core/databases/postgres/subscriptions/livequery/use-cases.mdx#pg-subscribe-table) +- [Subscribe to the latest value of some derived data](/graphql/core/databases/postgres/subscriptions/livequery/use-cases.mdx#pg-subscribe-derived) diff --git a/docs/docs/graphql/core/databases/postgres/subscriptions/use-cases.mdx b/docs/docs/graphql/core/databases/postgres/subscriptions/livequery/use-cases.mdx similarity index 96% rename from docs/docs/graphql/core/databases/postgres/subscriptions/use-cases.mdx rename to docs/docs/graphql/core/databases/postgres/subscriptions/livequery/use-cases.mdx index aea65ea8a55..981b8da2854 100644 --- a/docs/docs/graphql/core/databases/postgres/subscriptions/use-cases.mdx +++ b/docs/docs/graphql/core/databases/postgres/subscriptions/livequery/use-cases.mdx @@ -11,11 +11,11 @@ keywords: import GraphiQLIDE from '@site/src/components/GraphiQLIDE'; -# Subscriptions sample use cases +# Live query subscriptions sample use cases ## Introduction -The following are a few use cases for using subscriptions: +The following are a few use cases for using live query subscriptions: ## Subscribe to the latest value of a particular field {#pg-subscribe-field} @@ -84,7 +84,7 @@ variables={`{ In case you are interested in all the additions/changes to a table's entries, you can use subscriptions to fetch the table rows and get -updates whenever there are any additions/changes to the table. +live query updates whenever there are any additions/changes to the table. ### Example: Chat app @@ -227,7 +227,7 @@ subscription getResult($pollId: Int!) { ) { poll_id poll { - question + question } option { texts @@ -278,7 +278,7 @@ response={`{ }, "option": { "texts": "Burger" - }, + }, "votes": 3 }, { diff --git a/docs/graphql/core/databases/postgres/subscriptions/streaming/index.rst b/docs/docs/graphql/core/databases/postgres/subscriptions/streaming/index.mdx similarity index 55% rename from docs/graphql/core/databases/postgres/subscriptions/streaming/index.rst rename to docs/docs/graphql/core/databases/postgres/subscriptions/streaming/index.mdx index b5e5c406606..cb8c4567c88 100644 --- a/docs/graphql/core/databases/postgres/subscriptions/streaming/index.rst +++ b/docs/docs/graphql/core/databases/postgres/subscriptions/streaming/index.mdx @@ -1,58 +1,49 @@ -.. meta:: - :description: Streaming subscriptions with Hasura - :keywords: hasura, docs, subscription, streaming +--- +description: Streaming subscriptions with Hasura +sidebar_label: Streaming subscriptions +keywords: + - hasura + - docs + - subscription + - streaming + - postgres +slug: index +--- -.. _pg_streaming_subscriptions: +# Postgres: Streaming subscriptions -Postgres: Streaming subscriptions -================================= - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - - -Introduction ------------- +## Introduction A streaming subscription streams the response according to the cursor provided by the user while making the subscription. Streaming subscriptions can be used to subscribe only to the data which has been newly added to the result set. -.. admonition:: Supported from +:::tip Supported from - Streaming subscriptions are supported in Hasura GraphQL engine versions ``v2.5.0-beta.1`` and above. + Streaming subscriptions are supported in Hasura GraphQL engine versions ``v2.7.0-beta.1`` and above. -.. admonition:: Enabling streaming subscriptions +:::tip Enabling streaming subscriptions Streaming subscriptions in the graphql-engine are disabled by default. To enable it, set the environment variable ``HASURA_GRAPHQL_EXPERIMENTAL_FEATURES`` to ``streaming_subscriptions``. -How it works? -------------- +## How it works? In streaming subscriptions, the server maintains a cursor value with a subscription and after streaming each batch, the value of the cursor is updated. Ideally, the cursor chosen should represent unique and sortable values so that each row is sent exactly once to a subscriber. Streaming subscriptions work well with other Hasura features like -:ref:`permissions ` and :ref:`relationships ` and also -leverage the power of :ref:`multiplexing `. +[permissions](/graphql/core/auth/authorization/permission-rules.mdx#select-permissions) and [relationships](/graphql/core/databases/postgres/schema/table-relationships/index.mdx#table-relationships) and also +leverage the power of +[subscriptions multiplexing](/graphql/core/databases/postgres/subscriptions/livequery/execution-and-performance.mdx#subscription-multiplexing). -.. note:: +:::info Note In the case of streaming subscriptions, the multiplexed batch size can be configured via ``HASURA_GRAPHQL_STREAMING_QUERIES_MULTIPLEXED_BATCH_SIZE`` and the refetch interval can be configured via ``HASURA_GRAPHQL_STREAMING_QUERIES_MULTIPLEXED_REFETCH_INTERVAL``. -Use cases ---------- +## Use cases -- :ref:`pg_streaming_subscriptions_use_cases` - -.. toctree:: - :maxdepth: 1 - :hidden: - - Sample use cases +- [Subscribe to the undelivered messages in a chat application](/graphql/core/databases/postgres/subscriptions/streaming/use-cases.mdx) diff --git a/docs/graphql/core/databases/postgres/subscriptions/streaming/use-cases.rst b/docs/docs/graphql/core/databases/postgres/subscriptions/streaming/use-cases.mdx similarity index 82% rename from docs/graphql/core/databases/postgres/subscriptions/streaming/use-cases.rst rename to docs/docs/graphql/core/databases/postgres/subscriptions/streaming/use-cases.mdx index d8b74ad1a9b..a1baf5b659b 100644 --- a/docs/graphql/core/databases/postgres/subscriptions/streaming/use-cases.rst +++ b/docs/docs/graphql/core/databases/postgres/subscriptions/streaming/use-cases.mdx @@ -1,39 +1,32 @@ -.. meta:: - :description: Use cases for Hasura streaming subscriptions - :keywords: hasura, docs, subscription, use case, streaming +--- +description: Use cases for Hasura streaming subscriptions +sidebar_label: Sample use cases +sidebar_position: 1 +keywords: + - hasura + - docs + - subscription + - streaming + - use cases + - postgres +--- -.. _pg_streaming_subscriptions_use_cases: +# Streaming subscriptions sample use cases -Streaming subscriptions sample use cases -======================================== - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - -Introduction ------------- +## Introduction The following are a few use cases for using streaming subscriptions: -.. _pg_streaming_changed_events: - -Subscribing only to the events that have been changed ------------------------------------------------------ +### Subscribing only to the events that have been changed In case you are interested only in the latest events, you can use streaming subscriptions to fetch those events. -.. _pg_get_undelivered_messages: - -Get the undelivered messages in a chat application --------------------------------------------------- +### Get the undelivered messages in a chat application Consider the following schema: -.. code-block:: sql - +```sql messages ( id serial primary key, from_id uuid references users(id), @@ -49,11 +42,11 @@ Consider the following schema: last_name text, created_at timestamptz default current_timestamp ) +``` and the following messages need to be streamed: -.. code-block:: json - +```json [ { "id": 432432, @@ -100,11 +93,11 @@ and the following messages need to be streamed: "created_at": "2020-01-01 01:01:20" } ] +``` To stream the latest undelivered messages: -.. code-block:: graphql - +```graphql subscription getUndeliveredMessages { # will get all the messages that have `created_at > 2022-01-01` in batches of 100 rows messages_stream(cursor: {created_at: "2022-01-01", ordering: ASC}, batch_size: 2) { @@ -119,11 +112,11 @@ To stream the latest undelivered messages: created_at } } +``` The first response sent will be: -.. code-block:: json - +```json { "data": { "messages_stream": [ @@ -152,12 +145,13 @@ The first response sent will be: ] } } +``` The next response sent will be the following, note that the messages sent have ``created_at > 2020-01-01 01:01:20``, the greatest value of the cursor column sent in the previous response. -.. code-block:: json +```json { "data": { @@ -187,7 +181,4 @@ column sent in the previous response. ] } } - -.. toctree:: - :maxdepth: 1 - :hidden: +``` diff --git a/docs/docs/graphql/core/deployment/graphql-engine-flags/reference.mdx b/docs/docs/graphql/core/deployment/graphql-engine-flags/reference.mdx index d96abb9ba8f..35c31cb89d2 100644 --- a/docs/docs/graphql/core/deployment/graphql-engine-flags/reference.mdx +++ b/docs/docs/graphql/core/deployment/graphql-engine-flags/reference.mdx @@ -223,7 +223,7 @@ Enable the Hasura Console (served by the server on `/` and `/console`) (default: -A JSON string containing type and the JWK used for verifying (and other optional details). Example: +A JSON string containing type and the JWK used for verifying (and other optional details). Example: `{"type": "HS256", "key": "3bd561c37d214b4496d09049fadc542c"}`. See the JWT docs for more details. @@ -242,9 +242,9 @@ A JSON string containing type and the JWK used for verifying (and other optional -Unauthorized role, used when access-key is not sent in access-key only mode or the +Unauthorized role, used when access-key is not sent in access-key only mode or the `Authorization` header is absent in JWT mode. Example: `anonymous`. Now whenever the -"authorization" header is absent, the request's role will default to +"authorization" header is absent, the request's role will default to `anonymous`. @@ -358,7 +358,7 @@ Maximum number of events to be fetched from the DB in a single batch (default: 1 -Interval in milliseconds to sleep before trying to fetch async actions again after a fetch returned no async actions from metadata storage. Value +Interval in milliseconds to sleep before trying to fetch async actions again after a fetch returned no async actions from metadata storage. Value `0` implies completely disable fetching async actions from the storage. (Available for versions > v2.0.0) @@ -505,7 +505,7 @@ Time from connection creation after which the connection should be destroyed and -Stringify certain Postgres numeric types, specifically +Stringify certain Postgres numeric types, specifically `bigint` ,`numeric` ,`decimal` and `double precision` as they don't fit into the `IEEE-754` spec for JSON encoding-decoding. (default: false) @@ -558,6 +558,32 @@ Comma separated list of APIs (options: `metadata`, `graphql`, `pgdump`, `config` +`--streaming-queries-multiplexed-refetch-interval` + + + + +`HASURA_GRAPHQL_STREAMING_QUERIES_MULTIPLEXED_REFETCH_INTERVAL` + + +Updated results (if any) will be sent at most once in this interval (in milliseconds) for streaming queries which can be multiplexed. Default: 1000 (1sec) + + + + +`--streaming-queries-multiplexed-batch-size` + + + + +`HASURA_GRAPHQL_STREAMING_QUERIES_MULTIPLEXED_BATCH_SIZE` + + +Multiplexed streaming queries are split into batches of the specified size. Default: 100 + + + + `--enable-allowlist` @@ -603,7 +629,7 @@ Set the value to `/srv/console-assets` for the console to load assets from the s -Set the enabled log types. This is a comma-separated list of log-types to enable. Default: +Set the enabled log types. This is a comma-separated list of log-types to enable. Default: `startup, http-log, webhook-log, websocket-log`. See [log types](/graphql/core/deployment/logging.mdx#log-types) for more details. @@ -639,7 +665,7 @@ Set the logging level. Default: `info`. Options: `debug`, `info`, `warn`, `error -Set dev mode for GraphQL requests; include the +Set dev mode for GraphQL requests; include the `internal` key in the errors extensions of the response (if required). (Available for versions > v1.2.0) @@ -696,7 +722,7 @@ Enable remote schema permissions (default: `false`) -When the `--infer-function-permissions` flag is set to `false`, a function `f`, stable, immutable or volatile is only exposed for a role +When the `--infer-function-permissions` flag is set to `false`, a function `f`, stable, immutable or volatile is only exposed for a role `r` if there is a permission defined on the function `f` for the role `r`, creating a function permission will only be allowed if there is a select permission on the table type. When the `--infer-function-permissions` flag is set to `true` or the flag is omitted (defaults to `true`), the permission of the function is inferred from the select permissions from the target table of the function, only for stable/immutable functions. Volatile functions are not exposed to any of the roles in this case. @@ -732,8 +758,8 @@ When the `--infer-function-permissions` flag is set to `true` or the flag is omi -List of experimental features to be enabled. A comma separated value is expected. Options: -`inherited_roles`. +List of experimental features to be enabled. A comma separated value is expected. Options: +`inherited_roles, optimize_permission_filters, streaming_subscriptions`. (Available for versions > v2.0.0) @@ -801,8 +827,8 @@ Disable updating of metadata on the server (default: `false`) -Used to set the `Keep Alive` delay for client that use the -`subscription-transport-ws` (Apollo) protocol. For `graphql-ws` clients the graphql-engine sends +Used to set the `Keep Alive` delay for client that use the +`subscription-transport-ws` (Apollo) protocol. For `graphql-ws` clients the graphql-engine sends `PING` messages instead. (default: `5`) @@ -824,8 +850,8 @@ Used to set the `Keep Alive` delay for client that use the -Used to set the connection initialisation timeout for -`graphql-ws` clients. This is ignored for +Used to set the connection initialisation timeout for +`graphql-ws` clients. This is ignored for `subscription-transport-ws` (Apollo) clients. (default: `3`) @@ -840,4 +866,4 @@ Used to set the connection initialisation timeout for When the equivalent flags for environment variables are used, the flags will take precedence. -::: \ No newline at end of file +:::