For AI agents: this page in Markdown: https://www.pubnub.com/docs/sdks/javascript/api-reference/datasync.md. Documentation index: https://www.pubnub.com/llms-full.txt.

DataSync API for JavaScript SDK

The DataSync API of the PubNub JavaScript SDK stores application state as users, channels, memberships, entities, and relationships, and keeps connected clients current through real-time events. Use it to model the objects your application works with and to react the moment they change.

DataSync is the successor to App Context.

DataSync entities and SDK entities are different things

This page is about DataSync entities, the records the service stores and treats as the source of truth for your application state. They are created and read through the pubnub.dataSync.* methods documented here.

An SDK entity is a local client-side handle such as pubnub.channel('room-1'). It carries no stored state of its own and gives you a scoped handle for subscribing and calling APIs. See SDK entities in Publish and subscribe.

The two meet in the DataSync SDK entities: SDK entities whose only job is to subscribe to a DataSync object's real-time updates.

The classes that your objects conform to (their types and schemas) are defined through the Admin API or the Admin Portal, not through this SDK:

  • Entity classes, which back users, channels, and custom entities: list, read, create, replace, and delete. Partial updates aren't implemented. Replace the complete class version instead.
  • Relationship classes, which back memberships and custom relationships: list, read, create, replace, and delete.

A class definition decides three things for every object of that class. The definition decides which payload fields are filterable and sortable, which projection each field belongs to, and how long the object lives before it expires. See managing classes for details.

Every response includes the HTTP status. The remove* methods return the status on its own. Every other method adds a data key holding the object, or the array of objects for a list method. A response can also add a links object with the hypermedia URLs (HATEOAS) the service provides (self, and next where it applies). Every stored object carries its expiresAt auto-deletion timestamp (ISO 8601). A stored object also carries its free-form status when you set one.

The operations fall into six areas, and each operation has its own section:

#

#

#

#

#

#

Supported and recommended asynchronous patterns

PubNub supports Callbacks, Promises, and Async/Await for asynchronous JS operations. The recommended pattern is Async/Await and all sample requests in this document are based on it. This pattern returns a status only on detecting an error. To receive the error status, you must add the try...catch syntax to your code.

Create user​

pubnub.dataSync.createUser() creates a DataSync user through a PubNub client for JavaScript. The server generates the identifier unless the call supplies one.

Users have no top-level name or email fields. All application data lives in the free-form payload. See users for the concept.

A user is an entity of the built-in User entity class, which the service provides at the Global class level. To give your users their own declared properties, define a subclass of User with Create a new entity class and pass its name as class.

required
id#
Type: string
Default: no default
Identifier of the new DataSync user. Omit it to let the server generate one. The identifier has at most 255 characters.
class#
Type: string
Default: User
Name of the entity class that this user belongs to. The class is set at creation and immutable afterward. Must be User or one of its subclasses.
classLevel#
Type: string
Default: no default
Class hierarchy level of class, either Global for a class the service provides or SubKey for one defined on your key set. The level is set at creation and immutable afterward. Omit it to let the service apply its default.
data required#
Type: object
Default: no default
The mutable user data.
property of data: classVersion required#
Type: number
Default: no default
Version of the user class schema.
property of data: status#
Type: string
Default: no default
Free-form lifecycle status. The maximum length is 100 characters.
property of data: payload#
Type: object
Default: no default
Free-form JSON object holding your application data.

Returns​

pubnub.dataSync.createUser() resolves with the HTTP status and the created user.

Syntax

1pubnub.dataSync.createUser({
2    id: string,
3    class: string,
4    classLevel: string,
5    data: { classVersion: number, status: string, payload: object },
6}): Promise<DataSync.CreateUserResponse>

Get user​

pubnub.dataSync.getUser() returns one DataSync user by identifier through a PubNub client for JavaScript.

required
id required#
Type: string
Default: no default
Identifier of the user.

Returns​

pubnub.dataSync.getUser() resolves with the HTTP status and the requested user.

Syntax

1pubnub.dataSync.getUser({
2    id: string,
3}): Promise<DataSync.GetUserResponse>

Get all users​

pubnub.dataSync.getUsers() returns a paginated list of DataSync users through a PubNub client for JavaScript.

All parameters are optional, so you can call getUsers() with no arguments.You can also pass a callback as the only argument.For pagination, filtering, and sorting, see sorting and pagination.
class#
Type: string
Default: no default
Name of the entity class to list. Omit it to list users of every user class.
classVersion#
Type: number
Default: no default
Class version to list. Omit it to list users of every version of the class.
classLevel#
Type: string
Default: no default
Class hierarchy level of class, either Global for a class the service provides or SubKey for one defined on your key set. Use it to disambiguate a class name defined at both levels.
cursor#
Type: string
Default: no default
Opaque pagination cursor from the previous page. Omit it to get the first page.
limit#
Type: number
Default: no default
Maximum number of users to return in one page, up to 100.
filter#
Type: string
Default: no default
Filter expression evaluated against eventually consistent storage, so results can briefly lag writes. The parameter supports the full expression language over properties declared with filtering mode full. A call cannot combine it with filterFast.
filterFast#
Type: string
Default: no default
Filter expression evaluated against strongly consistent storage, so it reflects the latest writes. The parameter accepts up to 10 conditions by default (configurable per keyset) over properties declared with filtering mode simple or full. A call cannot combine it with filter.
sort#
Type: object | string
Default: no default
Sort order of the returned users. An object that maps each field to 'asc', 'desc', or null (service default), or a comma-separated string such as 'createdAt:desc'.

