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

DataSync API for Kotlin SDK

DataSync is PubNub's data layer for storing application state (users, channels, memberships, and any custom object type) and keeping every connected client 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, it just gives you a scoped surface for subscribing and calling APIs. Refer to the Channel SDK entity.

The two meet in the DataSync SDK entities (DataSyncUser, DataSyncChannel, and DataSyncEntity): 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.

User and Channel entity classes and the Membership relationship class are predefined on every keyset, so you only need to define classes for your own custom entities and relationships.

A class definition is what decides, for every object of that class, which payload fields are filterable and sortable, which projection each field belongs to, and how long the object lives before it expires. Refer to managing classes for more information.

Every DataSync method returns an endpoint object, and a successful call yields a result object carrying the HTTP status. The remove* methods return the status on its own, every other method adds a data property holding the object, or the list of objects for a list method. A list method also adds a next property holding the pagination state. The SDK does not surface the HATEOAS links the service sends. A stored object carries its free-form status and its expiresAt auto-deletion timestamp (ISO 8601) whenever those are set on it. A failed call surfaces as a PubNubException whose statusCode is the HTTP status, for example 412, and whose pubnubError is a DATASYNC_* category chosen from that status. Read the DS- error code with dataSyncErrorCode(), or every error item with dataSyncErrors(). The raw response body stays in errorMessage and jso. A response that carries no DS- code keeps the generic HTTP_ERROR category. You pass payload as any value that serializes to a JSON object, such as a Map, and read it back as a Map<String, Any?>.

Every DataSync request must be authorized with a token or signature. A request with no credential fails with a 401; an invalid credential or a credential that doesn't permit the operation fails with a 403.

A signature means the client is configured with a secretKey, and the SDK then signs every request with it automatically. Never put a secret key in a client-side application, use it only on a server you control. Give client-side applications a token from grantToken() instead, set with setToken().

Request execution

Most PubNub Kotlin SDK method invocations return an Endpoint object, which allows you to decide whether to perform the operation synchronously or asynchronously.

You must invoke the .sync() or .async() method on the Endpoint to execute the request, or the operation will not be performed.

1val channel = pubnub.channel("channelName")
2

3channel.publish("This SDK rules!").async { result ->
4    result.onFailure { exception ->
5        // Handle error
6    }.onSuccess { value ->
7        // Handle successful method result
8    }
9}
Requires Access Manager

DataSync requires that the Access Manager add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

Users​

Users are built-in objects. There are no top-level name or email fields, all application data lives in the free-form payload. Refer to 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, filterable properties, define a subclass of User with Create a new entity class and pass its name as className.

Create user​

Creates a user. Supply a userId to control the identifier, or omit it to let the server generate one.

Method(s)​

1pubnub.dataSync.createUser(
2    classVersion: Int,
3    userId: String? = null,
4    className: String? = null,
5    classLevel: PNDataSyncClassLevel? = null,
6    status: String? = null,
7    payload: Any? = null,
8): CreateUser
* required
ParameterDescription
classVersion *
Type: Int
Default:
n/a
Version of the user class schema.
userId
Type: String
Default:
server-generated
User identifier. Omit to let the server generate a UUID. Max 255 characters.
className
Type: String
Default:
User
Name of the entity class this user belongs to. Must be User or one of its subclasses. Defaults to User on the server if omitted. Set at creation and immutable afterward.
classLevel
Type: PNDataSyncClassLevel
Default:
service default
Class hierarchy level of className, either GLOBAL for a class the service provides or SUBKEY for one defined on your keyset. Used to disambiguate classes with the same name defined at different levels. Set at creation and immutable afterward.
status
Type: String
Default:
n/a
Free-form lifecycle status. Max 100 characters.
payload
Type: Any
Default:
n/a
Free-form JSON object holding your application data.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 201,
3    "data": {
4        "id": "user-alice",
5        "entityClass": "User",
6        "entityClassVersion": 1,
7        "entityClassLevel": "Global",
8        "payload": { "name": "Alice", "type": "shopper" },
9        "createdAt": "2026-07-13T09:00:00.000Z",
10        "updatedAt": "2026-07-13T09:00:00.000Z",
11        "eTag": "AbCdEfGhIjKlMn"
12    }
13}

Get user​

Returns a single user by userId.

Method(s)​

1pubnub.dataSync.getUser(
2    userId: String,
3): GetUser
* required
ParameterDescription
userId *
Type: String
Default:
n/a
User identifier.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "user-alice",
5        "entityClass": "User",
6        "entityClassVersion": 1,
7        "entityClassLevel": "Global",
8        "payload": { "name": "Alice", "type": "shopper" },
9        "createdAt": "2026-07-13T09:00:00.000Z",
10        "updatedAt": "2026-07-13T09:00:00.000Z",
11        "eTag": "AbCdEfGhIjKlMn"
12    }
13}

Get all users​

Returns a paginated list of users. All parameters are optional, so you can call getUsers with no arguments. For pagination, filtering, and sorting, refer to sorting and pagination.

Method(s)​

