# Static Methods

#`static` query()

const queryBuilder= Person.query(transactionOrKnex);

Creates a query builder for the model's table.

All query builders are created using this function, including$query,relatedQuery and$relatedQuery. That means you can modify each query by overriding this method for your model class.

See thequery examples section for more examples.

# Arguments

Argument	Type	Description
transactionOrKnex	object	Optional transaction or knex instance for the query. This can be used to specify a transaction or even a different database. for a query. Falsy values are ignored.

# Return value

Type	Description
QueryBuilder	The created query builder

# Examples

Read models from the database:

// Get all rows.const people=await Person.query();console.log('there are', people.length,'people in the database');// Example of a more complex WHERE clause. This generates:// SELECT "persons".*// FROM "persons"// WHERE ("firstName" = 'Jennifer' AND "age" < 30)// OR ("firstName" = 'Mark' AND "age" > 30)const marksAndJennifers=await Person.query().where(builder=>{    builder.where('firstName','Jennifer').where('age','<',30);}).orWhere(builder=>{    builder.where('firstName','Mark').where('age','>',30);});console.log(marksAndJennifers);// Get a subset of rows and fetch related models// for each row.const oldPeople=await Person.query().where('age','>',60).withGraphFetched('children.children.movies');console.log("some old person's grand child has appeared in",  oldPeople[0].children[0].children[0].movies.length,'movies');

Insert models to the database:

const sylvester=await Person.query().insert({firstName:'Sylvester',lastName:'Stallone'});console.log(sylvester.fullName());// --> 'Sylvester Stallone'.// Batch insert. This only works on Postgresql as it is// the only database that returns the identifiers of// _all_ inserted rows. If you need to do batch inserts// on other databases useknex* directly.// (See .knexQuery() method).const inserted=await Person.query().insert([{firstName:'Arnold',lastName:'Schwarzenegger'},{firstName:'Sylvester',lastName:'Stallone'}]);console.log(inserted[0].fullName());// --> 'Arnold Schwarzenegger'

update andpatch can be used to update models. Only difference between the mentioned methods is thatupdate validates the input objects using the model class's full jsonSchema andpatch ignores therequired property of the schema. Useupdate when you want to updateall properties of a model andpatch when only a subset should be updated.

const numUpdatedRows=await Person.query().update({firstName:'Jennifer',lastName:'Lawrence',age:35}).where('id', jennifer.id);console.log(numUpdatedRows);// This will throw assuming that `firstName` or `lastName`// is a required property for a Person.await Person.query().update({age:100});// This will _not_ throw.await Person.query().patch({age:100});console.log('Everyone is now 100 years old');

Models can be deleted using the delete method. Naturally the delete query can be chained with any knex* methods:

await Person.query().delete().where('age','>',90);console.log('anyone over 90 is now removed from the database');

#`static` relatedQuery()

const queryBuilder= Person.relatedQuery(relationName, transactionOrKnex);

Creates a query builder that can be used to query a relation of an item (or items).

This method is best explained through examples. See the examples below and the following sections:

# Arguments

Argument	Type	Description
relationName	string	The name of the relation to query.
transactionOrKnex	object	Optional transaction or knex instance for the query. This can be used to specify a transaction or even a different database for a query. Falsy values are ignored.

# Return value

Type	Description
QueryBuilder	The created query builder

# Examples

This example fetchespets for a person with id 1.pets is the name of the relation defined inrelationMappings.

const personId=1;const pets=await Person.relatedQuery('pets').for(personId);

select"animals".*from"animals"where"animals"."ownerId"=1

Just like to any query, you can chain any methods. The following example only fetches dogs and sorts them by name:

const dogs=await Person.relatedQuery('pets').for(1).where('species','dog').orderBy('name');

select"animals".*from"animals"where"species"='dog'and"animals"."ownerId"=1orderby"name"asc

If you want to fetch dogs of multiple people in one query, you can pass an array of identifiers to thefor method like this:

const dogs=await Person.relatedQuery('pets').for([1,2]).where('species','dog').orderBy('name');

