Skip to main content
version 1.0.0

ORM: Criterias

Introduction​

Criterias allow you to add constraints to all queries for a given model. Athenna's own soft delete functionality utilizes criterias to only retrieve "non-deleted" models from the database. Writing your own criterias can provide a convenient, easy way to make sure every query for a given model receives certain constraints.

Setting criterias in models​

Setting a criteria is very simple. You can do it by two ways, first by defining a Criteria in your model:

import { Model, Criteria } from '@athenna/database'

export class User extends Model {
  static get criterias() {
    return {
        myCriteriaName: Criteria.select('id', 'name').orderBy('name', 'DESC').get()
    }
  }

  /*...*/
}
warning

The get method in the final of the Criteria class is very important to "create" your criteria object. Remember always calling this method when using criterias in the static method criterias in your models.

The second way to define a criteria is calling the addCriteria method from your model:

User.addCriteria('myCriteriaName', Criteria.select('id', 'name').orderBy('name', 'DESC'))
tip

The addCriteria method will automatically recognize if you have called the get method or not. So when using addCriteria method you don't need to call the get method. But you can do so if you want:

User.addCriteria('myCriteriaName', Criteria.select('id', 'name').orderBy('name', 'DESC').get())

Removing criterias from model​

All the criterias add using the addCriteria method can be removed by using the removeCriteria method:

User.removeCriteria('myCriteriaName')
warning

The criterias that has been set in your static criterias method can only be removed using the removeCriteria from your model query builder. Check the documentation bellow to understand this behavior.

Removing criterias from model query builder​

As you can see, the criterias method from your model is static. This means that if you call addCriteria and removeCriteria it will change the state of your model globally in your application run time. To cover this behavior, the Athenna ModelQueryBuilder makes a copy of all the criterias in your model when you use the query method. So, if you call the removeCriteria of the model query builder, it will be removed only for that particular query builder instance and not globally from your models:

const user = await User.query()
        .removeCriteria('myCriteriaName')
        .where('name', 'Valmir Barbosa')
        .findMany()

You cannot add criterias again to your query at this point. So if you wish to "rollback" your criteria removal you will need to create a new query:

const user = await User.query()
        .where('name', 'Valmir Barbosa')
        .findMany()

Listing all available criterias​

You can list all the criterias available in you model using the getCriterias method. This method will merge both criterias set in static criterias method and criterias set using the addCriterias method:

const criterias = User.getCriterias()
tip

Always remember that basically any method (excluding the executors method like create) that are available in your models query builder (ModelQueryBuilder) can be used by your criterias.