1pubnub.dataSync.getUsers(
2    className: String? = null,
3    classVersion: Int? = null,
4    classLevel: PNDataSyncClassLevel? = null,
5    filterFast: String? = null,
6    filter: String? = null,
7    sort: List<PNDataSyncSortField> = emptyList(),
8    limit: Int? = null,
9    cursor: String? = null,
10): GetUsers
* required
ParameterDescription
className
Type: String
Default:
all user classes
User class to list. Omit to list the Global User class and all of its subclasses.
classVersion
Type: Int
Default:
all versions
User class version to list. Omit to list users across every version of the class.
classLevel
Type: PNDataSyncClassLevel
Default:
service default
Class hierarchy level of className, either GLOBAL for a class the service provides or SUBKEY for one defined on your keyset. Used to disambiguate a class name defined at both levels.
filterFast
Type: String
Default:
n/a
Filter expression evaluated against strongly consistent storage, so it reflects the latest writes. Accepts up to 10 conditions by default (raisable per keyset), over properties declared with filtering mode simple or full. Cannot be combined with filter.
filter
Type: String
Default:
n/a
Filter expression evaluated against eventually consistent storage, so results can briefly lag writes. Supports the full expression language, over properties declared with filtering mode full. Cannot be combined with filterFast.
sort
Type: List<PNDataSyncSortField>
Default:
empty list
Order results. Each entry names a property and a direction, for example PNDataSyncSortField("createdAt", ascending = false).
limit
Type: Int
Default:
20
Maximum number of users per page. Max 100.
cursor
Type: String
Default:
n/a
Opaque pagination cursor. Omit for the first page.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": [
4        {
5            "id": "user-alice",
6            "entityClass": "User",
7            "entityClassVersion": 1,
8            "entityClassLevel": "Global",
9            "payload": { "name": "Alice", "type": "shopper" },
10            "createdAt": "2026-07-13T09:00:00.000Z",
11            "updatedAt": "2026-07-13T09:00:00.000Z",
12            "eTag": "AbCdEfGhIjKlMn"
13        }
14    ],
15    "meta": {
show all 20 lines

Other examples​

Filter with filterFast​

filterFast is evaluated against strongly consistent storage, so it matches an object you just wrote. It runs over properties declared with filtering mode simple or full and accepts up to 10 conditions by default (raisable per keyset). Reference a declared property by its name, not its path. It shares the same expression language as filter, so only one of the two can be sent per call. The built-in User class declares only name and type, so those, plus the built-in id, createdAt, updatedAt, and status fields, are what you can filter on. To filter on other payload fields, such as email, define a subclass of User that declares them and pass it as className.

1
Filter with filter​

filter runs over properties declared with filtering mode full and is evaluated against eventually consistent storage, so a very recent write may not be matched yet. Reference a declared property by its name, not its path. It shares the same expression language as filterFast, so only one of the two can be sent per call.

1
Page through results with cursor​

Pass no cursor on the first call. Take next.cursor from the result and pass it back as cursor on the next call. Stop when next.hasNext is false.

1

Set user​

Replaces a user in full (PUT). Send the complete set of fields, any field you omit is cleared. className is immutable after creation and cannot be sent. Refer to optimistic concurrency with ETags for ifMatch. For a partial update, use Update user.

Method(s)​

1pubnub.dataSync.setUser(
2    userId: String,
3    classVersion: Int,
4    status: String? = null,
5    payload: Any? = null,
6    ifMatch: String? = null,
7): SetUser
* required
ParameterDescription
userId *
Type: String
Default:
n/a
User identifier.
classVersion *
Type: Int
Default:
n/a
Version of the user class schema.
status
Type: String
Default:
n/a
Free-form lifecycle status. Max 100 characters.
payload
Type: Any
Default:
n/a
Free-form JSON object holding your application data.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The update succeeds only if it still matches, otherwise the server returns 412.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "user-alice",
5        "entityClass": "User",
6        "entityClassVersion": 1,
7        "entityClassLevel": "Global",
8        "payload": { "name": "Alice B.", "type": "shopper" },
9        "createdAt": "2026-07-13T09:00:00.000Z",
10        "updatedAt": "2026-07-13T10:15:00.000Z",
11        "eTag": "CdEfGhIjKlMnOp"
12    }
13}

Update user​

Applies a partial update to a user with raw JSON Patch operations. Refer to partial update for the operation model.

Method(s)​

1pubnub.dataSync.updateUser(
2    userId: String,
3    operations: List<PNJsonPatchOperation>,
4    ifMatch: String? = null,
5): UpdateUser
* required
ParameterDescription
userId *
Type: String
Default:
n/a
User identifier.
operations *
Type: List<PNJsonPatchOperation>
Default:
n/a
One or more JSON Patch operations. Must contain at least one item.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The patch succeeds only if it still matches, otherwise the server returns 412.

Use a JSON Pointer that starts with /payload/ to target payload fields, or a root pointer (for example /status) to target a top-level field.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "user-alice",
5        "status": "active",
6        "entityClass": "User",
7        "entityClassVersion": 1,
8        "entityClassLevel": "Global",
9        "payload": { "name": "Alice B.", "type": "shopper" },
10        "createdAt": "2026-07-13T09:00:00.000Z",
11        "updatedAt": "2026-07-13T10:20:00.000Z",
12        "eTag": "EfGhIjKlMnOpQr"
13    }
14}

Remove user​

Deletes a user by userId.

Method(s)​

1pubnub.dataSync.removeUser(
2    userId: String,
3    ifMatch: String? = null,
4): RemoveUser
* required
ParameterDescription
userId *
Type: String
Default:
n/a
User identifier.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The delete succeeds only if it still matches, otherwise the server returns 412.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200
3}

Channels​

Channels work like users. They have no top-level name field, all application data lives in payload, and they support the same operations. Refer to 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. Subclass it with Create a new entity class to add declared properties, then pass the subclass name as className.

Create channel​

Creates a channel. Supply a channelId to control the identifier, or omit it to let the server generate one.

Method(s)​

1pubnub.dataSync.createChannel(
2    classVersion: Int,
3    channelId: String? = null,
4    className: String? = null,
5    classLevel: PNDataSyncClassLevel? = null,
6    status: String? = null,
7    payload: Any? = null,
8): CreateChannel
* required
ParameterDescription
classVersion *
Type: Int
Default:
n/a
Version of the channel class schema.
channelId
Type: String
Default:
server-generated
Channel identifier. Omit to let the server generate a UUID. Max 255 characters.
className
Type: String
Default:
Channel
Name of the entity class this channel belongs to. Must be Channel or one of its subclasses. Defaults to Channel on the server if omitted. Set at creation and immutable afterward.
classLevel
Type: PNDataSyncClassLevel
Default:
service default
Class hierarchy level of className, either GLOBAL for a class the service provides or SUBKEY for one defined on your keyset. Used to disambiguate classes with the same name defined at different levels. Set at creation and immutable afterward.
status
Type: String
Default:
n/a
Free-form lifecycle status. Max 100 characters.
payload
Type: Any
Default:
n/a
Free-form JSON object holding your application data.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 201,
3    "data": {
4        "id": "channel-summer-sale",
5        "entityClass": "Channel",
6        "entityClassVersion": 1,
7        "entityClassLevel": "Global",
8        "payload": { "name": "Summer Sale", "type": "promotion" },
9        "createdAt": "2026-07-13T09:05:00.000Z",
10        "updatedAt": "2026-07-13T09:05:00.000Z",
11        "eTag": "GhIjKlMnOpQrSt"
12    }
13}