select"animals".*from"animals"where"species"='dog'and"animals"."ownerId"in(1,2)orderby"name"asc

You can even give it a subquery! The following example fetches all dogs of all people named Jennifer.

// Note that there is no `await` here. This query does not get executed.const jennifers= Person.query().where('name','Jennifer');// This is the only executed query in this example.const allDogsOfAllJennifers=await Person.relatedQuery('pets').for(jennifers).where('species','dog').orderBy('name');

select"animals".*from"animals"where"species"='dog'and"animals"."ownerId"in(select"persons"."id"from"persons"where"name"='Jennifer')orderby"name"asc

relatedQuery also works withrelate ,unrelate,delete and all other query methods. The following example relates a person with id 100 to a movie with id 200 for the many-to-many relationmovies:

await Person.relatedQuery('movies').for(100).relate(200);

insertinto"persons_movies"("personId","movieId")values(100,200)

See more exampleshere.

relatedQuery can also be used as a subquery whenfor is omitted. The next example selects the count of a relation and the maximum value of another one:

const people=await Person.query().select(['persons.*',  Person.relatedQuery('pets').count().where('species','dog').as('dogCount'),  Person.relatedQuery('movies').max('createdAt').as('mostRecentMovieDate')]);console.log(people[0].id);console.log(people[0].dogCount);console.log(people[0].mostRecentMovieDate);

Find models that have at least one item in a relation:

const peopleThatHavePets=await Person.query().whereExists(  Person.relatedQuery('pets'));

Generates something like this:

select"persons".*from"persons"whereexists(select"pets".*from"animals"as"pets"where"pets"."ownerId"="persons"."id")

#`static` knex()

Get/Set the knex instance for a model class.

Subclasses inherit the connection. A system-wide knex instance can thus be set by callingobjection.Model.knex(knex). This works even after subclasses have been created.

If you want to use multiple databases, you can instead pass the knex instance to each individual query or use thebindKnex method.

# Examples

Set a knex instance:

const knex=require('knex')({client:'sqlite3',connection:{filename:'database.db'}});Model.knex(knex);

Get the knex instance:

const knex= Person.knex();

#`static` transaction()

const result=await Person.transaction(callback);const result=await Person.transaction(trxOrKnex, callback);

Shortcut forPerson.knex().transaction(callback).

See thetransaction guide.

# Arguments

Argument	Type	Description
callback	function
trxOrKnex	knex or Transation	Optional existing transaction or knex instance.

# Examples

try{const scrappy=await Person.transaction(asynctrx=>{const jennifer=await Person.query(trx).insert({firstName:'Jennifer',lastName:'Lawrence'});const scrappy=await jennifer.$relatedQuery('pets', trx).insert({name:'Scrappy'});return scrappy;});  console.log('Great success! Both Jennifer and Scrappy were inserted');}catch(err){  console.log('Something went wrong. Neither Jennifer nor Scrappy were inserted');}

#`static` startTransaction()

const trx=await Person.startTransaction(trxOrKnex);

Shortcut forobjection.transaction.start(Model1.knex()).

See thetransaction guide.

# Arguments

Argument	Type	Description
trxOrKnex	knex or Transation	Optional existing transaction or knex instance.

# Examples

const trx=await Person.startTransaction();try{await Person.query(trx).insert(person1);await Person.query(trx).insert(person2);await Person.query(trx).patch(person3).where('id', person3.id);await trx.commit();}catch(err){await trx.rollback();throw err;}

#`static` beforeFind()

classPersonextendsModel{staticbeforeFind(args){}}

A hook that is executed before find queries.

See these sections for more information:

# Arguments

Argument	Type	Description
args	StaticHookArguments	The arguments

# Return value

Type	Description
any	The return value is not used.

#`static` afterFind()

classPersonextendsModel{staticafterFind(args){}}

A hook that is executed after find queries.

See these sections for more information:

# Arguments

Argument	Type	Description
args	StaticHookArguments	The arguments

