SDK
SDK Javascript v6.x
1

You are currently looking at the documentation of a previous version of Kuzzle. We strongly recommend that you use the latest version. You can also use the version selector in the top menu.

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.


Copied to clipboard!
subscribe(index, collection, filters, callback, [options]);

Arguments Type Description
index
string
Index name
collection
string
Collection name
filters
object
Set of filters following Koncorde syntax
callback
function
Callback function to handle notifications
options
object
Query options

callback #

Callback function that will be called each time a new notifications is received. The callback will receive the notifications object as only argument.

options #

Additional subscription options.

Property Type
(default)
Description
scope
string

(all)
Subscribe to document entering or leaving the scope
Possible values: all, in, out, none
users
string

(none)
Subscribe to users entering or leaving the room
Possible values: all, in, out, none
subscribeToSelf
boolean

(true)
Subscribe to notifications fired by our own queries
volatile
object

(null)
subscription information, used in user join/leave notifications

Resolves #

Resolves to a string containing the room ID

Usage #

Simple subscription to document notifications

Copied to clipboard!
function callback (notification) {
  console.log(notification);
  /*
  { status: 200,
    requestId: '1850b835-d82d-4bce-abec-bf593a578763',
    timestamp: 1539680191720,
    volatile: { sdkVersion: '6.0.0-beta-2' },
    index: 'nyc-open-data',
    collection: 'yellow-taxi',
    controller: 'document',
    action: 'create',
    protocol: 'websocket',
    scope: 'in',
    result:
      { _source:
        { name: 'nina vkote',
          age: 19,
          _kuzzle_info:
            { author: '-1',
              createdAt: 1539680191720,
              updatedAt: null,
              updater: null,
              active: true,
              deletedAt: null } },
        _id: 'AWZ8F0TpJD41ulNI_b-v' },
    type: 'document',
    room: '14b675feccf5ac320456ef0dbdf6c1fa-7a90af8c8bdaac1b' }
  */
  if (notification.scope === 'in') {
    console.log(`Document ${notification.result._source.name} enter the scope`);
  } else {
    console.log(`Document ${notification.result._source.name} leave the scope`);
  }
}
try {
  // Subscribe to notifications for documents containing a 'name' property
  const filters = { exists: 'name' };
  await kuzzle.realtime.subscribe('nyc-open-data', 'yellow-taxi', filters, callback);
  const document = { name: 'nina vkote', age: 19 };
  await kuzzle.document.create('nyc-open-data', 'yellow-taxi', document);
} catch (error) {
  console.log(error.message);
}

Subscription to document notifications with scope option

Copied to clipboard!
function callback (notification) {
  console.log(notification);
  /*
  { status: 200,
    requestId: 'e114c5d0-8ad1-4751-9236-772f9fea1b19',
    timestamp: 1539783948258,
    volatile: { sdkVersion: '6.0.0-beta-2' },
    index: 'nyc-open-data',
    collection: 'yellow-taxi',
    controller: 'document',
    action: 'update',
    protocol: 'websocket',
    scope: 'out',
    state: 'done',
    result: { _id: 'AWaCRnfbiSV6vMG7iV_K' },
    type: 'document',
    room: '638dd7b94b86720e6ac3f0617f26f116-ae85604010d1f5c7' }
  */
  console.log(`Document moved ${notification.scope} from the scope`);
}
try {
  // Subscribe to notifications when document leaves the scope
  const filters = { range: { age: { lte: 20 } } };
  const options = { scope: 'out' };
  await kuzzle.realtime.subscribe(
    'nyc-open-data',
    'yellow-taxi',
    filters,
    callback,
    options
  );
  const document = { name: 'nina vkote', age: 19 };
  // The document is in the scope
  const { _id } = await kuzzle.document.create(
    'nyc-open-data',
    'yellow-taxi',
    document
  );
  // The document isn't in the scope anymore
  await kuzzle.document.update('nyc-open-data', 'yellow-taxi', _id, { age: 42 });
} catch (error) {
  console.log(error.message);
}

Subscription to message notifications

Copied to clipboard!
function callback (notification) {
  console.log(notification);
  /*
  { status: 200,
    requestId: '212cc14d-3a4e-4f26-9fe8-6ba6c6279f9d',
    timestamp: 1539702246068,
    volatile: { sdkVersion: '6.0.0-beta-2' },
    index: 'i-dont-exist',
    collection: 'in-database',
    controller: 'realtime',
    action: 'publish',
    protocol: 'websocket',
    scope: 'in',
    state: 'done',
    result:
    { _source:
      { metAt: 'Insane',
        hello: 'world',
        _kuzzle_info:
          { author: '-1',
            createdAt: 1539680191720,
            updatedAt: null,
            updater: null,
            active: true,
            deletedAt: null } },
      _id: null },
    type: 'document',
    room: '24bbb5c44c343167eaf6a023dca8629e-7a90af8c8bdaac1b' }
  */
  console.log('Message notification received');
}
try {
  // Subscribe to a room
  await kuzzle.realtime.subscribe('i-dont-exist', 'in-database', {}, callback);
  // Publish a message to this room
  const message = { metAt: 'Insane', hello: 'world' };
  await kuzzle.realtime.publish('i-dont-exist', 'in-database', message);
} catch (error) {
  console.log(error.message);
}

Subscription to user notifications

Copied to clipboard!
function callback (notification) {
  if (notification.type === 'user') {
    console.log(notification.volatile);
    /*
      { sdkVersion: '<current SDK version>', username: 'nina vkote' },
    */
    console.log(`Currently ${notification.result.count} users in the room`);
  }
}
try {
  const filters = { exists: 'name' };
  // Subscribe users notifications
  const options = { users: 'all' };
  await kuzzle.realtime.subscribe(
    'nyc-open-data',
    'yellow-taxi',
    filters,
    callback,
    options
  );
  // Instantiates a second kuzzle client: multiple subscriptions
  // made by the same user will not trigger "new user" notifications
  const kuzzle2 = new Kuzzle(
    new WebSocket('kuzzle')
  );
  await kuzzle2.connect();
  // Subscribe to the same room with the second client
  const options2 = { users: 'all', volatile: { username: 'nina vkote' } };
  await kuzzle2.realtime.subscribe(
    'nyc-open-data',
    'yellow-taxi',
    filters,
    () => {},
    options2
  );
} catch (error) {
  console.log(error.message);
}