Returns​

pubnub.dataSync.getUsers() resolves with the HTTP status, an array of users, and paging metadata.

Syntax

1pubnub.dataSync.getUsers({
2    class: string,
3    classVersion: number,
4    classLevel: string,
5    cursor: string,
6    limit: number,
7    filter: string,
8    filterFast: string,
9    sort: object | string,
10}): Promise<DataSync.GetUsersResponse>

Set user​

pubnub.dataSync.setUser() replaces a DataSync user in full through a PubNub client for JavaScript. The call clears a stored status or payload that it omits.

To guard against concurrent writes, pass ifMatchesEtag. See optimistic concurrency with ETags.
required
id required#
Type: string
Default: no default
Identifier of the user.
data required#
Type: object
Default: no default
The replacement user data.
property of data: classVersion required#
Type: number
Default: no default
Version of the user class schema.
property of data: status#
Type: string
Default: no default
Free-form lifecycle status. The maximum length is 100 characters.
property of data: payload#
Type: object
Default: no default
Free-form JSON object holding your application data.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The update succeeds only if it still matches, otherwise the server returns 412.

Returns​

pubnub.dataSync.setUser() resolves with the HTTP status and the stored user.

Syntax

1pubnub.dataSync.setUser({
2    id: string,
3    data: { classVersion: number, status: string, payload: object },
4    ifMatchesEtag: string,
5}): Promise<DataSync.SetUserResponse>

Update user​

pubnub.dataSync.updateUser() applies a JSON Patch (RFC 6902) partial update to a DataSync user through a PubNub client for JavaScript. The call needs at least one patch operation, and fields that no operation addresses stay unchanged.

required
id required#
Type: string
Default: no default
Identifier of the user.
add#
Type: object
Default: no default
Full JSON Pointers mapped to values to add.
replace#
Type: object
Default: no default
Full JSON Pointers mapped to replacement values.
remove#
Type: array
Default: no default
Full JSON Pointers to remove.
move#
Type: array
Default: no default
Pairs of JSON Pointers, each with a from and a path. The value at from is removed and re-added at path.
copy#
Type: array
Default: no default
Pairs of JSON Pointers, each with a from and a path. The value at from is duplicated to path.
test#
Type: object
Default: no default
Full JSON Pointers mapped to expected values. The patch fails if any value does not match.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The patch succeeds only if it still matches, otherwise the server returns 412.

Paths can target fields inside payload or top-level stored fields. A JSON Pointer that starts with /payload/ targets a payload field, and a root pointer such as /status targets a top-level field. See partial update for the JSON Pointer rules.

At least one of add, replace, remove, move, copy, or test must be provided.

A single updateUser() call can mix add, replace, remove, move, copy, and test. The order you write the keys in does not matter. The SDK always sends the operations in the same order, with test last.

Returns​

pubnub.dataSync.updateUser() resolves with the HTTP status and the updated user.

Syntax

1pubnub.dataSync.updateUser({
2    id: string,
3    add: object,
4    replace: object,
5    remove: string[],
6    move: { from: string, path: string }[],
7    copy: { from: string, path: string }[],
8    test: object,
9    ifMatchesEtag: string,
10}): Promise<DataSync.UpdateUserResponse>

Remove user​

pubnub.dataSync.removeUser() deletes a DataSync user by identifier through a PubNub client for JavaScript.

required
id required#
Type: string
Default: no default
Identifier of the user.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The delete succeeds only if it still matches, otherwise the server returns 412.

Returns​

pubnub.dataSync.removeUser() resolves with only the HTTP status.

Syntax

1pubnub.dataSync.removeUser({
2    id: string,
3    ifMatchesEtag: string,
4}): Promise<DataSync.RemoveUserResponse>

Create channel​

pubnub.dataSync.createChannel() creates a DataSync channel through a PubNub client for JavaScript. The server generates the identifier unless the call supplies one.

Channels work like users. They have no top-level name field, all application data lives in payload, and they support the same operations. See channels for the concept.

A channel is an entity of the built-in Channel entity class, which the service provides at the Global class level. To give your channels their own declared properties, define a subclass of Channel with Create a new entity class and pass its name as class.

required
id#
Type: string
Default: no default
Identifier of the new DataSync channel. Omit it to let the server generate one. The identifier has at most 255 characters.
class#
Type: string
Default: Channel
Name of the entity class that this channel belongs to. The class is set at creation and immutable afterward. Must be Channel or one of its subclasses.
classLevel#
Type: string
Default: no default
Class hierarchy level of class, either Global for a class the service provides or SubKey for one defined on your key set. The level is set at creation and immutable afterward. Omit it to let the service apply its default.
data required#
Type: object
Default: no default
The mutable channel data.
property of data: classVersion required#
Type: number
Default: no default
Version of the channel class schema.
property of data: status#
Type: string
Default: no default
Free-form lifecycle status. The maximum length is 100 characters.
property of data: payload#
Type: object
Default: no default
Free-form JSON object holding your application data.