Get channel​

Returns a single channel by channelId.

Method(s)​

1pubnub.dataSync.getChannel(
2    channelId: String,
3): GetChannel
* required
ParameterDescription
channelId *
Type: String
Default:
n/a
Channel identifier.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "channel-summer-sale",
5        "entityClass": "Channel",
6        "entityClassVersion": 1,
7        "entityClassLevel": "Global",
8        "payload": { "name": "Summer Sale", "type": "promotion" },
9        "createdAt": "2026-07-13T09:05:00.000Z",
10        "updatedAt": "2026-07-13T09:05:00.000Z",
11        "eTag": "GhIjKlMnOpQrSt"
12    }
13}

Get all channels​

Returns a paginated list of channels. All parameters are optional, so you can call getChannels with no arguments. For pagination, filtering, and sorting, refer to sorting and pagination.

Method(s)​

1pubnub.dataSync.getChannels(
2    className: String? = null,
3    classVersion: Int? = null,
4    classLevel: PNDataSyncClassLevel? = null,
5    filterFast: String? = null,
6    filter: String? = null,
7    sort: List<PNDataSyncSortField> = emptyList(),
8    limit: Int? = null,
9    cursor: String? = null,
10): GetChannels
* required
ParameterDescription
className
Type: String
Default:
all channel classes
Channel class to list. Omit to list the Global Channel class and all of its subclasses.
classVersion
Type: Int
Default:
all versions
Channel class version to list. Omit to list channels across every version of the class.
classLevel
Type: PNDataSyncClassLevel
Default:
service default
Class hierarchy level of className, either GLOBAL for a class the service provides or SUBKEY for one defined on your keyset. Used to disambiguate a class name defined at both levels.
filterFast
Type: String
Default:
n/a
Filter expression evaluated against strongly consistent storage, so it reflects the latest writes. Accepts up to 10 conditions by default (raisable per keyset), over properties declared with filtering mode simple or full. Cannot be combined with filter.
filter
Type: String
Default:
n/a
Filter expression evaluated against eventually consistent storage, so results can briefly lag writes. Supports the full expression language, over properties declared with filtering mode full. Cannot be combined with filterFast.
sort
Type: List<PNDataSyncSortField>
Default:
empty list
Order results. Each entry names a property and a direction.
limit
Type: Int
Default:
20
Maximum number of channels per page. Max 100.
cursor
Type: String
Default:
n/a
Opaque pagination cursor. Omit for the first page.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": [
4        {
5            "id": "channel-summer-sale",
6            "entityClass": "Channel",
7            "entityClassVersion": 1,
8            "entityClassLevel": "Global",
9            "payload": { "name": "Summer Sale", "type": "promotion" },
10            "createdAt": "2026-07-13T09:05:00.000Z",
11            "updatedAt": "2026-07-13T09:05:00.000Z",
12            "eTag": "GhIjKlMnOpQrSt"
13        }
14    ],
15    "meta": {
show all 20 lines

Other examples​

Filter with filterFast​

filterFast is evaluated against strongly consistent storage, so it matches an object you just wrote. It runs over properties declared with filtering mode simple or full and accepts up to 10 conditions by default (raisable per keyset). Reference a declared property by its name, not its path. It shares the same expression language as filter, so only one of the two can be sent per call. The built-in Channel class declares only name and type, so those, plus the built-in id, createdAt, updatedAt, and status fields, are what you can filter on. To filter on other payload fields, such as region, define a subclass of Channel that declares them and pass it as className.

1
Filter with filter​

filter runs over properties declared with filtering mode full and is evaluated against eventually consistent storage, so a very recent write may not be matched yet. Reference a declared property by its name, not its path. It shares the same expression language as filterFast, so only one of the two can be sent per call.

1
Page through results with cursor​

Pass no cursor on the first call. Take next.cursor from the result and pass it back as cursor on the next call. Stop when next.hasNext is false.

1

Set channel​

Replaces a channel in full (PUT). Send the complete set of fields, any field you omit is cleared. className is immutable after creation and cannot be sent. Refer to optimistic concurrency with ETags for ifMatch. For a partial update, use Update channel.

Method(s)​

1pubnub.dataSync.setChannel(
2    channelId: String,
3    classVersion: Int,
4    status: String? = null,
5    payload: Any? = null,
6    ifMatch: String? = null,
7): SetChannel
* required
ParameterDescription
channelId *
Type: String
Default:
n/a
Channel identifier.
classVersion *
Type: Int
Default:
n/a
Version of the channel class schema.
status
Type: String
Default:
n/a
Free-form lifecycle status. Max 100 characters.
payload
Type: Any
Default:
n/a
Free-form JSON object holding your application data.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The update succeeds only if it still matches, otherwise the server returns 412.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "channel-summer-sale",
5        "entityClass": "Channel",
6        "entityClassVersion": 1,
7        "entityClassLevel": "Global",
8        "payload": { "name": "Summer Sale 2026", "type": "promotion" },
9        "createdAt": "2026-07-13T09:05:00.000Z",
10        "updatedAt": "2026-07-13T11:00:00.000Z",
11        "eTag": "IjKlMnOpQrStUv"
12    }
13}

Update channel​

Applies a partial update to a channel with raw JSON Patch operations. Refer to partial update for the operation model.

Method(s)​

1pubnub.dataSync.updateChannel(
2    channelId: String,
3    operations: List<PNJsonPatchOperation>,
4    ifMatch: String? = null,
5): UpdateChannel
* required
ParameterDescription
channelId *
Type: String
Default:
n/a
Channel identifier.
operations *
Type: List<PNJsonPatchOperation>
Default:
n/a
One or more JSON Patch operations. Must contain at least one item.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The patch succeeds only if it still matches, otherwise the server returns 412.

