docs: Subscription tuning

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com>
Co-authored-by: Tirumarai Selvan <8663570+tirumaraiselvan@users.noreply.github.com>
GitOrigin-RevId: 9217d9d7520d424b8092cce1ec0f98b780122c77

docs/graphql/core/databases/postgres/subscriptions/execution-and-performance.rst

@@ -0,0 +1,109 @@
+.. meta::
+    :description: Tuning Hasura for High-performance Subscriptions
+    :keywords: hasura, docs, subscriptions, performance, tuning
+ 
+.. _subscriptions_execution_and_performance:
+
+Subscriptions execution and performance
+=======================================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 2
+  :local:
+
+Introduction
+------------
+
+Hasura Graphql Subscriptions are **live queries** executing over the Websocket protocol to fetch near real-time data from the database. 
+
+Execution
+---------
+
+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 the individual events leading up to the result.
+
+Subscriptions, on start, will emit the result of the underlying query. Subsequently, results will be emitted only if the result of the query changes underneath (via insert/update/delete on the subscribed resource).
+
+Subscription multiplexing
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Hasura optimizes subscriptions by combining multiple similar subscriptions into one SQL query and getting a single response from the database instead of
+making separate SQL queries for each subscription. Each row in the response contains the result for a different subscription. Once Hasura gets the response
+from the database, it diff-checks the individual responses and returns the result to the clients only if there is any difference in their data.
+
+Multiplexed live queries are further split into batches which can be configured via ``HASURA_GRAPHQL_LIVE_QUERIES_MULTIPLEXED_BATCH_SIZE`` environment
+variable or the ``--live-queries-multiplexed-batch-size`` flag. By default this value is set to ``100``.
+
+For example, with the default value, if there are 1000 subscription clients with similar queries, Hasura multiplexes 100 subscriptions into
+1 batch and make a single SQL query to the DB for that batch. So, in total there will be only 10 SQL queries to the DB for the 1000 subscriptions.
+
+Example
+^^^^^^^
+
+A practical use of subscriptions can be for tracking the live locations of delivery agents carrying food orders in a food-ordering system.
+
+The setup is operating with the default Hasura params of subscription refetch interval as 1 second and multiplexed batch size as 100.
+
+The below figure shows multiplexing in action, where the 3 similar subscriptions differing only in the variables are batched into one SQL:
+
+.. thumbnail:: /img/graphql/core/databases/postgres/subscriptions/subscription-multiplexing.png
+    :class: no-shadow
+    :width: 900px
+    :alt: Hasura subscription multiplexing AST
+
+In this case, all 3 subscriptions are multiplexed into 1 batch resulting in 1 SQL query which is run every 1 second. If there is an
+update in the location, the appropriate client gets sent the updated data.
+
+Tuning subscription performance
+-------------------------------
+
+Analyze
+^^^^^^^
+
+Subscriptions can be 'Analyzed' (from the Analyze button in GraphiQl window of Hasura console) to see the generated multiplexed SQL and its query plan. The query plan can reveal the bottlenecks in query execution and appropriate indexes can be added to improve performance.
+
+In addition to these, simplifying the subscription to avoid unnecessary joins or avoiding fetching fields which are not going to change can also help improve performance.
+
+Parameters
+^^^^^^^^^^
+
+The parameters governing the performance of subscriptions in terms of throughput, latency and resource utilization are:
+
+* ``HASURA_GRAPHQL_LIVE_QUERIES_MULTIPLEXED_REFETCH_INTERVAL``
+
+  * Time interval between Hasura multiplexed queries to the DB for fetching changes in subscriptions data, default = 1 sec
+
+  * Increasing this reduces frequency of queries to the DB thereby reducing the load on it and improving throughput while increasing the
+    latency of updates to the clients.
+
+* ``HASURA_GRAPHQL_LIVE_QUERIES_MULTIPLEXED_BATCH_SIZE``
+
+  * Number of similar subscriptions batched into a single SQL query to the DB, default = 100
+
+  * Increasing this reduces the number of SQL statements fired to the DB thereby reducing the load on it and improving throughput while
+    increasing individual SQL execution times and hence latency.
+
+  * This value should be reduced in case the execution time of the SQL generated by Hasura after multiplexing is more than the
+    refetch interval.
+
+* ``HASURA_GRAPHQL_PG_CONNECTIONS``
+
+  * Max number of connection Hasura opens with the DB, default = 50
+
+  * Increasing this increases the number of connections that can be opened with the DB to execute queries thereby improving concurrency but adding load to
+    the database. Very high number of concurrent connections can result in poor DB performance.
+
+
+.. note:: 
+
+  * Tuning these parameters have no impact on the resource utilization of Hasura. Hasura's CPU and memory utilization depends on the number of
+    requests being served.
+  * For most use cases, the default values offer reasonable trade-off between resource utilization and performance. For scenarios with heavy queries
+    and high number of active subscriptions, the setup needs to be benchmarked and these parameters need to be iterated upon to achieve optimal
+    performance.
+
+Further reading
+---------------
+
+You can read more details about the implementation of subscriptions in our `architecture and benchmarking doc <https://github.com/hasura/graphql-engine/blob/master/architecture/live-queries.md>`__.

docs/graphql/core/databases/postgres/subscriptions/index.rst

@@ -21,18 +21,14 @@ changes upstream.
 Subscriptions are supported for all kinds of queries. All the concepts of
 :ref:`queries <queries>` hold true for subscriptions as well.
 
-Execution
----------
+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**.
 
-By default updates are delivered to clients every **1 sec**. This interval can be configured via the
-``HASURA_GRAPHQL_LIVE_QUERIES_MULTIPLEXED_REFETCH_INTERVAL`` env var or the
-``--live-queries-multiplexed-refetch-interval`` flag. See the
-:ref:`server config reference <server_flag_reference>` for info on setting the flag/env var.
-
-You can read more about the implementation of subscriptions in the `architecture doc <https://github.com/hasura/graphql-engine/blob/master/architecture/live-queries.md>`__.
+See more details on :ref:`subscriptions execution and performance <subscriptions_execution_and_performance>`.
 
 Convert a query to a subscription
 ---------------------------------
@@ -114,3 +110,4 @@ It uses the provided CORS configuration (as per :ref:`configure-cors`).
   :hidden:
 
   Sample use cases <use-cases>
+  Execution and performance <execution-and-performance>