Quickstart Subscriptions

This quickstart will help you create your first subscription. We're going to subscribe to live updates for a message thread.

DOCS E-COMMERCE SAMPLE APP

This quickstart is dependent upon the docs e-commerce sample app. If you haven't already deployed the sample app, you can do so with one click below. If you've already deployed the sample app, simply use your existing project.

Step 1: Create a Subscription

Head to the API tab of the Hasura Console and paste in this value:

subscription MessageThreadSubscription($thread_id: uuid = "75e0f7b0-b5fc-11ed-ad85-1a122c2a1c44") {
  messages(where: { thread_id: { _eq: $thread_id } }) {
    created_at
    id
    body
    is_read
  }
}

Once hitting run, you should see the following output:

That's it?

Yep! Remember, you get subscriptions out of the box with Hasura 🔥 You won't see any messages in your results yet because there aren't any in the database, but the subscription is live and running. To test it, and mimic a client application, let's ping the server with curl in the next step.

Step 2: Insert a message

To avoid the need for a client application, we'll use curl to insert a message into the database. You can enter the curl command below into a terminal window, and replace the <YOUR_ADMIN_SECRET> and <YOUR_HASURA_PROJECT_ENDPOINT> values with your own:

curl -X POST -H "Content-Type: application/json" -H "X-Hasura-Admin-Secret: <YOUR_ADMIN_SECRET>" -d '{"query": "mutation { insert_messages(objects: {body: \"This is a live-updating subscription\", user_id: \"82001336-65b7-11ed-b905-7fa26a16d198\", thread_id: \"75e0f7b0-b5fc-11ed-ad85-1a122c2a1c44\" }) { affected_rows } } "}' <YOUR_HASURA_PROJECT_ENDPOINT>

After entering the above command hitting enter, you should see the following output on your Console's API tab:

Recap

What just happened? Well, you just wrote your first subscription! You can now subscribe to live updates for a message thread. Think of the possibilities in a real-world application: you can subscribe to live updates for a chat thread, a shopping cart, or a live leaderboard.

At the start, you created a subscription using the Hasura Console's API tab. This subscription returns the created_at, id, body, and is_read fields for all messages with a thread_id equal to the provided value. This allows us to receive new data, live from the server, rather than just a single response. So, as new messages are inserted into the database - like we did with the curl command - the subscription will return them.