Returns​

pubnub.dataSync.createChannel() resolves with the HTTP status and the created channel.

Syntax

1pubnub.dataSync.createChannel({
2    id: string,
3    class: string,
4    classLevel: string,
5    data: { classVersion: number, status: string, payload: object },
6}): Promise<DataSync.CreateChannelResponse>

Get channel​

pubnub.dataSync.getChannel() returns one DataSync channel by identifier through a PubNub client for JavaScript.

required
id required#
Type: string
Default: no default
Identifier of the channel.

Returns​

pubnub.dataSync.getChannel() resolves with the HTTP status and the requested channel.

Syntax

1pubnub.dataSync.getChannel({
2    id: string,
3}): Promise<DataSync.GetChannelResponse>

Get all channels​

pubnub.dataSync.getChannels() returns a paginated list of DataSync channels through a PubNub client for JavaScript.

All parameters are optional, so you can call getChannels() with no arguments.You can also pass a callback as the only argument.For pagination, filtering, and sorting, see sorting and pagination.
class#
Type: string
Default: no default
Name of the entity class to list. Omit it to list channels of every channel class.
classVersion#
Type: number
Default: no default
Class version to list. Omit it to list channels of every version of the class.
classLevel#
Type: string
Default: no default
Class hierarchy level of class, either Global for a class the service provides or SubKey for one defined on your key set. Use it to disambiguate a class name defined at both levels.
cursor#
Type: string
Default: no default
Opaque pagination cursor from the previous page. Omit it to get the first page.
limit#
Type: number
Default: no default
Maximum number of channels to return in one page, up to 100.
filter#
Type: string
Default: no default
Filter expression evaluated against eventually consistent storage, so results can briefly lag writes. The parameter supports the full expression language over properties declared with filtering mode full. A call cannot combine it with filterFast.
filterFast#
Type: string
Default: no default
Filter expression evaluated against strongly consistent storage, so it reflects the latest writes. The parameter accepts up to 10 conditions by default (configurable per keyset) over properties declared with filtering mode simple or full. A call cannot combine it with filter.
sort#
Type: object | string
Default: no default
Sort order of the returned channels. An object that maps each field to 'asc', 'desc', or null (service default), or a comma-separated string such as 'createdAt:desc'.

Returns​

pubnub.dataSync.getChannels() resolves with the HTTP status, an array of channels, and paging metadata.

Syntax

1pubnub.dataSync.getChannels({
2    class: string,
3    classVersion: number,
4    classLevel: string,
5    cursor: string,
6    limit: number,
7    filter: string,
8    filterFast: string,
9    sort: object | string,
10}): Promise<DataSync.GetChannelsResponse>

Set channel​

pubnub.dataSync.setChannel() replaces a DataSync channel in full through a PubNub client for JavaScript. The call clears a stored status or payload that it omits.

To guard against concurrent writes, pass ifMatchesEtag. See optimistic concurrency with ETags.
required
id required#
Type: string
Default: no default
Identifier of the channel.
data required#
Type: object
Default: no default
The replacement channel data.
property of data: classVersion required#
Type: number
Default: no default
Version of the channel class schema.
property of data: status#
Type: string
Default: no default
Free-form lifecycle status. The maximum length is 100 characters.
property of data: payload#
Type: object
Default: no default
Free-form JSON object holding your application data.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The update succeeds only if it still matches, otherwise the server returns 412.

Returns​

pubnub.dataSync.setChannel() resolves with the HTTP status and the stored channel.

Syntax

1pubnub.dataSync.setChannel({
2    id: string,
3    data: { classVersion: number, status: string, payload: object },
4    ifMatchesEtag: string,
5}): Promise<DataSync.SetChannelResponse>

Update channel​

pubnub.dataSync.updateChannel() applies a JSON Patch (RFC 6902) partial update to a DataSync channel through a PubNub client for JavaScript. The call needs at least one patch operation, and fields that no operation addresses stay unchanged.

required
id required#
Type: string
Default: no default
Identifier of the channel.
add#
Type: object
Default: no default
Full JSON Pointers mapped to values to add.
replace#
Type: object
Default: no default
Full JSON Pointers mapped to replacement values.
remove#
Type: array
Default: no default
Full JSON Pointers to remove.
move#
Type: array
Default: no default
Pairs of JSON Pointers, each with a from and a path. The value at from is removed and re-added at path.
copy#
Type: array
Default: no default
Pairs of JSON Pointers, each with a from and a path. The value at from is duplicated to path.
test#
Type: object
Default: no default
Full JSON Pointers mapped to expected values. The patch fails if any value does not match.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The patch succeeds only if it still matches, otherwise the server returns 412.

Paths can target fields inside payload or top-level stored fields. A JSON Pointer that starts with /payload/ targets a payload field, and a root pointer such as /status targets a top-level field. See partial update for the JSON Pointer rules.

At least one of add, replace, remove, move, copy, or test must be provided.

A single updateChannel() call can mix add, replace, remove, move, copy, and test. The order you write the keys in does not matter. The SDK always sends the operations in the same order, with test last.

Returns​

