Last Updated: 3/9/2026
Record operations
The most common task when extending PocketBase probably would be querying and working with your collection records.
You could find detailed documentation about all the supported Record model methods in core.Record type interface but below are some examples with the most common ones.
Set field value
// sets the value of a single record field// (field type specific modifiers are also supported). set("title", "example"). set("users+", "6jyr1y02438et52")// append to existing value// populates a record from a data map// (calls set() for each entry of the map). load()
Get field value
// retrieve a single record field value// (field specific modifiers are also supported). get("someField")// -> any (without cast). getBool("someField")// -> cast to bool. getString("someField")// -> cast to string. getInt("someField")// -> cast to int. getFloat("someField")// -> cast to float64. getDateTime("someField")// -> cast to types.DateTime. getStringSlice("someField")// -> cast to []string// retrieve the new uploaded files// (e.g. for inspecting and modifying the file(s) before save). getUnsavedFiles("someFileField")// unmarshal a single json field value into the provided result let = new DynamicModel({...}). unmarshalJSONField("someJsonField",)// retrieve a single or multiple expanded data. expandedOne("author")// -> as null|Record. expandedAll("categories")// -> as []Record// export all the public safe record fields in a plain object// (note: "json" type field values are exported as raw bytes array). publicExport()
Auth accessors
. isSuperuser()// alias for record.collection().name == "_superusers". email()// alias for record.get("email"). setEmail()// alias for record.set("email", email). verified()// alias for record.get("verified"). setVerified(false)// alias for record.set("verified", false). tokenKey()// alias for record.get("tokenKey"). setTokenKey()// alias for record.set("tokenKey", key). refreshTokenKey()// alias for record.set("tokenKey:autogenerate", ""). validatePassword(). setPassword()// alias for record.set("password", pass). setRandomPassword()// sets cryptographically random 30 characters string as password
Copies
// returns a shallow copy of the current record model populated// with its ORIGINAL db data state and everything else reset to the defaults// (usually used for comparing old and new field values). original()// returns a shallow copy of the current record model populated// with its LATEST data state and everything else reset to the defaults// (aka. no expand, no custom fields and with default visibility flags). fresh()// returns a shallow copy of the current record model populated// with its ALL collection and custom fields data, expand and visibility flags. clone()
Hide/Unhide fields
Collection fields can be marked as “Hidden” from the Dashboard to prevent regular user access to the field values.
Record models provide an option to further control the fields serialization visibility in addition to the “Hidden” fields option using the record.hide(fieldNames...) and record.unhide(fieldNames...) methods.
Often the hide/unhide methods are used in combination with the onRecordEnrich hook invoked on every record enriching (list, view, create, update, realtime change, etc.). For example:
onRecordEnrich((e) =>{// dynamically show/hide a record field depending on whether the current// authenticated user has a certain "role" (or any other field constraint) if(!.. ||(!... isSuperuser() &&... get("role")!= "staff")){.. hide("someStaffOnlyField")}. next()}, "articles")
For custom fields, not part of the record collection schema, it is required to call explicitly record.withCustomData(true) to allow them in the public serialization.
Fetch records
Fetch single record
All single record retrieval methods throw an error if no record is found.
// retrieve a single "articles" record by its id let =. findRecordById("articles", "RECORD_ID")// retrieve a single "articles" record by a single key-value pair let =. findFirstRecordByData("articles", "slug", "test")// retrieve a single "articles" record by a string filter expression// (NB! use "{:placeholder}" to safely bind untrusted user input parameters) let =. findFirstRecordByFilter("articles","status = 'public' && category = {:category}",{"category": "news"},)
Fetch multiple records
All multiple records retrieval methods return an empty array if no records are found.
// retrieve multiple "articles" records by their ids let =. findRecordsByIds("articles",["RECORD_ID1", "RECORD_ID2"])// retrieve the total number of "articles" records in a collection with optional dbx expressions let =. countRecords("articles",. hashExp({"status": "pending"}))// retrieve multiple "articles" records with optional dbx expressions let =. findAllRecords("articles",. exp("LOWER(username) = {:username}",{"username":"John.Doe"}),. hashExp({"status": "pending"}),)// retrieve multiple paginated "articles" records by a string filter expression// (NB! use "{:placeholder}" to safely bind untrusted user input parameters) let =. findRecordsByFilter("articles",// collection"status = 'public' && category = {:category}",// filter"-published",// sort 10,// limit 0,// offset{"category": "news"},// optional filter params)
Fetch auth records
// retrieve a single auth record by its email let =. findAuthRecordByEmail("users","test@example.com")// retrieve a single auth record by JWT// (you could also specify an optional list of accepted token types) let =. findAuthRecordByToken("YOUR_TOKEN", "auth")
Custom record query
In addition to the above query helpers, you can also create custom Record queries using $app.recordQuery(collection) method. It returns a SELECT DB builder that can be used with the same methods described in the Database guide.
function findTopArticle(){let = new Record();. recordQuery("articles"). andWhere(. hashExp({"status": "active"})). orderBy("rank ASC"). limit(1). one() return} let = findTopArticle()
For retrieving multiple Record models with the all() executor, you can use arrayOf(new Record) to create an array placeholder in which to populate the resolved DB result.
// the below is identical to// $app.findRecordsByFilter("articles", "status = 'active'", '-published', 10)// but allows more advanced use cases and filtering (aggregations, subqueries, etc.) function findLatestArticles(){let = arrayOf(new Record);. recordQuery("articles"). andWhere(. hashExp({"status": "active"})). orderBy("published DESC"). limit(10). all() return} let = findLatestArticles()
Create new record
Create new record programmatically
let =. findCollectionByNameOrId("articles") let = new Record(). set("title", "Lorem ipsum"). set("active", true)// field type specific modifiers can also be used. set("slug:autogenerate","post-")// new files must be one or a slice of filesystem.File values//// note1: see all factories in /jsvm/modules/_filesystem.html// note2: for reading files from a request event you can also use e.findUploadedFiles("fileKey") let =. fileFromPath("/local/path/to/file1.txt") let =. fileFromBytes("test content","file2.txt") let =. fileFromURL("https://example.com/file3.pdf"). set("documents",[,,])// validate and persist// (use saveNoValidate to skip fields validation). save();
Intercept create request
onRecordCreateRequest((e) =>{// ignore for superusers if(. hasSuperuserAuth()){return. next()}// overwrite the submitted "status" field value.. set("status", "pending")// or you can also prevent the create event by returning an error let =.. get("status") if(!= "pending" &&// guest or not an editor(!. ||.. get("role")!= "editor")){throw new BadRequestError("Only editors can set a status different from pending")}. next()}, "articles")
Update existing record
Update existing record programmatically
let =. findRecordById("articles", "RECORD_ID"). set("title", "Lorem ipsum")// delete existing record files by specifying their file names. set("documents-",["file1_abc123.txt","file3_abc123.txt"])// append one or more new files to the already uploaded list//// note1: see all factories in /jsvm/modules/_filesystem.html// note2: for reading files from a request event you can also use e.findUploadedFiles("fileKey") let =. fileFromPath("/local/path/to/file1.txt") let =. fileFromBytes("test content","file2.txt") let =. fileFromURL("https://example.com/file3.pdf"). set("documents+",[,,])// validate and persist// (use saveNoValidate to skip fields validation). save();
Intercept update request
onRecordUpdateRequest((e) =>{// ignore for superusers if(. hasSuperuserAuth()){return. next()}// overwrite the submitted "status" field value.. set("status", "pending")// or you can also prevent the update event by returning an error let =.. get("status") if(!= "pending" &&// guest or not an editor(!. ||.. get("role")!= "editor")){throw new BadRequestError("Only editors can set a status different from pending")}. next()}, "articles")
Delete record
let =. findRecordById("articles", "RECORD_ID"). delete()
Transaction
To execute multiple queries in a transaction you can use $app.runInTransaction(fn) .
The DB operations are persisted only if the transaction completes without throwing an error.
It is safe to nest runInTransaction calls as long as you use the callback’s txApp argument.
Inside the transaction function always use its txApp argument and not the original $app instance because we allow only a single writer/transaction at a time and it could result in a deadlock.
To avoid performance issues, try to minimize slow/long running tasks such as sending emails, connecting to external services, etc. as part of the transaction.
let =["title1", "title2", "title3"] let =. findCollectionByNameOrId("articles"). runInTransaction((txApp) =>{// create new record for each title for(let of){let = new Record(). set("title",). save()}})
Programmatically expanding relations
To expand record relations programmatically you can use $app.expandRecord(record, expands, customFetchFunc) for single or $app.expandRecords(records, expands, customFetchFunc) for multiple records.
Once loaded, you can access the expanded relations via record.expandedOne(relName) or record.expandedAll(relName) methods.
For example:
let =. findFirstRecordByData("articles", "slug","lorem-ipsum")// expand the "author" and "categories" relations. expandRecord(,["author", "categories"], null)// print the expanded records. log(. expandedOne("author")). log(. expandedAll("categories"))
Check if record can be accessed
To check whether a custom client request or user can access a single record, you can use the $app.canAccessRecord(record, requestInfo, rule) method.
Below is an example of creating a custom route to retrieve a single article and checking if the request satisfy the View API rule of the record collection:
routerAdd("GET","/articles/{slug}",(e) =>{let =.. pathValue("slug") let =.. findFirstRecordByData("articles", "slug",) let =.. canAccessRecord(,. requestInfo(),. collection().) if(!){throw new ForbiddenError()} return. json(200,)})
Generating and validating tokens
PocketBase Web APIs are fully stateless (aka. there are no sessions in the traditional sense) and an auth record is considered authenticated if the submitted request contains a valid Authorization: TOKEN header (see also Builtin auth middlewares and Retrieving the current auth state from a route ) .
If you want to issue and verify manually a record JWT (auth, verification, password reset, etc.), you could do that using the record token type specific methods:
let =. newAuthToken() let =. newVerificationToken() let =. newPasswordResetToken() let =. newEmailChangeToken() let =. newFileToken()// for protected files let =. newStaticAuthToken()// nonrenewable auth token
Each token type has its own secret and the token duration is managed via its type related collection auth option (the only exception is newStaticAuthToken).
To validate a record token you can use the $app.findAuthRecordByToken method. The token related auth record is returned only if the token is not expired and its signature is valid.
Here is an example how to validate an auth token:
let =. findAuthRecordByToken("YOUR_TOKEN", "auth")