Use a JSON Pointer that starts with /payload/ to target payload fields, or a root pointer (for example /status) to target a top-level field.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "channel-summer-sale",
5        "status": "active",
6        "entityClass": "Channel",
7        "entityClassVersion": 1,
8        "entityClassLevel": "Global",
9        "payload": { "name": "Summer Sale 2026", "type": "promotion" },
10        "createdAt": "2026-07-13T09:05:00.000Z",
11        "updatedAt": "2026-07-13T11:05:00.000Z",
12        "eTag": "KlMnOpQrStUvWx"
13    }
14}

Remove channel​

Deletes a channel by channelId.

Method(s)​

1pubnub.dataSync.removeChannel(
2    channelId: String,
3    ifMatch: String? = null,
4): RemoveChannel
* required
ParameterDescription
channelId *
Type: String
Default:
n/a
Channel identifier.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The delete succeeds only if it still matches, otherwise the server returns 412.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200
3}

Memberships​

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" }. Refer to 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.

Create membership​

Creates a membership linking a user to a channel. The userId/channelId pair must be unique for the membership class. A membership that duplicates an existing pair is rejected with a 409.

Method(s)​

1pubnub.dataSync.createMembership(
2    channelId: String,
3    userId: String,
4    classVersion: Int,
5    membershipId: String? = null,
6    status: String? = null,
7    payload: Any? = null,
8): CreateMembership
* required
ParameterDescription
channelId *
Type: String
Default:
n/a
Identifier of the channel in the membership.
userId *
Type: String
Default:
n/a
Identifier of the user in the membership.
classVersion *
Type: Int
Default:
n/a
Version of the Membership relationship class schema.
membershipId
Type: String
Default:
server-generated
Membership identifier. Omit to let the server generate a UUID. Max 255 characters.
status
Type: String
Default:
n/a
Free-form lifecycle status. Max 100 characters.
payload
Type: Any
Default:
n/a
Free-form JSON object holding your application data.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 201,
3    "data": {
4        "id": "membership-alice-summer-sale",
5        "channelId": "channel-summer-sale",
6        "userId": "user-alice",
7        "relationshipClass": "Membership",
8        "relationshipClassVersion": 1,
9        "payload": { "role": "viewer" },
10        "createdAt": "2026-07-13T09:10:00.000Z",
11        "updatedAt": "2026-07-13T09:10:00.000Z",
12        "eTag": "MnOpQrStUvWxYz"
13    }
14}

Get membership​

Returns a single membership by membershipId.

Method(s)​

1pubnub.dataSync.getMembership(
2    membershipId: String,
3): GetMembership
* required
ParameterDescription
membershipId *
Type: String
Default:
n/a
Membership identifier.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "membership-alice-summer-sale",
5        "channelId": "channel-summer-sale",
6        "userId": "user-alice",
7        "relationshipClass": "Membership",
8        "relationshipClassVersion": 1,
9        "payload": { "role": "viewer" },
10        "createdAt": "2026-07-13T09:10:00.000Z",
11        "updatedAt": "2026-07-13T09:10:00.000Z",
12        "eTag": "MnOpQrStUvWxYz"
13    }
14}

Get all memberships​

Returns a paginated list of memberships. All parameters are optional, so you can call getMemberships with no arguments. userId and channelId can be set independently, together, or omitted entirely. Filter by userId to list a user's memberships or by channelId to list a channel's members. For pagination, filtering, and sorting, refer to sorting and pagination.

Method(s)​

1pubnub.dataSync.getMemberships(
2    channelId: String? = null,
3    userId: String? = null,
4    classVersion: Int? = null,
5    filterFast: String? = null,
6    filter: String? = null,
7    sort: List<PNDataSyncSortField> = emptyList(),
8    limit: Int? = null,
9    cursor: String? = null,
10): GetMemberships
* required
ParameterDescription
channelId
Type: String
Default:
n/a
List only memberships for this channel.
userId
Type: String
Default:
n/a
List only memberships for this user.
classVersion
Type: Int
Default:
all versions
Membership class version to list. Omit to list memberships across every version of the class.
filterFast
Type: String
Default:
n/a
Filter expression evaluated against strongly consistent storage, so it reflects the latest writes. Accepts up to 10 conditions by default (raisable per keyset), over properties declared with filtering mode simple or full. Cannot be combined with filter.
filter
Type: String
Default:
n/a
Filter expression evaluated against eventually consistent storage, so results can briefly lag writes. Supports the full expression language, over properties declared with filtering mode full. Cannot be combined with filterFast.
sort
Type: List<PNDataSyncSortField>
Default:
empty list
Order results. Each entry names a property and a direction.
limit
Type: Int
Default:
20
Maximum number of memberships per page. Max 100.
cursor
Type: String
Default:
n/a
Opaque pagination cursor. Omit for the first page.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": [
4        {
5            "id": "membership-alice-summer-sale",
6            "channelId": "channel-summer-sale",
7            "userId": "user-alice",
8            "relationshipClass": "Membership",
9            "relationshipClassVersion": 1,
10            "payload": { "role": "viewer" },
11            "createdAt": "2026-07-13T09:10:00.000Z",
12            "updatedAt": "2026-07-13T09:10:00.000Z",
13            "eTag": "MnOpQrStUvWxYz"
14        }
15    ],
show all 21 lines

Other examples​

List a channel's members with channelId​

Pass channelId instead of userId to list the members of a channel rather than a user's memberships.

1
Filter with filterFast​

filterFast is evaluated against strongly consistent storage, so it matches an object you just wrote. It runs over properties declared with filtering mode simple or full and accepts up to 10 conditions by default (raisable per keyset). Reference a declared property by its name, not its path. It shares the same expression language as filter, so only one of the two can be sent per call.

1
Filter with filter​

filter runs over properties declared with filtering mode full and is evaluated against eventually consistent storage, so a very recent write may not be matched yet. Reference a declared property by its name, not its path. It shares the same expression language as filterFast, so only one of the two can be sent per call.

1
Page through results with cursor​

Pass no cursor on the first call. Take next.cursor from the result and pass it back as cursor on the next call. Stop when next.hasNext is false.

1

Set membership​