pubnub.dataSync.updateChannel() resolves with the HTTP status and the updated channel.

Syntax

1pubnub.dataSync.updateChannel({
2    id: string,
3    add: object,
4    replace: object,
5    remove: string[],
6    move: { from: string, path: string }[],
7    copy: { from: string, path: string }[],
8    test: object,
9    ifMatchesEtag: string,
10}): Promise<DataSync.UpdateChannelResponse>

Remove channel​

pubnub.dataSync.removeChannel() deletes a DataSync channel by identifier through a PubNub client for JavaScript.

required
id required#
Type: string
Default: no default
Identifier of the channel.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The delete succeeds only if it still matches, otherwise the server returns 412.

Returns​

pubnub.dataSync.removeChannel() resolves with only the HTTP status.

Syntax

1pubnub.dataSync.removeChannel({
2    id: string,
3    ifMatchesEtag: string,
4}): Promise<DataSync.RemoveChannelResponse>

Create membership​

pubnub.dataSync.createMembership() creates a DataSync membership through a PubNub client for JavaScript. The server generates the identifier unless the call supplies one.

A membership links a user to a channel and carries its own payload. In the running example, Alice is a member of channel-summer-sale with the payload { "role": "viewer" }. See memberships for the concept.

A membership is a relationship of the built-in Global Membership relationship class, whose two sides are surfaced as channelId and userId. Every membership response includes both relationshipClass and relationshipClassVersion. The class is assigned by the service, so the createMembership and setMembership methods take no class parameter.

Relationship classes don't support inheritance, and only the Global Membership class produces memberships, so relationshipClass is always Membership and relationshipClassVersion is the only part that varies.

The userId and channelId pair must be unique for the membership class. A membership that duplicates an existing pair is rejected with a 409.

required
id#
Type: string
Default: no default
Identifier of the new DataSync membership. Omit it to let the server generate one. The identifier has at most 255 characters.
userId required#
Type: string
Default: no default
Identifier of the user in the membership.
channelId required#
Type: string
Default: no default
Identifier of the channel in the membership.
data required#
Type: object
Default: no default
The mutable membership data.
property of data: classVersion required#
Type: number
Default: no default
Version of the membership class schema.
property of data: status#
Type: string
Default: no default
Free-form lifecycle status. The maximum length is 100 characters.
property of data: payload#
Type: object
Default: no default
Free-form JSON object holding your application data.

Returns​

pubnub.dataSync.createMembership() resolves with the HTTP status and the created membership.

Syntax

1pubnub.dataSync.createMembership({
2    id: string,
3    userId: string,
4    channelId: string,
5    data: { classVersion: number, status: string, payload: object },
6}): Promise<DataSync.CreateMembershipResponse>

Get membership​

pubnub.dataSync.getMembership() returns one DataSync membership by identifier through a PubNub client for JavaScript.

required
id required#
Type: string
Default: no default
Identifier of the membership.

Returns​

pubnub.dataSync.getMembership() resolves with the HTTP status and the requested membership.

Syntax

1pubnub.dataSync.getMembership({
2    id: string,
3}): Promise<DataSync.GetMembershipResponse>

Get all memberships​

pubnub.dataSync.getMemberships() returns a paginated list of DataSync memberships through a PubNub client for JavaScript.

All parameters are optional, so you can call getMemberships() with no arguments. You can also pass a callback as the only argument. Filter by userId to list a user's memberships or by channelId to list a channel's members. For pagination, filtering, and sorting, see sorting and pagination.

cursor#
Type: string
Default: no default
Opaque pagination cursor from the previous page. Omit it to get the first page.
limit#
Type: number
Default: no default
Maximum number of memberships to return in one page, up to 100.
filter#
Type: string
Default: no default
Filter expression evaluated against eventually consistent storage, so results can briefly lag writes. The parameter supports the full expression language over properties declared with filtering mode full. A call cannot combine it with filterFast.
filterFast#
Type: string
Default: no default
Filter expression evaluated against strongly consistent storage, so it reflects the latest writes. The parameter accepts up to 10 conditions by default (configurable per keyset) over properties declared with filtering mode simple or full. A call cannot combine it with filter.
sort#
Type: object | string
Default: no default
Sort order of the returned memberships. An object that maps each field to 'asc', 'desc', or null (service default), or a comma-separated string such as 'createdAt:desc'.
userId#
Type: string
Default: no default
List only memberships of this user.
channelId#
Type: string
Default: no default
List only memberships of this channel.
classVersion#
Type: number
Default: no default
Class version to list. Omit it to list memberships of every version of the class.

Returns​

pubnub.dataSync.getMemberships() resolves with the HTTP status, an array of memberships, and paging metadata.

Syntax

1pubnub.dataSync.getMemberships({
2    cursor: string,
3    limit: number,
4    filter: string,
5    filterFast: string,
6    sort: object | string,
7    userId: string,
8    channelId: string,
9    classVersion: number,
10}): Promise<DataSync.GetMembershipsResponse>

Set membership​

pubnub.dataSync.setMembership() replaces a DataSync membership in full through a PubNub client for JavaScript. The call clears a stored status or payload that it omits.

