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 scopePossible values: `all`, `in`, `out`, `none`
`users`	string (`none`)	Subscribe to users entering or leaving the roomPossible 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
`timeout`	number (`-1`)	Time (in ms) during which a request will still be waited to be resolved. Set it `-1` if you want to wait indefinitely
`triggerEvents`	boolean (`false`)	If set to `true`, will trigger events even if using Embeded SDK. You should always ensure that your events/pipes does not create an infinite loop. Available since Kuzzle 2.31.0

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: { sdkName: 'javascript@7.0.0' },
    index: 'nyc-open-data',
    collection: 'yellow-taxi',
    controller: 'document',
    action: 'create',
    event: 'write',
    protocol: 'websocket',
    scope: 'in',
    result:
      { _source:
        { name: 'nina vkote',
          age: 19,
          _kuzzle_info:
            { author: '-1',
              createdAt: 1539680191720,
              updatedAt: null,
              updater: 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: { sdkName: 'javascript@7.0.0' },
    index: 'nyc-open-data',
    collection: 'yellow-taxi',
    controller: 'document',
    action: 'update',
    event: 'write',
    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: { sdkName: 'javascript@7.0.0' },
    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 } },
      _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);
    /*
      { sdkName: '<current SDK name and 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);
}

Edit this page on Github