Collections
Queries that return more than one model give you a collection. A collection is a real JavaScript array of models with a few extra methods for loading relations, re-querying, and serializing the whole set.
const posts = await Post.where('status', 'published').get()
const titles = posts.map(post => post.title)
const ids = posts.modelKeys()
await posts.load('author')
return posts.toJSON()Available methods
Every method is listed alphabetically below and described in the method reference. Standard array methods, such as map() and filter(), also work.
Collections are arrays
get(), all(), findMany(), createMany(), and the data of a paginated result all return collections. Because a collection is an Array, every array method works and keeps the model types:
const posts = await Post.all()
const featured = posts.filter(post => post.is_featured)
const first = posts[0]
const count = posts.length
for (const post of posts) {
console.log(post.title)
}Methods like filter() and map() return plain arrays, not collections. Call collection methods before you transform the array.
Getting primary keys
modelKeys() returns the primary key of every model:
const users = await User.where('active', true).get()
users.modelKeys()
// [1, 4, 9]Querying the same records again
toQuery() builds a model query limited to the records in the collection. Use it to run a bulk update or a fresh query on exactly that set:
const drafts = await Post.where('status', 'draft').get()
await drafts.toQuery().update({ status: 'archived' })toQuery() throws on an empty collection, so check length first if the collection might be empty.
The query keeps the model's named scopes, so drafts.toQuery().published() type-checks when Post defines a published scope.
Reloading from the database
fresh() reloads every model and returns a new collection. Records deleted in the meantime are left out:
const latest = await posts.fresh()Loading relations
Load relations for every model in one query per relation. This avoids running a query per model:
const posts = await Post.all()
await posts.load('author', 'comments')
await posts.loadMissing('author')load() always queries. loadMissing() skips relations that are already loaded. Both return the collection with the loaded relations typed.
For morphTo relations, loadMorph() loads different nested relations depending on the related model. The keys are the stored morph types:
await comments.loadMorph('commentable', {
Post: 'author',
Video: ['channel', 'tags'],
})Loading aggregates
Add relation counts and sums to every model without loading the related rows:
const users = await User.all()
await users.loadCount('posts')
await users.loadExists('posts')
await users.loadSum('orders', 'total')
await users.loadAvg('orders', 'total')
await users.loadMin('orders', 'total')
await users.loadMax('orders', 'total')
users.toJSON()
// [{ id: 1, name: 'Amina', posts_count: 3, posts_exists: true, orders_sum_total: 240, ... }]| Method | Attribute name |
|---|---|
loadCount('posts') | posts_count |
loadExists('posts') | posts_exists |
loadSum('orders', 'total') | orders_sum_total |
loadAvg('orders', 'total') | orders_avg_total |
loadMin('orders', 'total') | orders_min_total |
loadMax('orders', 'total') | orders_max_total |
The column argument autocompletes from the related model's columns. To add aggregates while querying, use withCount() and friends from eager loading and aggregates.
Serializing a collection
toJSON() serializes each model, respecting its hidden, visible, and appended settings:
return users.toJSON()Change visibility for every model in the collection at once:
users.makeHidden('email').toJSON()
users.makeVisible('phone').toJSON()
users.setVisible(['id', 'name']).toJSON()
users.setHidden(['password']).toJSON()
users.append('display_name').toJSON()
users.withoutAppends().toJSON()See serialization for how each option works.
Method reference
append()
Adds computed attributes to the JSON output of every model. Repeated keys are added once.
users.append('display_name').toJSON()fresh()
Reloads every model from the database and returns a new collection. Models whose row was deleted are left out.
const current = await users.fresh()load()
Eager loads relations on every model in the collection, even ones already loaded. Use loadMissing() to skip the loaded ones.
await posts.load('author', 'tags')loadAvg()
Adds a {relation}_avg_{column} attribute to each model with the average of a related column.
await authors.loadAvg('books', 'rating')
// authors[0].books_avg_ratingloadCount()
Adds a {relation}_count attribute to each model.
await authors.loadCount('books')
// authors[0].books_countloadExists()
Adds a {relation}_exists boolean to each model. It's true when at least one related row exists.
await authors.loadExists('books')
// authors[0].books_existsloadMax()
Adds a {relation}_max_{column} attribute to each model with the largest related value.
await authors.loadMax('books', 'pages')loadMin()
Adds a {relation}_min_{column} attribute to each model with the smallest related value.
await authors.loadMin('books', 'pages')loadMissing()
Eager loads only the relations that aren't loaded on the models yet.
await posts.loadMissing('author')loadMorph()
Loads nested relations for a morphTo relation, with a different set per parent type. Keys are model names or morph class values. Each value is a relation name, an array of names, or an object of constraint callbacks.
await images.loadMorph('imageable', {
User: ['profile', 'posts'],
Post: 'comments',
})loadSum()
Adds a {relation}_sum_{column} attribute to each model with the total of a related column.
await authors.loadSum('books', 'pages')
// authors[0].books_sum_pagesmakeHidden()
Hides the given keys on every model in the collection, in addition to their current hidden keys.
users.makeHidden('email').toJSON()makeVisible()
Shows the given hidden keys on every model in the collection.
users.makeVisible('phone').toJSON()modelKeys()
Returns the primary key of every model, in collection order.
const ids = users.modelKeys()
// [1, 4, 9]setHidden()
Replaces the hidden keys on every model with the list you pass.
users.setHidden(['password']).toJSON()setVisible()
Shows only the listed keys on every model.
users.setVisible(['id', 'name']).toJSON()toJSON()
Returns an array of serialized models, respecting each model's hidden, visible, and appended settings.
return users.toJSON()toQuery()
Builds a model query limited to the primary keys in the collection. It throws on an empty collection.
await drafts.toQuery().update({ status: 'archived' })withoutAppends()
Removes the appended attributes from every model in the collection.
users.withoutAppends().toJSON()