Resend userId, channelId, and classVersion along with the fields you want to keep. For a partial update, use Update membership. To guard against concurrent writes, pass ifMatchesEtag. See optimistic concurrency with ETags.

required
id required#
Type: string
Default: no default
Identifier of the membership.
userId required#
Type: string
Default: no default
Identifier of the user in the membership.
channelId required#
Type: string
Default: no default
Identifier of the channel in the membership.
data required#
Type: object
Default: no default
The replacement membership data.
property of data: classVersion required#
Type: number
Default: no default
Version of the membership class schema.
property of data: status#
Type: string
Default: no default
Free-form lifecycle status. The maximum length is 100 characters.
property of data: payload#
Type: object
Default: no default
Free-form JSON object holding your application data.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The update succeeds only if it still matches, otherwise the server returns 412.

Returns​

pubnub.dataSync.setMembership() resolves with the HTTP status and the stored membership.

Syntax

1pubnub.dataSync.setMembership({
2    id: string,
3    userId: string,
4    channelId: string,
5    data: { classVersion: number, status: string, payload: object },
6    ifMatchesEtag: string,
7}): Promise<DataSync.SetMembershipResponse>

Update membership​

pubnub.dataSync.updateMembership() applies a JSON Patch (RFC 6902) partial update to a DataSync membership through a PubNub client for JavaScript. The call needs at least one patch operation, and fields that no operation addresses stay unchanged.

required
id required#
Type: string
Default: no default
Identifier of the membership.
add#
Type: object
Default: no default
Full JSON Pointers mapped to values to add.
replace#
Type: object
Default: no default
Full JSON Pointers mapped to replacement values.
remove#
Type: array
Default: no default
Full JSON Pointers to remove.
move#
Type: array
Default: no default
Pairs of JSON Pointers, each with a from and a path. The value at from is removed and re-added at path.
copy#
Type: array
Default: no default
Pairs of JSON Pointers, each with a from and a path. The value at from is duplicated to path.
test#
Type: object
Default: no default
Full JSON Pointers mapped to expected values. The patch fails if any value does not match.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The patch succeeds only if it still matches, otherwise the server returns 412.

Paths can target fields inside payload or top-level stored fields. A JSON Pointer that starts with /payload/ targets a payload field, and a root pointer such as /status targets a top-level field. See partial update for the JSON Pointer rules.

At least one of add, replace, remove, move, copy, or test must be provided.

A single updateMembership() call can mix add, replace, remove, move, copy, and test. The order you write the keys in does not matter. The SDK always sends the operations in the same order, with test last.

Returns​

pubnub.dataSync.updateMembership() resolves with the HTTP status and the updated membership.

Syntax

1pubnub.dataSync.updateMembership({
2    id: string,
3    add: object,
4    replace: object,
5    remove: string[],
6    move: { from: string, path: string }[],
7    copy: { from: string, path: string }[],
8    test: object,
9    ifMatchesEtag: string,
10}): Promise<DataSync.UpdateMembershipResponse>

Remove membership​

pubnub.dataSync.removeMembership() deletes a DataSync membership by identifier through a PubNub client for JavaScript.

required
id required#
Type: string
Default: no default
Identifier of the membership.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The delete succeeds only if it still matches, otherwise the server returns 412.

Returns​

pubnub.dataSync.removeMembership() resolves with only the HTTP status.

Syntax

1pubnub.dataSync.removeMembership({
2    id: string,
3    ifMatchesEtag: string,
4}): Promise<DataSync.RemoveMembershipResponse>

Create entity​

pubnub.dataSync.createEntity() creates a DataSync entity through a PubNub client for JavaScript. The server generates the identifier unless the call supplies one.

Entities are instances of the custom entity classes you define on your key set. In the running example, product is a class and product-sneaker-42 is an instance. Use Create a new entity class to declare a class, and Get entity class by ID to read the property, filtering, and projection declarations that govern its instances.

required
id#
Type: string
Default: no default
Identifier of the new DataSync entity. Omit it to let the server generate one. The identifier has at most 255 characters.
class required#
Type: string
Default: no default
Name of the entity class that this instance belongs to. The class is set at creation and immutable afterward.
classLevel#
Type: string
Default: no default
Class hierarchy level of class, either Global for a class the service provides or SubKey for one defined on your key set. The level is set at creation and immutable afterward. Omit it to let the service apply its default.
data required#
Type: object
Default: no default
The mutable entity data.
property of data: classVersion required#
Type: number
Default: no default
Version of the entity class schema.
property of data: status#
Type: string
Default: no default
Free-form lifecycle status. The maximum length is 100 characters.
property of data: payload#
Type: object
Default: no default
Free-form JSON object holding your application data.

Returns​

pubnub.dataSync.createEntity() resolves with the HTTP status and the created entity.

Syntax

1pubnub.dataSync.createEntity({
2    id: string,
3    class: string,
4    classLevel: string,
5    data: { classVersion: number, status: string, payload: object },
6}): Promise<DataSync.CreateEntityResponse>

Get entity​

pubnub.dataSync.getEntity() returns one DataSync entity by identifier through a PubNub client for JavaScript.

required
id required#
Type: string
Default: no default
Identifier of the entity.

Returns​

pubnub.dataSync.getEntity() resolves with the HTTP status and the requested entity.

