pb-api-rules

# PocketBase API Rules & Filter Expressions ## Rule Types Each collection has 5 rule types. Each rule is a **filter expression** that must evaluate to `true` for the request to proceed. | Rule | Controls | Locked = | Empty string = | |------|----------|----------|----------------| | **List** | `GET /api/collections/{name}/records` | superusers only | everyone can list | | **View** | `GET /api/collections/{name}/records/{id}` | superusers only | everyone can view | | **Create** | `POST /api/collections/{name}/records` | superusers only | everyone can create | | **Update** | `PATCH /api/collections/{name}/records/{id}` | superusers only | everyone can update | | **Delete** | `DELETE /api/collections/{name}/records/{id}` | superusers only | everyone can delete | **Critical**: `null`/locked means only superusers can perform the action (regular users and guests are denied). Empty string `""` means EVERYONE including guests. Superusers always bypass API rules entirely — see below. ## Superuser Bypass Superusers (formerly admins) **always bypass API rules**. Rules only apply to regular auth records and guests. ## Filter Syntax ### Operators | Operator | Meaning | Example | |----------|---------|---------| | `=` | Equal | `status = "active"` | | `!=` | Not equal | `status != "draft"` | | `>` | Greater than | `count > 5` | | `>=` | Greater or equal | `count >= 5` | | `<` | Less than | `count < 10` | | `<=` | Less or equal | `count <= 10` | | `~` | LIKE (contains) | `title ~ "hello"` | | `!~` | NOT LIKE | `title !~ "spam"` | | `?=` | Any/has (array contains) | `tags ?= "TAG_ID"` | | `?!=` | None (array not contains) | `tags ?!= "TAG_ID"` | | `?>` | Any greater than | `scores ?> 90` | | `?>=` | Any greater or equal | `scores ?>= 90` | | `?<` | Any less than | `scores ?< 10` | | `?<=` | Any less or equal | `scores ?<= 10` | | `?~` | Any LIKE | `emails ?~ "@gmail.com"` | | `?!~` | Any NOT LIKE | `emails ?!~ "@test.com"` | **Critical**: use `?=` (not `=`) for multi-valued fields (multi-select, multi-relation, multi-file). `=` checks the raw JSON string, `?=` checks individual values. ### Logical Operators ``` status = "active" && author = @request.auth.id status = "active" || status = "featured" ``` Parentheses for grouping: `(a = 1 || b = 2) && c = 3` ### Values - Strings: `"value"` or `'value'` - Numbers: `123`, `45.67` - Booleans: `true`, `false` - `null` — empty/missing value - Identifiers: field names, macros ## Request Macros (`@request.*`) Access the current request context in rules: | Macro | Type | Description | |-------|------|-------------| | `@request.auth.id` | `string` | Current auth record ID (empty if guest) | | `@request.auth.email` | `string` | Current auth record email | | `@request.auth.verified` | `bool` | Whether email is verified | | `@request.auth.collectionId` | `string` | Auth collection ID | | `@request.auth.collectionName` | `string` | Auth collection name | | `@request.auth.*` | `any` | Any field from the auth record | | `@request.body.fieldName` | `any` | Field value from request body | | `@request.query.paramName` | `string` | URL query parameter | | `@request.headers.name` | `string` | Request header (lowercase key) | | `@request.method` | `string` | HTTP method (GET/POST/PATCH/DELETE) | ### Auth record relations You can traverse relations on the auth record: ``` @request.auth.team.owner = @request.auth.id ``` ## Collection Macros (`@collection.*`) Cross-collection lookups without explicit joins: ``` @collection.memberships.user ?= @request.auth.id && @collection.memberships.team ?= team ``` This checks if a record exists in the `memberships` collection where the user matches the current auth user and the team matches the current record's team field. **Note**: `@collection.*` performs an implicit EXISTS subquery. It's powerful but can be slow on large datasets — add indexes. ## Field Modifiers Use in create/update rules to validate specific field behaviors: | Modifier | Works on | Description | |----------|----------|-------------| | `:isset` | `@request.body.*` | True if the field was sent in the request (even if empty) | | `:changed` | record field | True if the field value differs from current stored value (update only) | | `:length` | `string`/`array` | Returns the length | | `:each` | `array` | Applies the condition to each element | | `:lower` | `string` | Lowercased value | ### Examples ``` // Only allow changing status if user is owner status:changed = false || author = @request.auth.id // Prevent setting role on create @request.body.role:isset = false // Require at least 2 tags @request.body.tags:length >= 2 // Check each tag is from allowed list @request.body.tags:each ?= @collection.allowed_tags.id ``` ## Datetime Macros | Macro | Example output | |-------|----------------| | `@now` | `2024-01-15 10:30:00.000Z` | | `@second` | `2024-01-15 10:30:00.000Z` | | `@minute` | `2024-01-15 10:30:00.000Z` | | `@hour` | `2024-01-15 10:00:00.000Z` | | `@day` | `2024-01-15 00:00:00.000Z` | | `@month` | `2024-01-01 00:00:00.000Z` | | `@year` | `2024-01-01 00:00:00.000Z` | | `@todayStart` | `2024-01-15 00:00:00.000Z` | | `@todayEnd` | `2024-01-15 23:59:59.999Z` | | `@monthStart` | `2024-01-01 00:00:00.000Z` | | `@monthEnd` | `2024-01-31 23:59:59.999Z` | | `@yearStart` | `2024-01-01 00:00:00.000Z` | | `@yearEnd` | `2024-12-31 23:59:59.999Z` | Arithmetic: `@now - 7d`, `@now + 1h`, `@now - 30m` ## `geoDistance()` For location-based filtering: ``` geoDistance(lat, lon, 40.7128, -74.0060) <= 10000 ``` Arguments: `geoDistance(latField, lonField, targetLat, targetLon)` — returns meters. ## Common Patterns ### Owner-only access ``` // View/Update/Delete rule: author = @request.auth.id ``` ### Authenticated users only ``` @request.auth.id != "" ``` ### Verified users only ``` @request.auth.verified = true ``` ### Role-based access ``` @request.auth.role = "admin" || author = @request.auth.id ``` ### Team membership ``` @collection.team_members.user ?= @request.auth.id && @collection.team_members.team ?= team ``` ### Public read, owner write ``` // List/View: "" (empty = everyone) // Create: @request.auth.id != "" // Update/Delete: author = @request.auth.id ``` ### Prevent field modification ``` // Update rule: prevent changing `owner` after creation owner:changed = false ``` ### Time-limited access ``` expires > @now ```