subscribe #

Subscribes by providing a set of filters: messages, document changes and, optionally, user events matching the provided filters will generate real-time notifications, sent to you in real-time by Kuzzle.

Query Syntax #

HTTP #

Due to the synchronous nature of the HTTP protocol, real-time notifications are not supported.

Other protocols #

{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "subscribe",
  "body": {
    // subscription filters
  },
  "volatile": {
    // query volatile data
  },
  "scope": "<all|in|out|none>",
  "state": "<all|pending|done>",
  "users": "<all|in|out|none>"
}

Arguments #

• collection: watched collection
• index: watched index

Optional: #

• scope: accepted values: all, in, out, none (default: all). Subscribe to either new documents entering the scope of the subscription filters (in), to documents leaving it (out), or both (all). Alternatively, document notifications can be ignored entirely (none)
• state
  Deprecated since 1.5.0
  : accepted values: all, pending, done (default: done). Subscribe to either changes that are about to occur (pending), to changes having occured (done), or both (all). In the latter case, each document change will generate 2 real-time notifications
• users: accepted values: all, in, out, none (default: none). Receive real-time notifications about users subscribing to the same filters (in), about users leaving the subscription (out), or both (all). If set to none, no notifications are sent about users
• volatile: subscription information, used in user join/leave notifications

Body properties #

Subscription filters, following the Koncorde syntax

An empty filter subscribes to any change occuring on the selected index-collection pair.

Response #

Returns an object detailing the new subscription properties:

• channel: unique channel identifier. A channel acts as a subscription configuration ID, allowing multiple subscriptions to occur with the same filters, but different notification options.
• roomId: unique subscription identifier.

Notifications include the room property, which indicates to what channel the notification is for. This is how notifications can be linked to subscriptions by front-end applications (our SDK perform these operations automatically).

Example #

{
  "status": 200,
  "error": null,
  "index": "<index>",
  "collection": "<collection>",
  "controller": "realtime",
  "action": "subscribe",
  "requestId": "<unique request identifier>",
  "result": {
    "roomId": "<unique Kuzzle room identifier>",
    "channel": "<unique channel identifier>"
  }
}