Syntax

1pubnub.dataSync.getEntity({
2    id: string,
3}): Promise<DataSync.GetEntityResponse>

Get all entities​

pubnub.dataSync.getEntities() returns a paginated list of DataSync entities through a PubNub client for JavaScript.

The class parameter is required, entities are always listed within the context of their class. Listing a class also returns the entities of its subclasses, so getEntities({ class: 'product' }) returns every product plus every instance of a class that extends product. For pagination, filtering, and sorting, see sorting and pagination.

required
class required#
Type: string
Default: no default
Name of the entity class to list. The class parameter is required.
classVersion#
Type: number
Default: no default
Class version to list. Omit it to list entities of every version of the class.
classLevel#
Type: string
Default: no default
Class hierarchy level of class, either Global for a class the service provides or SubKey for one defined on your key set. Use it to disambiguate a class name defined at both levels.
cursor#
Type: string
Default: no default
Opaque pagination cursor from the previous page. Omit it to get the first page.
limit#
Type: number
Default: no default
Maximum number of entities to return in one page, up to 100.
filter#
Type: string
Default: no default
Filter expression evaluated against eventually consistent storage, so results can briefly lag writes. The parameter supports the full expression language over properties declared with filtering mode full. A call cannot combine it with filterFast.
filterFast#
Type: string
Default: no default
Filter expression evaluated against strongly consistent storage, so it reflects the latest writes. The parameter accepts up to 10 conditions by default (configurable per keyset) over properties declared with filtering mode simple or full. A call cannot combine it with filter.
sort#
Type: object | string
Default: no default
Sort order of the returned entities. An object that maps each field to 'asc', 'desc', or null (service default), or a comma-separated string such as 'createdAt:desc'.

Returns​

pubnub.dataSync.getEntities() resolves with the HTTP status, an array of entities, and paging metadata.

Syntax

1pubnub.dataSync.getEntities({
2    class: string,
3    classVersion: number,
4    classLevel: string,
5    cursor: string,
6    limit: number,
7    filter: string,
8    filterFast: string,
9    sort: object | string,
10}): Promise<DataSync.GetEntitiesResponse>

Set entity​

pubnub.dataSync.setEntity() replaces a DataSync entity in full through a PubNub client for JavaScript. The call clears a stored status or payload that it omits.

The entity class is immutable after creation and cannot be sent. To guard against concurrent writes, pass ifMatchesEtag. See optimistic concurrency with ETags.

required
id required#
Type: string
Default: no default
Identifier of the entity.
data required#
Type: object
Default: no default
The replacement entity data. The entity class is immutable and cannot be included.
property of data: classVersion required#
Type: number
Default: no default
Version of the entity class schema.
property of data: status#
Type: string
Default: no default
Free-form lifecycle status. The maximum length is 100 characters.
property of data: payload#
Type: object
Default: no default
Free-form JSON object holding your application data.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The update succeeds only if it still matches, otherwise the server returns 412.

Returns​

pubnub.dataSync.setEntity() resolves with the HTTP status and the stored entity.

Syntax

1pubnub.dataSync.setEntity({
2    id: string,
3    data: { classVersion: number, status: string, payload: object },
4    ifMatchesEtag: string,
5}): Promise<DataSync.SetEntityResponse>

Update entity​

pubnub.dataSync.updateEntity() applies a JSON Patch (RFC 6902) partial update to a DataSync entity through a PubNub client for JavaScript. The call needs at least one patch operation, and fields that no operation addresses stay unchanged.

required
id required#
Type: string
Default: no default
Identifier of the entity.
add#
Type: object
Default: no default
Full JSON Pointers mapped to values to add.
replace#
Type: object
Default: no default
Full JSON Pointers mapped to replacement values.
remove#
Type: array
Default: no default
Full JSON Pointers to remove.
move#
Type: array
Default: no default
Pairs of JSON Pointers, each with a from and a path. The value at from is removed and re-added at path.
copy#
Type: array
Default: no default
Pairs of JSON Pointers, each with a from and a path. The value at from is duplicated to path.
test#
Type: object
Default: no default
Full JSON Pointers mapped to expected values. The patch fails if any value does not match.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The patch succeeds only if it still matches, otherwise the server returns 412.

Paths can target fields inside payload or top-level stored fields. A JSON Pointer that starts with /payload/ targets a payload field, and a root pointer such as /status targets a top-level field. See partial update for the JSON Pointer rules.

At least one of add, replace, remove, move, copy, or test must be provided.

A single updateEntity() call can mix add, replace, remove, move, copy, and test. The order you write the keys in does not matter. The SDK always sends the operations in the same order, with test last.

Returns​

pubnub.dataSync.updateEntity() resolves with the HTTP status and the updated entity.

Syntax

1pubnub.dataSync.updateEntity({
2    id: string,
3    add: object,
4    replace: object,
5    remove: string[],
6    move: { from: string, path: string }[],
7    copy: { from: string, path: string }[],
8    test: object,
9    ifMatchesEtag: string,
10}): Promise<DataSync.UpdateEntityResponse>

Remove entity​

pubnub.dataSync.removeEntity() deletes a DataSync entity by identifier through a PubNub client for JavaScript.