Replaces a membership in full (PUT). Send the complete set of fields, any field you omit is cleared. The linked user and channel are immutable, so setMembership doesn't expose channelId/userId at all, there's nothing to resend. Refer to optimistic concurrency with ETags for ifMatch. For a partial update, use Update membership.

Method(s)​

1pubnub.dataSync.setMembership(
2    membershipId: String,
3    classVersion: Int,
4    status: String? = null,
5    payload: Any? = null,
6    ifMatch: String? = null,
7): SetMembership
* required
ParameterDescription
membershipId *
Type: String
Default:
n/a
Membership identifier.
classVersion *
Type: Int
Default:
n/a
Version of the Membership relationship class schema.
status
Type: String
Default:
n/a
Free-form lifecycle status. Max 100 characters.
payload
Type: Any
Default:
n/a
Free-form JSON object holding your application data.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The update succeeds only if it still matches, otherwise the server returns 412.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "membership-alice-summer-sale",
5        "channelId": "channel-summer-sale",
6        "userId": "user-alice",
7        "relationshipClass": "Membership",
8        "relationshipClassVersion": 1,
9        "payload": { "role": "moderator" },
10        "createdAt": "2026-07-13T09:10:00.000Z",
11        "updatedAt": "2026-07-13T12:00:00.000Z",
12        "eTag": "OpQrStUvWxYzAb"
13    }
14}

Update membership​

Applies a partial update to a membership with raw JSON Patch operations. Refer to partial update for the operation model.

Method(s)​

1pubnub.dataSync.updateMembership(
2    membershipId: String,
3    operations: List<PNJsonPatchOperation>,
4    ifMatch: String? = null,
5): UpdateMembership
* required
ParameterDescription
membershipId *
Type: String
Default:
n/a
Membership identifier.
operations *
Type: List<PNJsonPatchOperation>
Default:
n/a
One or more JSON Patch operations. Must contain at least one item.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The patch succeeds only if it still matches, otherwise the server returns 412.

Use a JSON Pointer that starts with /payload/ to target payload fields, or a root pointer (for example /status) to target a top-level field.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "membership-alice-summer-sale",
5        "status": "active",
6        "channelId": "channel-summer-sale",
7        "userId": "user-alice",
8        "relationshipClass": "Membership",
9        "relationshipClassVersion": 1,
10        "payload": { "role": "moderator" },
11        "createdAt": "2026-07-13T09:10:00.000Z",
12        "updatedAt": "2026-07-13T12:05:00.000Z",
13        "eTag": "QrStUvWxYzAbCd"
14    }
15}

Remove membership​

Deletes a membership by membershipId.

Method(s)​

1pubnub.dataSync.removeMembership(
2    membershipId: String,
3    ifMatch: String? = null,
4): RemoveMembership
* required
ParameterDescription
membershipId *
Type: String
Default:
n/a
Membership identifier.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The delete succeeds only if it still matches, otherwise the server returns 412.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200
3}

Entities​

Entities are instances of the custom entity classes you define on your keyset. 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.

Entity classes can extend one another. Listing a class also returns the entities of its subclasses, so getEntities(className = "product") returns every product plus every instance of a class that extends product.

Create entity​

Creates an entity of a given class and version.

Method(s)​

1pubnub.dataSync.createEntity(
2    className: String,
3    classVersion: Int,
4    classLevel: PNDataSyncClassLevel? = null,
5    entityId: String? = null,
6    status: String? = null,
7    payload: Any? = null,
8): CreateEntity
* required
ParameterDescription
className *
Type: String
Default:
n/a
Name of the entity class this instance belongs to. Set at creation and immutable afterward.
classVersion *
Type: Int
Default:
n/a
Version of the entity class schema.
classLevel
Type: PNDataSyncClassLevel
Default:
service default
Class hierarchy level of className, either GLOBAL for a class the service provides or SUBKEY for one defined on your keyset. Used to disambiguate classes with the same name defined at different levels. Set at creation and immutable afterward.
entityId
Type: String
Default:
server-generated
Entity identifier. Omit to let the server generate a UUID. Max 255 characters.
status
Type: String
Default:
n/a
Free-form lifecycle status. Max 100 characters.
payload
Type: Any
Default:
n/a
Free-form JSON object holding your application data.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 201,
3    "data": {
4        "id": "product-sneaker-42",
5        "entityClass": "product",
6        "entityClassVersion": 1,
7        "entityClassLevel": "SubKey",
8        "payload": { "name": "Retro Sneaker", "price": 89.99, "stock": 12 },
9        "createdAt": "2026-07-13T09:15:00.000Z",
10        "updatedAt": "2026-07-13T09:15:00.000Z",
11        "eTag": "StUvWxYzAbCdEf"
12    }
13}

Get entity​

Returns a single entity by entityId.

Method(s)​

1pubnub.dataSync.getEntity(
2    entityId: String,
3): GetEntity
* required
ParameterDescription
entityId *
Type: String
Default:
n/a
Entity identifier.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "product-sneaker-42",
5        "entityClass": "product",
6        "entityClassVersion": 1,
7        "entityClassLevel": "SubKey",
8        "payload": { "name": "Retro Sneaker", "price": 89.99, "stock": 12 },
9        "createdAt": "2026-07-13T09:15:00.000Z",
10        "updatedAt": "2026-07-13T09:15:00.000Z",
11        "eTag": "StUvWxYzAbCdEf"
12    }
13}

Get all entities​

Returns a paginated list of entities within a class. The className parameter is required, entities are always listed within the context of their class. For pagination, filtering, and sorting, refer to sorting and pagination.

Method(s)​

