Glossary
A group of rows/documents, from one or more tables/collections.
Bucket / Bucket instance
Each bucket can be synced by any number of users, as a whole. The PowerSync protocol does not support syncing partial buckets (filtering inside buckets).
Each bucket is defined by its bucket definition name and set of parameter values. Together this forms its ID, for example by_user["user1","admin"].
Bucket Definition
This is the “Sync Rule” that describes buckets. Specifies the name, parameter query(ies), and data queries.
Each bucket definition describes a set of buckets using SQL-like queries.
Bucket Parameters
This is the set of parameters that uniquely identifies an individual bucket within a bucket definition. Together with the bucket name, this forms the bucket ID.
The bucket parameters are defined using one or more SQL-like queries in a bucket definition. These queries can return values directly from the user’s authentication token (token parameters), and/or select values from a table/collection.
Token Parameters
This is a set of parameters specified in the user’s authentication token (JWT). This always includes the token subject (the user_id), but may include additional and custom parameters.
Token parameters are used to identify the user, and specify permissions for the user.
These parameters are signed as part of the JWT generated on your app backend.
Client Parameters
In addition to token parameters, the client may add parameters to the sync request.
A client can pass any value, and sync data accordingly. Hence, client parameters should always be treated with care, and should not be used for access control purposes.
However, client parameters can be used to filter data for use cases such as:
- Syncing different buckets based on the client version (example).
- Syncing different buckets based on state in the client app, for example only synchronizing data for the customer currently selected.
Learn more here: Client Parameters
Global Buckets
Global buckets are buckets with no parameters.
If no parameter query is specified, the bucket is automatically a global bucket.
Parameter queries may still be used to filter buckets for an user, as long as it does not contain any output columns/fields.