SDK
SDK Javascript v7.x

# 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: { sdkName: 'javascript@7.0.0' },
    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 } },
        _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: { sdkName: 'javascript@7.0.0' },
    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: { 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

Copied to clipboard!
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);
}