Parameter queries allow parameters to be defined on a bucket to group data. These queries can use parameters from the JWT (we loosely refer to these as token parameters), such as a user_id
, or parameters from clients directly.
Available functions in sync rules are:
request.user_id()
: Returns the JWT subject, same as request.jwt() ->> 'sub'
request.jwt()
: Returns the entire (signed) JWT payload as a JSON string.
request.parameters()
: Returns client parameters as a JSON string.
Example usage:
A previous syntax for parameter queries used token_parameters
. Expand the below for details on how to migrate to the recommended syntax above.
Previous Syntax
The previous syntax for parameter queries used token_parameters.user_id
to return the JWT subject. Example:
The new functions available in sync rules are:
request.jwt()
: Returns the entire (signed) JWT payload as a JSON string.
request.parameters()
: Returns client parameters as a JSON string.
request.user_id()
: Returns the token subject, same as request.jwt() ->> 'sub'
and also the same as token_parameters.user_id
in the previous syntax.
The major difference from the previous token_parameters
is that all payloads are preserved as-is, which can make usage a little more intuitive. This also includes JWT payload fields that were not previously accessible.
Migrating to the new syntax:
token_parameters.user_id
references can simply be updated to request.user_id()
Custom parameters can be updated from token_parameters.my_custom_field
to request.jwt() ->> 'parameters.my_custom_field'
This example applies if you keep your existing custom JWT as is.
Supabase users can now make use of Supabase’s standard JWT structure and reference app_metadata.my_custom_field
directly.
Example:
In this example, a single query can return multiple sets of bucket parameters for a single user.
Keep in mind that the total number of buckets per user should remain limited (< 1,000), so don’t make buckets too granular.
Parameter queries may return multiple bucket parameters.
Note that every bucket parameter must be used in every data query.
Multiple parameter queries can be used in the same bucket definition.
It is important in this case that the output columns are exactly the same for each query in the bucket definition, as these define the bucket parameters.
Keep in mind that the total number of buckets per user should remain limited (< 1,000), so don’t make buckets too granular.
It is possible to pass parameters from clients directly. See client parameters to learn more.
Global buckets are buckets with no bucket parameters. This means there is a single bucket for the bucket definition.
When no parameter query is specified, it is automatically a global bucket.
Alternatively, a parameter query with no output columns may be specified to only sync the bucket to a subset of users.
Parameter queries are not run directly on a database. Instead, the queries are used to pre-process rows/documents as they are replicated, and index them for efficient use in the sync process.
The supported SQL is based on a small subset of the SQL standard syntax.
Notable features and restrictions:
Only simple SELECT
statements are supported.
No JOIN
, GROUP BY
or other aggregation, ORDER BY
, LIMIT
, or subqueries are supported.
For token parameters, only =
operators are supported, and IN
to a limited extent.
A limited set of operators and functions are supported — see Operators and Functions.
Parameter queries allow parameters to be defined on a bucket to group data. These queries can use parameters from the JWT (we loosely refer to these as token parameters), such as a user_id
, or parameters from clients directly.
Available functions in sync rules are:
request.user_id()
: Returns the JWT subject, same as request.jwt() ->> 'sub'
request.jwt()
: Returns the entire (signed) JWT payload as a JSON string.
request.parameters()
: Returns client parameters as a JSON string.
Example usage:
A previous syntax for parameter queries used token_parameters
. Expand the below for details on how to migrate to the recommended syntax above.
Previous Syntax
The previous syntax for parameter queries used token_parameters.user_id
to return the JWT subject. Example:
The new functions available in sync rules are:
request.jwt()
: Returns the entire (signed) JWT payload as a JSON string.
request.parameters()
: Returns client parameters as a JSON string.
request.user_id()
: Returns the token subject, same as request.jwt() ->> 'sub'
and also the same as token_parameters.user_id
in the previous syntax.
The major difference from the previous token_parameters
is that all payloads are preserved as-is, which can make usage a little more intuitive. This also includes JWT payload fields that were not previously accessible.
Migrating to the new syntax:
token_parameters.user_id
references can simply be updated to request.user_id()
Custom parameters can be updated from token_parameters.my_custom_field
to request.jwt() ->> 'parameters.my_custom_field'
This example applies if you keep your existing custom JWT as is.
Supabase users can now make use of Supabase’s standard JWT structure and reference app_metadata.my_custom_field
directly.
Example:
In this example, a single query can return multiple sets of bucket parameters for a single user.
Keep in mind that the total number of buckets per user should remain limited (< 1,000), so don’t make buckets too granular.
Parameter queries may return multiple bucket parameters.
Note that every bucket parameter must be used in every data query.
Multiple parameter queries can be used in the same bucket definition.
It is important in this case that the output columns are exactly the same for each query in the bucket definition, as these define the bucket parameters.
Keep in mind that the total number of buckets per user should remain limited (< 1,000), so don’t make buckets too granular.
It is possible to pass parameters from clients directly. See client parameters to learn more.
Global buckets are buckets with no bucket parameters. This means there is a single bucket for the bucket definition.
When no parameter query is specified, it is automatically a global bucket.
Alternatively, a parameter query with no output columns may be specified to only sync the bucket to a subset of users.
Parameter queries are not run directly on a database. Instead, the queries are used to pre-process rows/documents as they are replicated, and index them for efficient use in the sync process.
The supported SQL is based on a small subset of the SQL standard syntax.
Notable features and restrictions:
Only simple SELECT
statements are supported.
No JOIN
, GROUP BY
or other aggregation, ORDER BY
, LIMIT
, or subqueries are supported.
For token parameters, only =
operators are supported, and IN
to a limited extent.
A limited set of operators and functions are supported — see Operators and Functions.