required
id required#
Type: string
Default: no default
Identifier of the entity.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The delete succeeds only if it still matches, otherwise the server returns 412.

Returns​

pubnub.dataSync.removeEntity() resolves with only the HTTP status.

Syntax

1pubnub.dataSync.removeEntity({
2    id: string,
3    ifMatchesEtag: string,
4}): Promise<DataSync.RemoveEntityResponse>

Create relationship​

pubnub.dataSync.createRelationship() creates a DataSync relationship through a PubNub client for JavaScript. The server generates the identifier unless the call supplies one.

A relationship links two entities and carries its own payload. In the running example, the ProductOwner relationship links seller-bob to product-sneaker-42.

Relationships are instances of the relationship classes you define on your key set. A relationship class declares the cardinality the service enforces (one-to-one, one-to-many, or many-to-many) and, optionally, which entity class each side must belong to. Use Create a new relationship class to declare a class, and Get relationship class by name and version to read it back.

The relationship class's cardinality is enforced on create. A relationship that violates its class's cardinality is rejected with a 409.

required
id#
Type: string
Default: no default
Identifier of the new DataSync relationship. Omit it to let the server generate one. The identifier has at most 255 characters.
class required#
Type: string
Default: no default
Name of the relationship class that this instance belongs to. The class is set at creation and immutable afterward.
entityAId required#
Type: string
Default: no default
Identifier of the first linked entity. Immutable after creation.
entityBId required#
Type: string
Default: no default
Identifier of the second linked entity. Immutable after creation.
data required#
Type: object
Default: no default
The mutable relationship data.
property of data: classVersion required#
Type: number
Default: no default
Version of the relationship class schema.
property of data: status#
Type: string
Default: no default
Free-form lifecycle status. The maximum length is 100 characters.
property of data: payload#
Type: object
Default: no default
Free-form JSON object holding your application data.

Returns​

pubnub.dataSync.createRelationship() resolves with the HTTP status and the created relationship.

Syntax

1pubnub.dataSync.createRelationship({
2    id: string,
3    class: string,
4    entityAId: string,
5    entityBId: string,
6    data: { classVersion: number, status: string, payload: object },
7}): Promise<DataSync.CreateRelationshipResponse>

Get relationship​

pubnub.dataSync.getRelationship() returns one DataSync relationship by identifier through a PubNub client for JavaScript.

required
id required#
Type: string
Default: no default
Identifier of the relationship.

Returns​

pubnub.dataSync.getRelationship() resolves with the HTTP status and the requested relationship.

Syntax

1pubnub.dataSync.getRelationship({
2    id: string,
3}): Promise<DataSync.GetRelationshipResponse>

Get all relationships​

pubnub.dataSync.getRelationships() returns a paginated list of DataSync relationships through a PubNub client for JavaScript.

The class parameter is required. Filter by entityAId or entityBId to list a specific entity's links. For pagination, filtering, and sorting, see sorting and pagination.

required
class required#
Type: string
Default: no default
Name of the relationship class to list. The class parameter is required.
classVersion#
Type: number
Default: no default
Class version to list. Omit it to list relationships of every version of the class.
entityAId#
Type: string
Default: no default
List only relationships whose first entity has this identifier.
entityBId#
Type: string
Default: no default
List only relationships whose second entity has this identifier.
cursor#
Type: string
Default: no default
Opaque pagination cursor from the previous page. Omit it to get the first page.
limit#
Type: number
Default: no default
Maximum number of relationships to return in one page, up to 100.
filter#
Type: string
Default: no default
Filter expression evaluated against eventually consistent storage, so results can briefly lag writes. The parameter supports the full expression language over properties declared with filtering mode full. A call cannot combine it with filterFast.
filterFast#
Type: string
Default: no default
Filter expression evaluated against strongly consistent storage, so it reflects the latest writes. The parameter accepts up to 10 conditions by default (configurable per keyset) over properties declared with filtering mode simple or full. A call cannot combine it with filter.
sort#
Type: object | string
Default: no default
Sort order of the returned relationships. An object that maps each field to 'asc', 'desc', or null (service default), or a comma-separated string such as 'createdAt:desc'.

Returns​

pubnub.dataSync.getRelationships() resolves with the HTTP status, an array of relationships, and paging metadata.

Syntax

1pubnub.dataSync.getRelationships({
2    class: string,
3    classVersion: number,
4    entityAId: string,
5    entityBId: string,
6    cursor: string,
7    limit: number,
8    filter: string,
9    filterFast: string,
10    sort: object | string,
11}): Promise<DataSync.GetRelationshipsResponse>

Set relationship​

pubnub.dataSync.setRelationship() replaces a DataSync relationship in full through a PubNub client for JavaScript. The call clears a stored status or payload that it omits.

The linked entity identifiers are immutable, so resend the same entityAId and entityBId. To guard against concurrent writes, pass ifMatchesEtag. See optimistic concurrency with ETags.

