> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powersync.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Organize Data Into Buckets

> Design Sync Rules to organize data into global and user-filtered buckets.

Designing your Sync Rules is about *organizing data into buckets*, and creating the bucket definitions accordingly. Each [bucket definition](/sync/rules/overview#bucket-definition) defines a set of tables/collections and rows/documents to sync.

* If there's some data you want to sync to *all* your users/clients, you can add bucket definitions for one or more [Global Buckets](/sync/rules/global-buckets). This is the simplest way to get started with PowerSync.
* If there's data that you want to filter by user, so that different users/clients get different subsets of data, you can add bucket definitions to your Sync Rules specifically for that purpose, using the `user_id` *Authentication Parameter* that comes from the JWT.
* You can also filter data based on other parameters, such as project, organization, etc. — using additional bucket definitions with those parameters.

When designing your buckets, it is recommended, but not required, to group all data in a bucket where the same parameters apply.

## Defining Buckets

Sync Rules take the form of a <Tooltip tip="For PowerSync Cloud, the YAML file is edited and deployed to a specific PowerSync instance in the PowerSync Dashboard. For self-hosting setups, the YAML is configured as part of your instance configuration.">YAML file</Tooltip> containing all your [bucket definitions](/sync/rules/overview#bucket-definition).

A *bucket definition* contains two sets of queries:

1. [Parameter Queries](/sync/rules/parameter-queries): Select bucket parameters

2. [Data Queries](/sync/rules/data-queries): Select data in the bucket using the bucket parameters

Here is an example of Sync Rules containing a single bucket definition, which will sync only the `lists` that belong to the user:

```yaml theme={null}
bucket_definitions:
  user_lists:
    # select parameters for the bucket - in this case we are just selecting the user_id
    parameters: SELECT request.user_id() as user_id # (request.user_id() comes from the JWT token)  
    data:
      # select data rows/documents using the parameters above
      - SELECT * FROM lists WHERE owner_id = bucket.user_id
```

<Note>
  You can choose any name for a bucket. The above Sync Rules contains only one bucket definition, with a bucket name of `user_lists`.
</Note>

<Note>
  **Note**: The table/collection names that your Data Queries select from in your Sync Rules must match the table names defined in your [client-side schema](/intro/setup-guide#define-your-client-side-schema).
</Note>

<Warning>
  The supported SQL in *Parameter Queries* and *Data Queries* is based on a small subset of the SQL standard syntax. Not all SQL constructs are supported. See [Supported SQL](/sync/supported-sql).
</Warning>

## Limit on Number of Buckets Per Client

There is a maximum cap on the number of buckets that each user/client can sync — [the default limit](/resources/performance-and-limits) is 1,000.

What this practically means is that the total number of <Tooltip tip="Global Buckets can also add to the number of buckets, but this usually has a neglible impact">results returned from all the **Parameter Queries**</Tooltip> across all your bucket definitions *for each specific user/client* cannot exceed that limit. If the Parameter Queries for a specific user/client exceed that limit, you will get a [`PSYNC_S2305` error](/debugging/error-codes#psync_s23xx:-sync-api-errors) from the PowerSync Service.

Note that this limit only applies to *each individual user/client*. You can have many more buckets in total in your project, as long as each user syncs no more total buckets than the limit. For example, your PowerSync Service instance could track let's say 1,000,000 buckets in total, but each user syncs a small fraction of those buckets.

<Note>This limit can be increased upon request for [Team and Enterprise](https://www.powersync.com/pricing) customers, however: as the number of buckets exceeds 1,000, performance degrades. See [Performance and Limits](/resources/performance-and-limits)</Note>