Tutorial #4 - Real-time Subscriptions with GraphQL

In this tutorial you will learn how to get real-time updates with subscriptions in Quick. Like queries, subscriptions enable you to fetch data. Unlike queries, they maintain an active connection to your GraphQL server, allowing you to subscribe to a topic and be notified whenever there is new data.

You can find the commands and the schemas used for this tutorial in our quick-examples repository

We will use the demo use-case from our introduction series, an online shop with products, users and purchases.
type Product {
    productId: Int!,
    name: String,
    description: String,
    price: Price,
    metadata: Metadata
}

type Price {
    total: Float,
    currency: String
}

type Metadata {
    created_at: Int,
    source: String
}

type User {
    userId: String!,
    name: String,
    address: String
}
type Purchase {
    purchaseId: String!,
    productId: Int!,
    userId: String!,
    amount: Int,
    price: Price,
}

type Price {
    total: Float,
    currency: String
}
Example data for Product, User and Purchase
{"key":101,"value":{"productId":101,"name":"Sweater","description":"Black cashmere sweater","price":{"total":55.74,"currency":"EURO"},"metadata":{"created_at":1107444371,"source":"https:\/\/scirocco.org"}}}
{"key":"vro1gi","value":{"userId":"vro1gi","name":"Shaneka Evans","address":"298 Marston Field"}}
{"key":"g46qiw","value":{"purchaseId":"g46qiw","productId":101,"userId":"vro1gi","amount":2,"price":{"total":111.48,"currency":"EURO"}}}
Create topics for products, users, purchases
> quick topic create product-topic -k long -v schema --schema product-schema.gql
Created new topic product-topic

> quick topic create user-topic -k string -v schema --schema user-schema.gql
Created new topic user-topic 

> quick topic create purchase-topic -k string -v schema --schema purchase-schema.gql
Created new topic purchase-topic
Example data ingestion to purchase-topic.
> curl --request POST \ 
--url https://$QUICK_URL/ingest/purchase-topic/ \
--header 'content-type: application/json' \
--header 'X-API-Key: $KEY' \
--data '{"key": "g46qiw", "value": {"purchaseId": "g46qiw", "productId": 101, "userId": "vro1gi", "amount": 2, "price": {"total": 111.48, "currency": "EURO"}}}'
Quick allows us to define subscriptions via Subscription, which delivers real-time updates of stream data through a websocket connection. In this example, we create a subscription purchaseStream to get live purchase updates. In Purchase, we add two fields product and user adding details from the corresponding topics. We apply this schema to our gateway, product-gateway.
type Query {
  allPurchases: [Purchase] @topic(name: "purchase-topic")
}

type Subscription {
  purchaseStream: Purchase @topic(name: "purchase-topic")
}

type Purchase {
  purchaseId: String!,
  productId: Int!,
  product: Product @topic(name: "product-topic", keyField: "productId")
  userId: String!,
  user: User @topic(name: "user-topic", keyField: "userId"),
  amount: Int,
  price: Price,
}

type Product {
  productId: Int!,
  name: String,
  description: String,
  price: Price,
  metadata: Metadata
}

type User {
  userId: String!,
  name: String,
  address: String
}

type Price {
  total: Float,
  currency: String
}

type Metadata {
  created_at: Int,
  source: String
}
> quick gateway apply product-gateway -f schema.gql
Applied definition for gateway product-gateway
We subscribe via purchaseStream and get the latest purchase updates, including product and user details.
subscription {
    purchaseStream {
    purchaseId
    product {
      productId
      name
      description
    }
    user {
      userId
      name
      address
    }
    amount
    price {
      total
      currency
    }
  }
}
{"purchaseStream":{"purchaseId":"g46qiw","product":{"productId":101,"name":"Sweater","description":"Black cashmere sweater"},"user":{"userId":"vro1gi","name":"Shaneka Evans","address":"298 Marston Field"},"amount":2,"price":{"total":111.48,"currency":"EURO"}}}
{"purchaseStream":{"purchaseId":"2etw5t","product":{"productId":202,"name":"Dress","description":"Short black dress"},"user":{"userId":"4nfr85","name":"Theressa Middleton","address":"744 Dr Carlton B Goodlett Loop"},"amount":1,"price":{"total":586.54,"currency":"DOLLAR"}}}