---
source_url: https://www.pubnub.com/docs/sdks/java/entities/data-sync-entity
title: DataSyncEntity SDK entity
updated_at: 2026-10-08T04:47:34.000Z
sdk_name: PubNub Java SDK
sdk_version: 14.0.0
---

# DataSyncEntity SDK entity

PubNub Java SDK, use the latest version: 14.0.0

Install:

```bash
Add PubNub dependency to your build@14.0.0
```

> For AI agents: documentation index at https://www.pubnub.com/llms-full.txt

The `DataSyncEntity` SDK entity is a local client-side handle that subscribes to the real-time updates of a DataSync [entity](https://www.pubnub.com/docs/sdks/java/api-reference/data-sync.md#entities). It is the subscribe-side counterpart to the `pubnub.dataSync().*` read and write methods, and `subscription()` is the only API it exposes.

:::note SDK entity is not the same as a DataSync entity
An **SDK entity** is a local client-side handle. A **DataSync entity** is a stored server-side record, the source of truth for your application state, managed through the [DataSync API](https://www.pubnub.com/docs/sdks/java/api-reference/data-sync.md). Creating `DataSyncEntity` performs no network call and does not require a matching server-side record to exist.
:::

## Create a DataSyncEntity

Use this factory method to return a local `DataSyncEntity` SDK entity for a single DataSync entity.

```java
pubnub.dataSyncEntity(String id)
```

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| id | String | Yes |  | Identifier of the DataSync entity to create a subscription of. |

#### Sample code

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

```java
Subscription subscription = pubnub.dataSyncEntity("product-sneaker-42").subscription();
subscription.subscribe();
```

## Available operations

| Operation | Description |
| --- | --- |
| `subscription(options)` | Returns a local [subscription object](https://www.pubnub.com/docs/pub-sub/subscribe/subscriptions.md) for the DataSync entity's own data channel, `id`. The subscription delivers only the events that arrive on that channel. |
| `subscription(projection, options)` | Returns a subscription for a DataSync [projection](https://www.pubnub.com/docs/sdks/java/api-reference/access-manager.md#grant-token) of the DataSync entity. Pass `default` or `__default__` to observe the entity itself, the same as the first method. Any other name observes the projection on its own `__{projection}__{id}` channel. A blank name throws an `IllegalArgumentException`. |

Both methods accept the usual [SubscriptionOptions](https://www.pubnub.com/docs/sdks/java/api-reference/publish-and-subscribe.md#subscriptionoptions). The projection is chosen per subscription rather than per SDK entity, so one SDK entity can serve several projections at once. Each subscription is subscribed and unsubscribed independently. To receive the events, attach a DataSync listener, as described in [Add DataSync listener](https://www.pubnub.com/docs/sdks/java/api-reference/publish-and-subscribe.md#add-datasync-listener).

:::note Subscribing needs a channel read grant
A DataSync SDK entity subscribes to an ordinary channel, so an authorized client needs a `read` grant on that channel. The grants from `DataSyncGrant.user`, `DataSyncGrant.channel`, and `DataSyncGrant.entity` cover only the DataSync API methods, not subscribing. Use `DataSyncGrant.subscribe` or `DataSyncGrant.subscribePattern` to grant the subscribe. Refer to [Grant token](https://www.pubnub.com/docs/sdks/java/api-reference/access-manager.md#grant-token).
:::

:::warning Relationship and membership changes are not delivered on their own id
A relationship change is delivered on the data channels of the two entities it links (`entityAId` and `entityBId`), and a membership change on those of its `userId` and `channelId`. It is never published on a channel named after the relationship or membership id, so the Java SDK has no SDK entity for either. To watch memberships appear and disappear, observe the linked user and channel with `DataSyncUser` and `DataSyncChannel` instead. Refer to [Where each event is delivered](https://www.pubnub.com/docs/sdks/java/api-reference/data-sync.md#where-each-event-is-delivered).
:::

##### Observe a projection

A projection channel carries only the fields the named projection exposes. The code below subscribes to the `admin` projection of a DataSync entity.

```java
Subscription subscription = pubnub.dataSyncEntity("product-sneaker-42").subscription("admin");
subscription.subscribe();
```

Last updated at: 2026-10-08T04:47:34.000Z