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.


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

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

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

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

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);
}