# Return value

Type	Description
any	If the return value is not`undefined`, it will be used as the return value of the query.

#`static` beforeUpdate()

classPersonextendsModel{staticbeforeUpdate(args){}}

A hook that is executed before update and patch queries.

See these sections for more information:

# Arguments

Argument	Type	Description
args	StaticHookArguments	The arguments

# Return value

Type	Description
any	The return value is not used.

#`static` afterUpdate()

classPersonextendsModel{staticafterUpdate(args){}}

A hook that is executed after update and patch queries.

See these sections for more information:

# Arguments

Argument	Type	Description
args	StaticHookArguments	The arguments

# Return value

Type	Description
any	If the return value is not`undefined`, it will be used as the return value of the query.

#`static` beforeInsert()

classPersonextendsModel{staticbeforeInsert(args){}}

A hook that is executed before insert queries.

See these sections for more information:

# Arguments

Argument	Type	Description
args	StaticHookArguments	The arguments

# Return value

Type	Description
any	The return value is not used.

#`static` afterInsert()

classPersonextendsModel{staticafterInsert(args){}}

A hook that is executed after insert queries.

See these sections for more information:

# Arguments

Argument	Type	Description
args	StaticHookArguments	The arguments

# Return value

Type	Description
any	If the return value is not`undefined`, it will be used as the return value of the query.

#`static` beforeDelete()

classPersonextendsModel{staticbeforeDelete(args){}}

A hook that is executed before delete queries.

See these sections for more information:

# Arguments

Argument	Type	Description
args	StaticHookArguments	The arguments

# Return value

Type	Description
any	The return value is not used.

#`static` afterDelete()

classPersonextendsModel{staticafterDelete(args){}}

A hook that is executed after delete queries.

See these sections for more information:

# Arguments

Argument	Type	Description
args	StaticHookArguments	The arguments

# Return value

Type	Description
any	If the return value is not`undefined`, it will be used as the return value of the query.

#`static` bindKnex()

const BoundPerson= Person.bindKnex(transactionOrKnex);

Creates an anonymous model subclass class that is bound to the given knex instance or transaction.

This method can be used to bind a Model subclass to multiple databases for example in a multi-tenant system. See themulti tenancy recipe for more info.

Also check out themodel binding pattern for transactions which internally usesbindKnex.

# Arguments

Argument	Type	Description
transactionOrKnex	object	knex instance or a transaction to bind the model to.

# Return value

Type	Description
Constructor<? extends Model>	The created model subclass constructor

# Examples

const knex1=require('knex')({client:'sqlite3',connection:{filename:'database1.db'}});const knex2=require('knex')({client:'sqlite3',connection:{filename:'database2.db'}});SomeModel.knex(null);const BoundModel1= SomeModel.bindKnex(knex1);const BoundModel2= SomeModel.bindKnex(knex2);// Throws since the knex instance is null.await SomeModel.query();// Works.const models=await BoundModel1.query();console.log(models[0]instanceofSomeModel);// --> trueconsole.log(models[0]instanceofBoundModel1);// --> true// Works.const models=await BoundModel2.query();console.log(models[0]instanceofSomeModel);// --> trueconsole.log(models[0]instanceofBoundModel2);// --> true

#`static` bindTransaction()

Alias forbindKnex.

# Examples

const{ transaction}=require('objection');const Person=require('./models/Person');awaittransaction(Person.knex(),asynctrx=>{const TransactingPerson= Person.bindTransaction(trx);await TransactingPerson.query().insert({firstName:'Jennifer'});return TransactingPerson.query().patch({lastName:'Lawrence'}).where('id', jennifer.id);});

This is 100% equivalent to the example above:

const{ transaction}=require('objection');const Person=require('./models/Person');awaittransaction(Person,asyncTransactingPerson=>{await TransactingPerson.query().insert({firstName:'Jennifer'});return TransactingPerson.query().patch({lastName:'Lawrence'}).where('id', jennifer.id);});

#`static` fromJson()

const person= Person.fromJson(json, opt);

