---
source_url: https://www.pubnub.com/docs/data-storage/structured-data/query-structured-data
title: Query DataSync
updated_at: 2026-09-30T07:20:08.000Z
---

# Query DataSync

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

This guide shows you how to list and filter DataSync objects using the `filter_fast` and `filter` query parameters. Both require a valid [Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md) token with `get` permission on the target resource type. Refer to [Grant DataSync access](https://www.pubnub.com/docs/data-storage/structured-data/grant-structured-data-access.md) if you don't have a token yet.

## Before you start

* DataSync must be enabled on your keyset. Refer to [Enable DataSync](https://www.pubnub.com/docs/data-storage/structured-data/enable-structured-data.md).
* The fields you want to filter on must be declared as class properties with the right filtering mode. Refer to [Define an entity class](https://www.pubnub.com/docs/data-storage/structured-data/define-entity-class.md).

## Required and optional list parameters

Listing generic entities requires the `entity_class` query parameter. Listing generic relationships requires `relationship_class`. Omitting the required parameter is rejected with a `400`. User, channel, and membership lists have no required class parameter.

Two additional optional parameters apply when listing generic entities or relationships:

| Parameter | Applies to | What it does |
| --- | --- | --- |
| `entity_class_level` | Entity lists | Pass `Global` or `SubKey` to disambiguate when a Global class and a SubKey (keyset-level) class share the same name. Omit it and the SubKey class takes precedence. |
| `entity_class_version` | Entity lists | Restricts results to instances of a specific class version. Omit it to list instances across all versions of the class. |
| `relationship_class_version` | Relationship lists | Restricts results to instances of a specific relationship class version. Omit it to list instances across all versions. |

## Choose a filtering tier

DataSync offers two mutually exclusive filtering parameters. Supplying both is rejected with a `400`.

| Parameter | Consistency | Eligible properties |
| --- | --- | --- |
| `filter_fast` | Strongly consistent | Declared with `filtering: simple` or `filtering: full` |
| `filter` | Eventually consistent | Declared with `filtering: full` only |

If you need a result that immediately reflects a completed write, use `filter_fast`. If you need broader search-like pattern matching across a larger data set, use `filter` and tolerate a brief lag.

The four built-in fields (`id`, `createdAt`, `updatedAt`, `status`) are filterable and sortable in both tiers without being declared on the class.

## Filter with filter_fast (strongly consistent)

### JavaScript

```javascript
const response = await pubnub.dataSync.getEntities({
    class: 'Product',
    filterFast: 'price < 100',
    sort: { price: 'desc' },
    limit: 20,
})
console.log(response.data)
console.log(response.meta)
```

### C#

```csharp
PNResult<PNDataSyncEntitiesListResult> response = await pubnub.DataSync.GetEntities(new GetEntitiesParameters
{
    EntityClass = "Product",
    FilterFast = "price < 100",
    Sort = "price:desc",
    Limit = 20,
});
```

Using the REST API directly:

```bash
curl -G 'https://ps.pndsn.com/v1/datasync/subkeys/{subKey}/entities' \
  --data-urlencode 'entity_class=Product' \
  --data-urlencode 'filter_fast=price < 100' \
  --data-urlencode 'sort=price:desc' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'auth=<token>' \
  --data-urlencode 'uuid=user-alice'
```

Set `uuid` to the user ID the token was granted to. If `uuid` doesn't match the token's authorized user ID, Access Manager rejects the request with a `403`. The SDKs send `uuid` for you.

The token's projection shapes each result. With Alice's token from [Grant DataSync access](https://www.pubnub.com/docs/data-storage/structured-data/grant-structured-data-access.md#grant-a-shopper-read-access), products come back through the `public` projection, with `name` and `price` but without `stock`.

## Filter with filter (eventually consistent)

Use `filter` the same way as `filter_fast`, substituting the parameter name. Only properties declared with `filtering: full` are eligible.

```bash
curl -G 'https://ps.pndsn.com/v1/datasync/subkeys/{subKey}/entities' \
  --data-urlencode 'entity_class=Product' \
  --data-urlencode 'filter=name LIKE "Retro*"' \
  --data-urlencode 'sort=name:desc' \
  --data-urlencode 'auth=<token>' \
  --data-urlencode 'uuid=user-alice'
```

:::note LIKE is case-insensitive here
Unlike SQL, DataSync's `LIKE` ignores case. Use `SLIKE` when you need a case-sensitive match. The wildcard character is `*`, not `%`.
:::

## Filter expression syntax

Filter expressions support:

* Comparison operators: `==`, `!=`, `<`, `>`, `<=`, `>=`
* Pattern operators: `LIKE` (case-insensitive), `SLIKE` (case-sensitive)
* Logical operators: `&&`, `||`, `!`, and parentheses for grouping
* Values: strings in single or double quotes, numbers, `true`, `false`, or `null`

You always filter on a property's `name`, not its JSON Pointer `path`. Compare `date` and `datetime` properties against a quoted ISO-8601 string.

The default limit is 10 predicates per expression for `filter_fast`. Exceeding the limit returns a `400`.

## Sort results

Add a `sort` parameter: a comma-separated list of property names, each optionally followed by `:desc`.

```text
sort=price:desc
sort=name,price:desc
```

A property with no suffix sorts ascending. `:desc` and `:descending` are case-insensitive. `:asc` is not a recognized suffix; omit it to sort ascending.

If you combine `filter` (eventually consistent) with a sort, the sorted properties must have `filtering: full`. A `simple` property sorts correctly under `filter_fast` but is rejected when combined with `filter`.

## Paginate results

List endpoints use cursor-based pagination. Page size ranges from 1 to 100, with a default of 20. Pagination is forward-only.

To page forward, pass the `next_cursor` from the previous response back as `cursor`, and stop when `has_next` is `false`.

```bash
curl -G 'https://ps.pndsn.com/v1/datasync/subkeys/{subKey}/entities' \
  --data-urlencode 'entity_class=Product' \
  --data-urlencode 'cursor=<next_cursor_value>' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'auth=<token>' \
  --data-urlencode 'uuid=user-alice'
```

## Filter memberships by user or channel

Membership lists can be narrowed by `user_id`, `channel_id`, or both. These narrow results on the strongly consistent tier only. Combining `user_id` or `channel_id` with `filter` ignores them.

```bash
curl -G 'https://ps.pndsn.com/v1/datasync/subkeys/{subKey}/memberships' \
  --data-urlencode 'user_id=user-alice' \
  --data-urlencode 'auth=<token>' \
  --data-urlencode 'uuid=user-alice'
```

Refer to [Get all entities (JavaScript)](https://www.pubnub.com/docs/sdks/javascript/api-reference/data-sync.md#get-all-entities), [Get all entities (C#)](https://www.pubnub.com/docs/sdks/c-sharp/api-reference/data-sync.md#get-all-entities), and [Get entities (REST)](https://www.pubnub.com/docs/sdks/rest-api/get-entities.md) for the full parameter reference.

Last updated at: 2026-09-30T07:20:08.000Z