why deepstreamHub? compare us getting started faq
use cases
products

deepstream open source

the server that started it all and now drives thousands of realtime apps worldwide

deepstreamHub enterprise

the full scale and featureset of deepstreamHub on premise
compare products
developers
api docs

Documentation for client, open source server & server SDKs

 tutorials

Learning deepstream by example

 guides

In-depth explanations of features and concepts

 integrations

Usage with other APIs, Protocols & Frameworks

 open source server

Deepstream server docs and tutorials

 benchmarking

Performance tests overview & results
company
team

meet the people behind deepstreamHub

 jobs

open positions and hiring process

 media

brand assets and media relations

 legal

imprint, terms of use, privacy and data-protection
blog contact

Record

docs → client-js → Record

Records are the documents in deepstreamHub’s realtime datastore. A record is identified by a unique id and can contain any kind of JSON data. Clients and backend processes can create, read, write, update and observe the entire record as well as paths within it. Any change is immediately synchronized amongst all connected subscribers.

Records can be arranged in lists and collections and can contain references to other records to allow for the modelling of relational data structures.

You can learn more about records in the records tutorial.

Creating records

Records are created and retrieved using client.record.getRecord( 'name' );

const recordName = 'user/' + client.getUid() // "user/iqaphzxy-2o1pnsvcnbo"
const record = client.record.getRecord(recordName)

Methods

whenReady(callback)

argument type optional description
callback Function false A function that should be invoked as soon as the record is ready.

Immediately executes the callback if the record is ready. Otherwise, it registers it as a callback for the ready event.

record.whenReady(record => {
  // data has now been loaded
})

set(path, value)

argument type optional description
path String true A particular path within the JSON structure that should be set.
value Various false The value the record or path should be set to.

Used to set the data of the entire record or of a path within it to a given value.

// Set the entire record's data
record.set({
  personalData: {
    firstname: 'Homer',
    lastname: 'Simpson',
    status: 'married'
  },
  children: ['Bart', 'Maggie', 'Lisa']
});

// Update only firstname
record.set('personalData.firstname', 'Marge')

get(path)

argument type optional description
path String true A particular path within the JSON structure that should be retrieved.

Will return the entire record's data or - if called with a path the value for that path. Will return undefined if the path can't be found.

record.get() // Returns entire object
record.get('children[1]') // 'Maggie'
record.get('personalData.firstname') // 'Homer'

subscribe(path, callback, triggerNow)

argument type optional description
path String true A path within the JSON structure that should be subscribed to.
callback Function false A function that is called whenever the value changes and the data passed through.
triggerNow Boolean true If true, the callback function will be called immediately with the current value.

Registers a callback that will be invoked whenever the record's value changes. Subscribes to any change to the record when called without a path argument or to the changes of a path within the record.

Optional: Passing true will execute the callback immediately with the record's current value.

Listening to any changes on the record:

// Subscribe to any change of the record
function userDataChanged(data) {
  // do stuff...
}
record.subscribe(userDataChanged)

Listening to changes on a specific path within the record:

// Only subscribe to the status of the user
function statusChanged( status ) {
  if (status !== 'married') {
    // I want my childhood back!
  }
}
record.subscribe('status', statusChanged, true)

unsubscribe(path, callback)

argument type optional description
path String true The path that was previously used for subscribe.
callback Function false The previously registered callback function.

Removes a subscription previously made using record.subscribe(). Passing a path to unsubscribe removes the callback only for that specific path.

Info

  • unsubscribe is purely a client-side operation. To notify deepstreamHub that the app is no longer interested in the record, use discard() instead.

Unsubscribe all callbacks registered with the path status

record.unsubscribe('status')

Unsubscribe a specific callback registered for the path status

record.unsubscribe('status', statusChanged)

Unsubscribe a specific callback registered for the record

record.unsubscribe(userDataChanged)

Unsubscribe all callbacks not associated with a path

record.unsubscribe()


discard()

Removes all change listeners and notifies the platform that the client is no longer interested in updates for this record.

record.discard()


Info

  • Especially for mobile apps it's crucial to minimize the amount of data that's sent to the app. Make sure to discard all unneeded records so the platform won't sent updates anymore. Please note: the deepstream client keeps track of how many times a record was requested. Every time a component within your app calls .getRecord(), that count goes up. Every time .discard() is called the count goes down. Only when it reaches 0 will the client assume that no aspect of your app needs the record anymore and notify the platform.

delete()

This permanently deletes the record for all users.

record.delete()


Info


  • Since deleting a record means that it no longer exists, the resulting action will be a forced discard to all clients with that record.
    Creating a record directly after deleting it without waiting for the delete event can end up in a race condition. Try to ensure the record has been deleted succesfully to avoid edge cases.

Properties

argument type description
name String The name of the record, as specified when calling client.record.getRecord( name )
usages Number The number of active records throughout the application, meaning they have not yet been discarded via discard()
isReady Boolean True once the record has received its current data and emitted the 'ready' event
isDestroyed Boolean True once the record has been discarded or deleted. The record would need to be retrieved again via client.record.getRecord( name )

Events

ready

Emitted once the record has received its current data from the platform.

delete

Emitted when the record was deleted, whether by this client or by another.

discard

Emitted once the record was discarded.

error

Emitted if the record encounters an error. The error message is passed to the event callback.

Merge strategies

Merge strategies in deepstream handle conflicts in data in a way that is described in this guide.