Query DataSync

Showing JavaScript examples.

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 token with get permission on the target resource type. Refer to Grant DataSync access if you don't have a token yet.

Before you start

• DataSync must be enabled on your keyset. Refer to Enable DataSync.
• The fields you want to filter on must be declared as class properties with the right filtering mode. Refer to Define an entity class.

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
• C#

1const response = await pubnub.dataSync.getEntities({
2    class: 'Product',
3    filterFast: 'price < 100',
4    sort: { price: 'desc' },
5    limit: 20,
6})
7console.log(response.data)
8console.log(response.meta)

Using the REST API directly:

1curl -G 'https://ps.pndsn.com/v1/datasync/subkeys/{subKey}/entities' \
2  --data-urlencode 'entity_class=Product' \
3  --data-urlencode 'filter_fast=price < 100' \
4  --data-urlencode 'sort=price:desc' \
5  --data-urlencode 'limit=20' \
6  --data-urlencode 'auth=<token>' \
7  --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, 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.

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

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.

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.

1curl -G 'https://ps.pndsn.com/v1/datasync/subkeys/{subKey}/entities' \
2  --data-urlencode 'entity_class=Product' \
3  --data-urlencode 'cursor=<next_cursor_value>' \
4  --data-urlencode 'limit=20' \
5  --data-urlencode 'auth=<token>' \
6  --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.

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

Refer to Get all entities (JavaScript), Get all entities (C#), and Get entities (REST) for the full parameter reference.