1pubnub.dataSync.getEntities(
2    className: String,
3    classVersion: Int? = null,
4    classLevel: PNDataSyncClassLevel? = null,
5    filterFast: String? = null,
6    filter: String? = null,
7    sort: List<PNDataSyncSortField> = emptyList(),
8    limit: Int? = null,
9    cursor: String? = null,
10): GetEntities
* required
ParameterDescription
className *
Type: String
Default:
n/a
Name of the entity class to list.
classVersion
Type: Int
Default:
all versions
Entity class version to list. Omit to list entities across every version of the class.
classLevel
Type: PNDataSyncClassLevel
Default:
service default
Class hierarchy level of className, either GLOBAL for a class the service provides or SUBKEY for one defined on your keyset. Used to disambiguate a class name defined at both levels.
filterFast
Type: String
Default:
n/a
Filter expression evaluated against strongly consistent storage, so it reflects the latest writes. Accepts up to 10 conditions by default (raisable per keyset), over properties declared with filtering mode simple or full. Cannot be combined with filter.
filter
Type: String
Default:
n/a
Filter expression evaluated against eventually consistent storage, so results can briefly lag writes. Supports the full expression language, over properties declared with filtering mode full. Cannot be combined with filterFast.
sort
Type: List<PNDataSyncSortField>
Default:
empty list
Order results. Each entry names a property and a direction.
limit
Type: Int
Default:
20
Maximum number of entities per page. Max 100.
cursor
Type: String
Default:
n/a
Opaque pagination cursor. Omit for the first page.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": [
4        {
5            "id": "product-sneaker-42",
6            "entityClass": "product",
7            "entityClassVersion": 1,
8            "entityClassLevel": "SubKey",
9            "payload": { "name": "Retro Sneaker", "price": 89.99, "stock": 12 },
10            "createdAt": "2026-07-13T09:15:00.000Z",
11            "updatedAt": "2026-07-13T09:15:00.000Z",
12            "eTag": "StUvWxYzAbCdEf"
13        }
14    ],
15    "meta": {
show all 20 lines

Other examples​

Filter with filterFast​

filterFast is evaluated against strongly consistent storage, so it matches an object you just wrote. It runs over properties declared with filtering mode simple or full and accepts up to 10 conditions by default (raisable per keyset). Reference a declared property by its name, not its path, and combine conditions with && and ||. It shares the same expression language as filter, so only one of the two can be sent per call.

1
Filter with filter​

filter runs over properties declared with filtering mode full and is evaluated against eventually consistent storage, so a very recent write may not be matched yet. Reference a declared property by its name, not its path, and combine conditions with && and ||. It shares the same expression language as filterFast, so only one of the two can be sent per call.

1
Page through results with cursor​

Pass no cursor on the first call. Take next.cursor from the result and pass it back as cursor on the next call. Stop when next.hasNext is false.

1

Set entity​

Replaces a entity in full (PUT). Send the complete set of fields, any field you omit is cleared. className is immutable after creation and cannot be sent. Refer to optimistic concurrency with ETags for ifMatch. For a partial update, use Update entity.

Method(s)​

1pubnub.dataSync.setEntity(
2    entityId: String,
3    classVersion: Int,
4    status: String? = null,
5    payload: Any? = null,
6    ifMatch: String? = null,
7): SetEntity
* required
ParameterDescription
entityId *
Type: String
Default:
n/a
Entity identifier.
classVersion *
Type: Int
Default:
n/a
Version of the entity class schema.
status
Type: String
Default:
n/a
Free-form lifecycle status. Max 100 characters.
payload
Type: Any
Default:
n/a
Free-form JSON object holding your application data.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The update succeeds only if it still matches, otherwise the server returns 412.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "product-sneaker-42",
5        "entityClass": "product",
6        "entityClassVersion": 1,
7        "entityClassLevel": "SubKey",
8        "payload": { "name": "Retro Sneaker", "price": 79.99, "stock": 12 },
9        "createdAt": "2026-07-13T09:15:00.000Z",
10        "updatedAt": "2026-07-13T13:00:00.000Z",
11        "eTag": "UvWxYzAbCdEfGh"
12    }
13}

Update entity​

Applies a partial update to a entity with raw JSON Patch operations. Refer to partial update for the operation model.

Method(s)​

1pubnub.dataSync.updateEntity(
2    entityId: String,
3    operations: List<PNJsonPatchOperation>,
4    ifMatch: String? = null,
5): UpdateEntity
* required
ParameterDescription
entityId *
Type: String
Default:
n/a
Entity identifier.
operations *
Type: List<PNJsonPatchOperation>
Default:
n/a
One or more JSON Patch operations. Must contain at least one item.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The patch succeeds only if it still matches, otherwise the server returns 412.

Use a JSON Pointer that starts with /payload/ to target payload fields, or a root pointer (for example /status) to target a top-level field.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "product-sneaker-42",
5        "entityClass": "product",
6        "entityClassVersion": 1,
7        "entityClassLevel": "SubKey",
8        "payload": { "name": "Retro Sneaker", "price": 79.99, "stock": 8 },
9        "createdAt": "2026-07-13T09:15:00.000Z",
10        "updatedAt": "2026-07-13T13:05:00.000Z",
11        "eTag": "WxYzAbCdEfGhIj"
12    }
13}

Other examples​

Combine patch operations, and guard the write with ifMatch​

A single updateEntity call can mix add, replace, remove, move, copy, and test operations in one operations list. All operations in the call apply together or not at all. Add ifMatch (the eTag from a prior read) to reject the patch with a 412 if the entity changed since you read it, instead of silently overwriting a concurrent change.

1

Remove entity​

Deletes a entity by entityId.

Method(s)​

1pubnub.dataSync.removeEntity(
2    entityId: String,
3    ifMatch: String? = null,
4): RemoveEntity
* required
ParameterDescription
entityId *
Type: String
Default:
n/a
Entity identifier.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The delete succeeds only if it still matches, otherwise the server returns 412.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200
3}

Relationships​

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

Create relationship​

Creates a relationship between two entities. The relationship class's cardinality (one-to-one, one-to-many, or many-to-many) is enforced on create. A relationship that violates its class's cardinality is rejected with a 409.

Method(s)​

