why deepstreamHub? compare us getting started feature roadmap faq
use cases pricing
enterprise blog contact

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)



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
  personalData: {
    firstname: 'Homer',
    lastname: 'Simpson',
    status: 'married'
  children: ['Bart', 'Maggie', 'Lisa']

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


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...

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!
user.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.


  • 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


Unsubscribe a specific callback registered for the path status

user.unsubscribe('status', statusChanged)

Unsubscribe a specific callback registered for the record


Unsubscribe all callbacks not associated with a path



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

<div class="docbox infobox"><h3>Info</h3><ul><li>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.



  • 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.


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 )



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


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


Emitted once the record was discarded.


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