Live Query

Prerequisiteslink

Enable eventinglink

Make sure you have enabled eventing for your Space Cloud cluster. To enable eventing, head over to the Settings tab in the Eventing section:

Check the Enable eventing module checkbox.

Select an Eventing DB and hit Save.

Eventing DB is used to store event and invocation logs.

Other prerequisiteslink

• Enable logical replication for Postgres, if you want to capture events from Postgres.
• Enable replica mode in MongoDB, if you want to capture events from MongoDB.

Make sure you have read the limitations.

Prerequisiteslink

To use the realtime functionality (liveQuery) on any table/collection, you need to make sure that the following things are true:

• The schema of the table/collection has some fields that uniquely identify each row (i.e. the table should have primary or unique fields). These fields should also be present in the where clause during update and delete mutations.
• The particular table/collection has the realtime feature enabled. You can find and change this setting for each table/collection in the Overview tab of the Database section.

Live querylink

When you make a live query request to Space Cloud, it first pushes down the initial data in the result set one by one. After that, it just notifies you of any changes that happen to your result set.

Example: Live query to the list of pokemons caught by a trainer:

# Note: Only one single top level field is allowed in subscriptions

subscription {
  caught_pokemons(
    where: {trainer_id: "1"}
  ) @mongo {
    type
    payload {
      name
    }
    find # Object containing the unique fields of the concerned document 
  }
}

const whereClause = cond("trainer_id", "==", "1")

// Callback for data changes:
const onSnapshot  = (docs, type, find, doc) => {
   // docs is the entire result set maintained by the client SDK
   // doc is the concerned doc whereas find is the object containing the unique fields
   console.log(docs, type, find, doc)
}

// Callback for error while subscribing
const onError = (err) => {
   console.log('Live query error', err)
}

let subscription = db.liveQuery("caught_pokemons")
  .where(whereClause).subscribe(onSnapshot, onError)

// Unsubscribe to changes
if (on some logic) {
  subscription.unsubscribe()
}

Data pushed down in live query have the following fields:

• type: The type of operation which has resulted in Space Cloud pushing down data. Possible values are - initial, insert, update, and delete. initial is only applicable when Space Cloud is pushing the initial data down.
• payload: The concerned document/object.
• find: An object containing the unique fields of the document.
• time: The timestamp of the operation in milliseconds.

Subscribing to changes onlylink

In case you are interested in only the changes and not the initial values, use can use skipInitial:

subscription {
  caught_pokemons @mongo (
    where: {trainer_id: $trainerId},
    skipInitial: true
  ){
    type
    payload {
      name
    }
    find
  }
}

const whereClause = cond("trainer_id", "==", "1")

// Callback for data changes:
const onSnapshot  = (docs, type, find, doc) => {
   // docs is the entire result set maintained by the client SDK
   // doc is the concerned doc whereas find is the object containing the unique fields
   console.log(docs, type, find, doc)
}

// Callback for error while subscribing
const onError = (err) => {
   console.log('Live query error', err)
}

let subscription = db.liveQuery("caught_pokemons")
  .options({ skipInitial: true })
  .where(whereClause).subscribe(onSnapshot, onError)

// Unsubscribe to changes
if (on some logic) {
  subscription.unsubscribe()
}

Limitationslink

Following are the limitations of the subscriptions in Space Cloud:

• Truncating a table doesn’t spawn the corresponding DELETE events.
• Subscriptions doesn’t work for SQL Server yet.

Have a technical question?

Improve the docs!