Creates a model instance from a POJO (Plain Old Javascript Object).

The object is checked againstjsonSchema if a schema is provided and an exception is thrown on failure.

Thejson object is also passed through the$parseJson hook before the model instance is created. Seethis section for more info.

# Arguments

Argument	Type	Description
json	Object	The JSON object from which to create the model.
opt	ModelOptions	Update options.

# Return value

Type	Description
Model	The created model instance

# Examples

Create a model instance:

const jennifer= Person.fromJson({firstName:'Jennifer'});

Create a model instance skipping validation:

const jennifer= Person.fromJson({firstName:'Jennifer'},{skipValidation:true});

#`static` fromDatabaseJson()

const person= Person.fromDatabaseJson(row);

Creates a model instance from a JSON object send by the database driver.

UnlikefromJson, this method doesn't validate the input. The input is expected to be in the database format as explainedhere.

# Arguments

Argument	Type	Description
row	Object	A database row.

# Return value

Type	Description
Model	The created model instance

#`static` modifierNotFound()

classBaseModelextendsModel{staticmodifierNotFound(builder, modifier){const{ properties}=this.jsonSchema;if(properties&& modifierin properties){      builder.select(modifier);}else{super.modifierNotFound(builder, modifier);}}}

This method is called when an unknown modifier is used somewhere.

By default, the staticmodifierNotFound() hook throws aModifierNotFoundError error. If a model class overrides the hook, it can decide to handle the modifer through the passedbuilder instance, or call the hook's definition in the super class to still throw the error.

# Arguments

Argument	Type	Description
builder	QueryBuilder	The query builder on which to apply the modifier.
modifier	string	The name of the unknown modifier.

#`static` createValidator()

classBaseModelextendsModel{staticcreateValidator(){returnnewMyCustomValidator();}}

Creates an instance of aValidator that is used to do all validation related stuff. This method is called only once per model class.

You can override this method to return an instance of your custom validator. The custom validator doesn't need to be based on thejsonSchema. It can be anything at all as long as it implements theValidator interface.

If you want to use the default json schema basedAjvValidator but want to modify it, you can use theobjection.AjvValidator constructor. See the default implementation example.

If you want to share the same validator instance between multiple models, that's completely fine too. Simply implementcreateValidator so that it always returns the same object instead of creating a new one.

# Examples

Sharing the same validator between model classes is also possible:

const validator=newMyCustomValidator();classBaseModelextendsModel{staticcreateValidator(){return validator;}}

The default implementation:

const AjvValidator=require('objection').AjvValidator;classModel{staticcreateValidator(){returnnewAjvValidator({onCreateAjv:ajv=>{// Here you can modify the `Ajv` instance.},options:{allErrors:true,validateSchema:false,ownProperties:true,v5:true}});}}

#`static` createNotFoundError()

classBaseModelextendsModel{staticcreateNotFoundError(queryContext, props){returnnewMyCustomNotFoundError({...props,modelClass:this});}}

Creates an error thrown bythrowIfNotFound method. You can override thisto throw any error you want.

# Arguments

Argument	Type	Description
queryContext	Object	The context object of query that produced the empty result. Seecontext.
props	any	Data passed to the error class constructor.

# Return value

Type	Description
`Error`	The created error.NotFoundError by default.

# Examples

The default implementation:

classModel{staticcreateNotFoundError(queryContext, props){returnnewthis.NotFoundError({...props,modelClass:this});}}

#`static` createValidationError()

classBaseModelextendsModel{staticcreateValidationError({ type, message, data}){returnnewMyCustomValidationError({ type, message, data,modelClass:this});}}

Creates an error thrown when validation fails for a model. You can override this to throw any error you want. The errors created by this function don't have to implement any interface or have the same properties asValidationError. Objection only throws errors created by this function an never catches them.

# Return value

Type	Description
`Error`	The created error.ValidationError by default.

#`static` fetchGraph()

const queryBuilder= Person.fetchGraph(models, expression, options);

Load related models for a set of models using aRelationExpression.

# Arguments

Argument	Type	Description
models	Array<Model\|Object>	Model instances for which to fetch the relations. Can be an array of model instances, array of POJOs, a single model instance or a single POJO.
expression	string\|RelationExpression	The relation expression
options	FetchGraphOptions	Optional options.

# Return value

Type	Description
QueryBuilder	The created query builder

# Examples

const people=await Person.fetchGraph([person1, person2],'children.pets');const person1= people[0];const person2= people[1];

Relations can be filtered by giving modifier functions as arguments for the relations:

const people=await Person.fetchGraph([person1, person2],`    children(orderByAge).[      pets(onlyDogs, orderByName),      movies    ]`).modifiers({orderByAge(builder){    builder.orderBy('age');},orderByName(builder){    builder.orderBy('name');},onlyDogs(builder){    builder.where('species','dog');}});console.log(people[1].children.pets[0]);

#`static` traverseAsync()

Traverses the relation tree of a model instance (or a list of model instances).

Calls the callback for each related model recursively. The callback is called also for the input models themselves.

In the second example the traverser function is only called forPerson instances.

# Arguments

Argument	Type	Description
filterConstructor	function	If this optional constructor is given, the`traverser` is only called for models for which`model instanceof filterConstructor` returns true.
models	Model\|Model[]	The model(s) whose relation trees to traverse.
traverser	function(Model, string, string)	The traverser function that is called for each model. The first argument is the model itself. If the model is in a relation of some other model the second argument is the parent model and the third argument is the name of the relation.

# Examples

There are two ways to call this method:

const models=await SomeModel.query();await Model.traverseAsync(models,async(model, parentModel, relationName)=>{awaitdoSomething(model);});

and

const persons=await Person.query();Model.traverseAsync(  Person,  persons,async(person, parentModel, relationName)=>{awaitdoSomethingWithPerson(person);});

Also works with a single model instance

const person=await Person.query();await Person.traverseAsync(person,async(model, parentModel, relationName)=>{awaitdoSomething(model);});

#`static` getRelations()

const relations= Person.getRelations();

Returns aRelation object for each relation defined inrelationMappings.

This method is mainly useful for plugin developers and for other generic usages.

# Return value

Type	Description
Object<string, Relation>	Object whose keys are relation names and values areRelation instances.

#`static` columnNameToPropertyName()

const propertyName= Person.columnNameToPropertyName(columnName);

Runs the property through possiblecolumnNameMappers and$parseDatabaseJson hooks to apply any possible conversion for the column name.

# Arguments

Argument	Type	Description
columnName	string	A column name

# Return value

Type	Description
string	The property name

# Examples

If you have definedcolumnNameMappers = snakeCaseMappers() for your model:

const propName= Person.columnNameToPropertyName('foo_bar');console.log(propName);// --> 'fooBar'

#`static` propertyNameToColumnName()

const columnName= Person.propertyNameToColumnName(propertyName);

Runs the property through possiblecolumnNameMappers and$formatDatabaseJson hooks to apply any possible conversion for the property name.

# Arguments

Argument	Type	Description
propertyName	string	A property name

# Return value

Type	Description
string	The column name

# Examples

If you have definedcolumnNameMappers = snakeCaseMappers() for your model:

const columnName= Person.propertyNameToColumnName('fooBar');console.log(columnName);// --> 'foo_bar'

#`static` fetchTableMetadata()

const metadata=await Person.fetchTableMetadata(opt);

Fetches and caches the table metadata.

Most of the time objection doesn't need this metadata, but some methods likewithGraphJoined do. This method is called by objection when the metadata is needed. The result is cached and after the first call the cached promise is returned and no queries are executed.

Because objection uses this on demand, the first query that needs this information can have unpredicable performance. If that's a problem, you can call this method for each of your models during your app's startup.

If you've implementedtableMetadata method to return a custom metadata object, this method doesn't execute database queries, but returnsPromise.resolve(this.tableMetadata()) instead.

# Arguments

Argument	Type	Description
opt	TableMetadataFetchOptions	Optional options

# Return value

Type	Description
Promise<TableMetadata>	The table metadata object

#`static` tableMetadata()

const metadata= Person.tableMetadata(opt);

Synchronously returns the table metadata object from the cache.

You can override this method to return a custom object if you don't want objection to usefetchTableMetadata.

SeefetchTableMetadata for more information.

# Arguments

Argument	Type	Description
opt	TableMetadataOptions	Optional options

# Return value

Type	Description
TableMetadata	The table metadata object

# Examples

A custom override that uses the property information injsonSchema.

classPersonextendsModel{statictableMetadata(){return{columns: Object.keys(this.jsonSchema.properties)};}}

#`static` raw()

Shortcut forPerson.knex().raw(...args)

#`static` ref()

Returns aReferenceBuilder instance that is bound to the model class. Any reference created using it will add the correct table name to the reference.

const{ ref}= Person;await Person.query().where(ref('firstName'),'Jennifer');

select"persons".*from"persons"where"persons"."firstName"='Jennifer'

ref uses the correct table name even when an alias has been given to the table.

const{ ref}= Person;await Person.query().alias('p').where(ref('firstName'),'Jennifer');

select"p".*from"persons"as"p"where"p"."firstName"='Jennifer'

Note that the following two ways to useModel.ref are completely equivalent:

const{ ref}= Person;await Person.query().where(ref('firstName'),'Jennifer');

await Person.query().where(Person.ref('firstName'),'Jennifer');

#`static` fn()

Shortcut forPerson.knex().fn

#`static` knexQuery()

Shortcut forPerson.knex().table(Person.tableName)

← Static Properties Instance Methods →

Movatterモバイル変換

# Static Methods

#static query()

# Arguments

# Return value

# Examples

#static relatedQuery()

# Arguments

# Return value

# Examples

#static knex()

# Examples

#static transaction()

# Arguments

# Examples

#static startTransaction()

# Arguments

# Examples

#static beforeFind()

# Arguments

# Return value

#static afterFind()

# Arguments

# Return value

#static beforeUpdate()

# Arguments

# Return value

#static afterUpdate()

# Arguments

# Return value

#static beforeInsert()

# Arguments

# Return value

#static afterInsert()

# Arguments

# Return value

#static beforeDelete()

# Arguments

# Return value

#static afterDelete()

# Arguments

# Return value

#static bindKnex()

# Arguments

# Return value

# Examples

#static bindTransaction()

# Examples

#static fromJson()

# Arguments

# Return value

# Examples

#static fromDatabaseJson()

# Arguments

# Return value

#static modifierNotFound()

# Arguments

#static createValidator()

# Examples

#static createNotFoundError()

# Arguments

# Return value

# Examples

#static createValidationError()

# Return value

#static fetchGraph()

# Arguments

# Return value

# Examples

#static traverseAsync()

# Arguments

# Examples

#static getRelations()

# Return value

#static columnNameToPropertyName()

# Arguments

# Return value

# Examples

#static propertyNameToColumnName()

# Arguments

#`static` query()

#`static` relatedQuery()

#`static` knex()

#`static` transaction()

#`static` startTransaction()

#`static` beforeFind()

#`static` afterFind()

#`static` beforeUpdate()

#`static` afterUpdate()

#`static` beforeInsert()

#`static` afterInsert()

#`static` beforeDelete()

#`static` afterDelete()

#`static` bindKnex()

#`static` bindTransaction()

#`static` fromJson()

#`static` fromDatabaseJson()

#`static` modifierNotFound()

#`static` createValidator()

#`static` createNotFoundError()

#`static` createValidationError()

#`static` fetchGraph()

#`static` traverseAsync()

#`static` getRelations()

#`static` columnNameToPropertyName()

#`static` propertyNameToColumnName()

#`static` fetchTableMetadata()

#`static` tableMetadata()

#`static` raw()

#`static` ref()

#`static` fn()

#`static` knexQuery()