1pubnub.dataSync.createRelationship(
2    entityAId: String,
3    entityBId: String,
4    className: String,
5    classVersion: Int,
6    relationshipId: String? = null,
7    status: String? = null,
8    payload: Any? = null,
9): CreateRelationship
* required
ParameterDescription
entityAId *
Type: String
Default:
n/a
Identifier of the first linked entity. Immutable after creation.
entityBId *
Type: String
Default:
n/a
Identifier of the second linked entity. Immutable after creation.
className *
Type: String
Default:
n/a
Name of the relationship class this instance belongs to. Set at creation and immutable afterward.
classVersion *
Type: Int
Default:
n/a
Version of the relationship class schema.
relationshipId
Type: String
Default:
server-generated
Relationship identifier. Omit to let the server generate a UUID. Max 255 characters.
status
Type: String
Default:
n/a
Free-form lifecycle status. Max 100 characters.
payload
Type: Any
Default:
n/a
Free-form JSON object holding your application data.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 201,
3    "data": {
4        "id": "rel-bob-owns-sneaker-42",
5        "entityAId": "seller-bob",
6        "entityBId": "product-sneaker-42",
7        "relationshipClass": "ProductOwner",
8        "relationshipClassVersion": 1,
9        "payload": { "since": "2026-07-13" },
10        "createdAt": "2026-07-13T09:20:00.000Z",
11        "updatedAt": "2026-07-13T09:20:00.000Z",
12        "eTag": "YzAbCdEfGhIjKl"
13    }
14}

Get relationship​

Returns a single relationship by relationshipId.

Method(s)​

1pubnub.dataSync.getRelationship(
2    relationshipId: String,
3): GetRelationship
* required
ParameterDescription
relationshipId *
Type: String
Default:
n/a
Relationship identifier.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "rel-bob-owns-sneaker-42",
5        "entityAId": "seller-bob",
6        "entityBId": "product-sneaker-42",
7        "relationshipClass": "ProductOwner",
8        "relationshipClassVersion": 1,
9        "payload": { "since": "2026-07-13" },
10        "createdAt": "2026-07-13T09:20:00.000Z",
11        "updatedAt": "2026-07-13T09:20:00.000Z",
12        "eTag": "YzAbCdEfGhIjKl"
13    }
14}

Get all relationships​

Returns a paginated list of relationships within a class. The className parameter is required. Filter by entityAId or entityBId to list a specific entity's links. For pagination, filtering, and sorting, refer to sorting and pagination.

Method(s)​

1pubnub.dataSync.getRelationships(
2    className: String,
3    entityAId: String? = null,
4    entityBId: String? = null,
5    classVersion: Int? = null,
6    filterFast: String? = null,
7    filter: String? = null,
8    sort: List<PNDataSyncSortField> = emptyList(),
9    limit: Int? = null,
10    cursor: String? = null,
11): GetRelationships
* required
ParameterDescription
className *
Type: String
Default:
n/a
Name of the relationship class to list.
entityAId
Type: String
Default:
n/a
List only relationships whose first entity is this id.
entityBId
Type: String
Default:
n/a
List only relationships whose second entity is this id.
classVersion
Type: Int
Default:
all versions
Relationship class version to list. Omit to list relationships across every version of the class.
filterFast
Type: String
Default:
n/a
Filter expression evaluated against strongly consistent storage, so it reflects the latest writes. Accepts up to 10 conditions by default (raisable per keyset), over properties declared with filtering mode simple or full. Cannot be combined with filter.
filter
Type: String
Default:
n/a
Filter expression evaluated against eventually consistent storage, so results can briefly lag writes. Supports the full expression language, over properties declared with filtering mode full. Cannot be combined with filterFast.
sort
Type: List<PNDataSyncSortField>
Default:
empty list
Order results. Each entry names a property and a direction.
limit
Type: Int
Default:
20
Maximum number of relationships per page. Max 100.
cursor
Type: String
Default:
n/a
Opaque pagination cursor. Omit for the first page.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": [
4        {
5            "id": "rel-bob-owns-sneaker-42",
6            "entityAId": "seller-bob",
7            "entityBId": "product-sneaker-42",
8            "relationshipClass": "ProductOwner",
9            "relationshipClassVersion": 1,
10            "payload": { "since": "2026-07-13" },
11            "createdAt": "2026-07-13T09:20:00.000Z",
12            "updatedAt": "2026-07-13T09:20:00.000Z",
13            "eTag": "YzAbCdEfGhIjKl"
14        }
15    ],
show all 21 lines

Other examples​

Pass entityBId instead of entityAId to list relationships where the entity is on the second side of the link.

1
Filter with filterFast​

filterFast is evaluated against strongly consistent storage, so it matches an object you just wrote. It runs over properties declared with filtering mode simple or full and accepts up to 10 conditions by default (raisable per keyset). Reference a declared property by its name, not its path. It shares the same expression language as filter, so only one of the two can be sent per call.

1
Filter with filter​

filter runs over properties declared with filtering mode full and is evaluated against eventually consistent storage, so a very recent write may not be matched yet. Reference a declared property by its name, not its path. It shares the same expression language as filterFast, so only one of the two can be sent per call.

1
Page through results with cursor​

Pass no cursor on the first call. Take next.cursor from the result and pass it back as cursor on the next call. Stop when next.hasNext is false.

1

Set relationship​

Replaces a relationship in full (PUT). Send the complete set of fields, any field you omit is cleared. className is immutable after creation and cannot be sent, and the linked entity ids are immutable too, so setRelationship doesn't expose entityAId/entityBId at all, there's nothing to resend. Refer to optimistic concurrency with ETags for ifMatch. For a partial update, use Update relationship.

Method(s)​

1pubnub.dataSync.setRelationship(
2    relationshipId: String,
3    classVersion: Int,
4    status: String? = null,
5    payload: Any? = null,
6    ifMatch: String? = null,
7): SetRelationship
* required
ParameterDescription
relationshipId *
Type: String
Default:
n/a
Relationship identifier.
classVersion *
Type: Int
Default:
n/a
Version of the relationship class schema.
status
Type: String
Default:
n/a
Free-form lifecycle status. Max 100 characters.
payload
Type: Any
Default:
n/a
Free-form JSON object holding your application data.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The update succeeds only if it still matches, otherwise the server returns 412.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "rel-bob-owns-sneaker-42",
5        "entityAId": "seller-bob",
6        "entityBId": "product-sneaker-42",
7        "relationshipClass": "ProductOwner",
8        "relationshipClassVersion": 1,
9        "payload": { "since": "2026-07-13", "tier": "gold" },
10        "createdAt": "2026-07-13T09:20:00.000Z",
11        "updatedAt": "2026-07-13T14:00:00.000Z",
12        "eTag": "AbCdEfGhIjKlMn"
13    }
14}

