Realtime Data

The @live directive allows developers to read data in real-time, making it easy to build collaborative and multiplayer applications more efficiently than ever before.

Grafbase uses server-sent events to push data to the client via HTTP.

If any of the data for the query changes, the data pushed to the client is in the format of JSON Patch which contains instructions how to update the existing state.

The local Playground takes care of sending the request with the required HTTP header — accept: text/event-stream, and applying the JSON Patch.

You will need to configure your client to work with the EventSource API and applying the JSON Patch. We have several integrations to make this easier:

• URQL
• Apollo Client
• Vanilla EventSource

Here is the query from the reading data step:

{
  postCollection(first: 10) {
    edges {
      node {
        id
        title
        url
      }
    }
  }
}

We can make this live by adding @live to the query:

query @live {
  postCollection(first: 10) {
    edges {
      node {
        id
        title
        url
      }
    }
  }
}

Make sure the @live query above is still executing and listening for changes.

Now run the following mutation to create a Post in a new window:

mutation {
  postCreate(input: { title: "GraphQL", url: "https://graphql.org" }) {
    post {
      id
    }
  }
}

You should now see the @live has been updated to include the new result!

Now execute a mutation to update the Post by id and watch for changes.

Make sure to pass the GraphQL variables id and title.

mutation ($id: ID!, $title: String!) {
  postUpdate(by: { id: $id }, input: { title: $title }) {
    post {
      title
    }
  }
}

We'll now finish by deleting the Post by id which will automatically update the @live query results.

mutation DeletePostById($id: ID!) {
  postDelete(by: { id: $id }) {
    deletedId
  }
}

You should now see that the @live query that's listening for changes has been updated: