Subscriptions Execution and Performance
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.
Subscriptions that rely on SQL functions, such as through custom root fields or computed fields, may be at risk of multiplexing errors if they throw "dynamic" exceptions based on data in the underlying tables.
For example, if the SQL function throws an exception by reading rows and checking an aggregate then it may be prone to
such multiplexing errors. On the other hand, if it throws exception based on static values (e.g. input arguments to the
function), then it is safe from multiplexing errors. To avoid potential issues, it is important to carefully evaluate
the use of subscriptions with such functions. You can set the env variable
HASURA_GRAPHQL_LIVE_QUERIES_MULTIPLEXED_BATCH_SIZE: 1 to avoid multiplexing errors.
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:
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.
- 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.
You can also analyze the metrics about the multiplexed subscription emitted in
livequery-poller-log. See details of this log in this page.