Update relationship​

Applies a partial update to a relationship with raw JSON Patch operations. Refer to partial update for the operation model.

Method(s)​

1pubnub.dataSync.updateRelationship(
2    relationshipId: String,
3    operations: List<PNJsonPatchOperation>,
4    ifMatch: String? = null,
5): UpdateRelationship
* required
ParameterDescription
relationshipId *
Type: String
Default:
n/a
Relationship identifier.
operations *
Type: List<PNJsonPatchOperation>
Default:
n/a
One or more JSON Patch operations. Must contain at least one item.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The patch succeeds only if it still matches, otherwise the server returns 412.

Use a JSON Pointer that starts with /payload/ to target payload fields, or a root pointer (for example /status) to target a top-level field.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200,
3    "data": {
4        "id": "rel-bob-owns-sneaker-42",
5        "entityAId": "seller-bob",
6        "entityBId": "product-sneaker-42",
7        "relationshipClass": "ProductOwner",
8        "relationshipClassVersion": 1,
9        "payload": { "since": "2026-07-13", "tier": "platinum" },
10        "createdAt": "2026-07-13T09:20:00.000Z",
11        "updatedAt": "2026-07-13T14:05:00.000Z",
12        "eTag": "CdEfGhIjKlMnOp"
13    }
14}

Remove relationship​

Deletes a relationship by relationshipId.

Method(s)​

1pubnub.dataSync.removeRelationship(
2    relationshipId: String,
3    ifMatch: String? = null,
4): RemoveRelationship
* required
ParameterDescription
relationshipId *
Type: String
Default:
n/a
Relationship identifier.
ifMatch
Type: String
Default:
n/a
The eTag from a prior read. The delete succeeds only if it still matches, otherwise the server returns 412.

Sample code​

Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
1

Response​

1{
2    "status": 200
3}

Real-time updates​

DataSync objects can publish create, update, and delete events that you receive in real time with a dataSync listener on a Subscription, a SubscriptionSet, or the PubNub client. Create a DataSync SDK entity for the object (DataSyncUser, DataSyncChannel, or DataSyncEntity), subscribe to it, and attach the listener, as described in Add DataSync listener.

1

Each event arrives as a PNDataSyncEventResult. Its extractedMessage names the object kind in type (user, channel, membership, entity, or relationship) and carries the object state in data. A create or update event is a PNSetDataSync*EventMessage whose event is CREATE or UPDATE. For a delete event, a PNDeleteDataSync*EventMessage carries only the id and the deletedAt timestamp.

type names the object kind directly, while the message class tells you which typed state container the event carries:

Change totypeOn create or updateOn delete
A useruserPNSetDataSyncUserEventMessage with PNDataSyncUserDataPNDeleteDataSyncUserEventMessage
A channelchannelPNSetDataSyncChannelEventMessage with PNDataSyncChannelDataPNDeleteDataSyncChannelEventMessage
An entityentityPNSetDataSyncEntityEventMessage with PNDataSyncEntityDataPNDeleteDataSyncEntityEventMessage
A membershipmembershipPNSetDataSyncMembershipEventMessage with PNDataSyncMembershipDataPNDeleteDataSyncMembershipEventMessage
A relationshiprelationshipPNSetDataSyncRelationshipEventMessage with PNDataSyncRelationshipDataPNDeleteDataSyncRelationshipEventMessage

Branch on the message class with a when expression, and always add an else branch, because an event the SDK does not recognize arrives as a PNUnknownDataSyncEventMessage that keeps the raw type, event, metadata, and data. className tells you the specific class within a kind, for example which subclass of User an event belongs to.

Where each event is delivered​

The channels that receive an event depend on the changed object. A relationship or membership never publishes on a channel named after its own id:

Change toOn createOn update or delete
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 membershipSame as create
A relationshipBoth the entityAId and the entityBId of the relationshipSame as create
Update and delete also fan out to connected objects

An update or delete on a user, channel, or entity is also delivered on the id channel of every other object connected to it by a relationship or membership, in either direction, at the time of the change. A client subscribed to a connected object's channel receives the event too, even though that object itself did not change. A create does not fan out this way, because nothing can be connected to a brand new object yet.

The connected channels are entity, user, and channel ids. Relationships and memberships never get an id channel of their own, so they never appear in this fan-out as a channel name.

So to see memberships appear and disappear for Alice, subscribe to user-alice rather than the membership id. A client subscribed to both sides of the same link receives the change twice, once per channel. Deduplicate create and update events on the object's id and updatedAt, and delete events on id and deletedAt.

For a membership event, PNDataSyncMembershipData carries channelId and userId directly, so you don't map them onto generic A and B sides. A relationship event carries entityAId and entityBId.

Projection channels​

Each projection declared on the class gets its own event, published to its own channel, and carrying only that projection's view of the payload:

ProjectionChannelPayload
__default__ (the base projection)The object's own id, for example product-sneaker-42The fields tagged __default__
Any named projection, for example admin__<projection>__<id>, for example __admin__product-sneaker-42The fields tagged with that projection

Filtering applies to payload and to status: each is included in a given projection's event only if the class declares it under that projection, falling back to __default__ when the class never declares status. id, eTag, createdAt, updatedAt, and expiresAt are never filtered. Every projection's event carries them unchanged.

So one change to an object whose class declares an admin projection publishes two events, and a client subscribed only to product-sneaker-42 never sees the admin-only fields:

1

If the class declares no properties at all there is nothing to filter, so a single unfiltered event is published to the object's own id channel.

Projection channels need channel grants

Publishing to __<projection>__<id> is an ordinary channel publish, and it isn't gated by the projection assignments in a token. Use Access Manager channel grants to control who can subscribe to a projection channel. Anyone who can subscribe there receives the restricted fields. Refer to Grant token.

Delete events are never filtered by a projection.

Events are off by default and are enabled per class in the Admin Portal. Refer to enabling events for how to turn them on, and receiving events for the listener flow.

Was this page useful?

Last updated on