微信扫一扫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