Query Scopes

Table of contents

Query scopes help you extract fragments of an SQL query to their own methods. They are usually helpful in moving complex SQL queries behind

Creating a query scope

Query scopes are defined as static functions on the model itself. For example:

import { DateTime } from 'luxon'
import {
  scope // 👈 import scope
} from '@ioc:Adonis/Lucid/Orm'

export default class Post extends BaseModel {

  public static published = scope((query) => {    query.where('publishedOn', '<=', DateTime.utc().toSQLDate())  })

Now, you can use it as follows:

Post.query().apply((scopes) => scopes.published())

The query scopes can also accept arguments. For example: Creating a scope that accepts a user object to scope the projects they can view.

import { DateTime } from 'luxon'
import User from 'App/Models/User'
import { BaseModel, column, scope } from '@ioc:Adonis/Lucid/Orm'

export default class Project extends BaseModel {

  public static visibleTo = scope((query, user: User) => {
    if (user.isAdmin) {

     * Non-admin users can only view their own team's projects
    query.where('teamId', user.teamId)


You can use above defined scope as follows:

Project.query().apply((scopes) => scopes.visibleTo(auth.user))

On this page

Table of contents