required
id required#
Type: string
Default: no default
Identifier of the relationship.
entityAId required#
Type: string
Default: no default
Identifier of the first linked entity. Must match the value set at creation.
entityBId required#
Type: string
Default: no default
Identifier of the second linked entity. Must match the value set at creation.
data required#
Type: object
Default: no default
The replacement relationship data. The relationship class is immutable and cannot be included.
property of data: classVersion required#
Type: number
Default: no default
Version of the relationship class schema.
property of data: status#
Type: string
Default: no default
Free-form lifecycle status. The maximum length is 100 characters.
property of data: payload#
Type: object
Default: no default
Free-form JSON object holding your application data.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The update succeeds only if it still matches, otherwise the server returns 412.

Returns​

pubnub.dataSync.setRelationship() resolves with the HTTP status and the stored relationship.

Syntax

1pubnub.dataSync.setRelationship({
2    id: string,
3    entityAId: string,
4    entityBId: string,
5    data: { classVersion: number, status: string, payload: object },
6    ifMatchesEtag: string,
7}): Promise<DataSync.SetRelationshipResponse>

Update relationship​

pubnub.dataSync.updateRelationship() applies a JSON Patch (RFC 6902) partial update to a DataSync relationship through a PubNub client for JavaScript. The call needs at least one patch operation, and fields that no operation addresses stay unchanged.

required
id required#
Type: string
Default: no default
Identifier of the relationship.
add#
Type: object
Default: no default
Full JSON Pointers mapped to values to add.
replace#
Type: object
Default: no default
Full JSON Pointers mapped to replacement values.
remove#
Type: array
Default: no default
Full JSON Pointers to remove.
move#
Type: array
Default: no default
Pairs of JSON Pointers, each with a from and a path. The value at from is removed and re-added at path.
copy#
Type: array
Default: no default
Pairs of JSON Pointers, each with a from and a path. The value at from is duplicated to path.
test#
Type: object
Default: no default
Full JSON Pointers mapped to expected values. The patch fails if any value does not match.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The patch succeeds only if it still matches, otherwise the server returns 412.

Paths can target fields inside payload or top-level stored fields. A JSON Pointer that starts with /payload/ targets a payload field, and a root pointer such as /status targets a top-level field. See partial update for the JSON Pointer rules.

At least one of add, replace, remove, move, copy, or test must be provided.

A single updateRelationship() call can mix add, replace, remove, move, copy, and test. The order you write the keys in does not matter. The SDK always sends the operations in the same order, with test last.

Returns​

pubnub.dataSync.updateRelationship() resolves with the HTTP status and the updated relationship.

Syntax

1pubnub.dataSync.updateRelationship({
2    id: string,
3    add: object,
4    replace: object,
5    remove: string[],
6    move: { from: string, path: string }[],
7    copy: { from: string, path: string }[],
8    test: object,
9    ifMatchesEtag: string,
10}): Promise<DataSync.UpdateRelationshipResponse>

Remove relationship​

pubnub.dataSync.removeRelationship() deletes a DataSync relationship by identifier through a PubNub client for JavaScript.

required
id required#
Type: string
Default: no default
Identifier of the relationship.
ifMatchesEtag#
Type: string
Default: no default
The eTag from a prior read. The delete succeeds only if it still matches, otherwise the server returns 412.

Returns​

pubnub.dataSync.removeRelationship() resolves with only the HTTP status.

Syntax

1pubnub.dataSync.removeRelationship({
2    id: string,
3    ifMatchesEtag: string,
4}): Promise<DataSync.RemoveRelationshipResponse>

Where each event is delivered​

The PubNub JavaScript SDK receives a DataSync change event on every channel whose name matches the identifier of an object that the change affects.

DataSync objects can publish create, update, and delete events that you receive in real time with a dataSync listener. Create a DataSync SDK entity for the object, subscribe to it, and attach the listener, described in the Add DataSync listener section of Publish and subscribe.

Each event names the change in event, identifies the object kind in objectType (user, channel, membership, entity, or relationship), and carries the object state in data. For a delete event, data holds only the id and, when the service reports it, deletedAt.

A relationship or membership change is delivered on the ids of the two objects it links, and never on a channel named after the relationship or membership id. A create for a user, channel, or entity is delivered only on its own id. An update or delete for a user, channel, or entity is also delivered on the id of every object connected to it at the time of the change. The connection can be a relationship or membership, in either direction.

The table shows the mapping for each kind of change.

Change tocreate delivered onupdate / delete delivered on
A userThe user's idThe user's id, plus the id of every entity, user, or channel connected to it by a relationship or membership
A channelThe channel's idThe channel's id, plus the id of every entity, user, or channel connected to it by a relationship or membership
An entityThe entity's idThe entity's id, plus the id of every entity, user, or channel connected to it by a relationship or membership
A membershipBoth the userId and the channelId of the membershipBoth the userId and the channelId of the membership
A relationshipBoth the entityAId and the entityBId of the relationshipBoth the entityAId and the entityBId of the relationship

So to see memberships appear and disappear for Alice, observe user-alice rather than the membership id. Unlike entity/user/channel events, a membership or relationship create is delivered on both linked ids too, the same as its update/delete. A client observing both sides of the same link receives the change twice, once per channel. Deduplicate create and update events on data.id and data.updatedAt, and delete events on data.id and data.deletedAt.

DataSync events are off by default. You enable event publishing for each class in the Admin Portal. See enabling DataSync events. See receiving events for the listener flow.

Basic usage

1

Was this page useful?

Last updated on