# Types

This page contains the documentation of all other types and classes thanModel andQueryBuilder. There are two types of items on this page:

1. type: A type is just a POJO (Plain Old Javascript Object) with a set of properties.
2. class: A class is a JavaScript class with properties and methods.

#type RelationMapping

#type RelationJoin

#type RelationThrough

#type ModelOptions

#type CloneOptions

#type ToJsonOptions

#type GraphOptions

#type UpsertGraphOptions

#type InsertGraphOptions

#type FetchGraphOptions

#type TableMetadataFetchOptions

#type TableMetadataOptions

#type TableMetadata

#type StaticHookArguments

#type FieldExpression

Field expressions are strings that allow you to refer to JSONB fields inside columns.

Syntax:<column reference>[:<json field reference>]

e.g.persons.jsonColumnName:details.names[1] would refer to value'Second' in columnpersons.jsonColumnName which has{ details: { names: ['First', 'Second', 'Last'] } } object stored in it.

First part<column reference> is compatible with column references used in knex e.g.MyFancyTable.tributeToThBestColumnNameEver.

Second part describes a path to an attribute inside the referred column. It is optional and it always starts with colon which follows directly with first path element. e.g.Table.jsonObjectColumnName:jsonFieldName orTable.jsonArrayColumn:[321].

Syntax supports[<key or index>] and.<key or index> flavors of reference to json keys / array indexes:

e.g. bothTable.myColumn:[1][3] andTable.myColumn:1.3 would access correctly both of the following objects[null, [null,null,null, "I was accessed"]] and{ "1": { "3" : "I was accessed" } }

Caveats when using special characters in keys:

1. objectColumn.key This is the most common syntax, good if you are not using dots or square brackets[] in your json object key name.
2. Keys containing dotsobjectColumn:[keywith.dots] Column{ "keywith.dots" : "I was referred" }
3. Keys containing square bracketscolumn['[]']{ "[]" : "This is getting ridiculous..." }
4. Keys containing square brackets and quotesobjectColumn:['Double."Quote".[]'] andobjectColumn:["Sinlge.'Quote'.[]"] Column{ "Double.\"Quote\".[]" : "I was referred", "Sinlge.'Quote'.[]" : "Mee too!" }
5. Keys containing dots, square brackets, single quotes and double quotes in one json key is not currently supported

There are some special methods that acceptFieldExpression strings directly, likewhereJsonSupersetOf but you can useFieldExpressions anywhere withref. Here's an example:

const{ ref}=require('objection');await Person.query().select(['id',ref('persons.jsonColumn:details.name').castText().as('name'),ref('persons.jsonColumn:details.age').castInt().as('age'),]).join('someTable',ref('persons.jsonColumn:details.name').castText(),'=',ref('someTable.name')).where('age','>',ref('someTable.ageLimit'));

In the above example, we assumepersons table has a column namedjsonColumn of typejsonb (only works on postgres).

#type RelationExpression

Relation expression is a simple DSL for expressing relation trees.

These strings are all valid relation expressions:

• children
• children.movies
• [children, pets]
• [children.movies, pets]
• [children.[movies, pets], pets]
• [children.[movies.actors.[children, pets], pets], pets]
• [children as kids, pets(filterDogs) as dogs]

There are two tokens that have special meaning:* and^.* means "all relations recursively" and^ means "this relation recursively".

For examplechildren.* means "relationchildren and all its relations, and all their relations and ...".

Expressionparent.^ is equivalent toparent.parent.parent.parent... up to the point a relation no longer has results for theparent relation. The recursion can be limited to certain depth by giving the depth after the^ character. For exampleparent.^3 is equal toparent.parent.parent.

Relations can be aliased using theas keyword.

For example the expressionchildren.[movies.actors.[pets, children], pets] represents a tree:

              children              (Person)                 |         -----------------         |               |       movies           pets      (Movie)         (Animal)         |       actors      (Person)         |    -----------    |         |   pets    children (Animal)  (Person)

The model classes are shown in parenthesis. When given towithGraphFetched method, this expression would fetch all relations as shown in the tree above:

const people=await Person.query().withGraphFetched('children.[movies.actors.[pets, children], pets]');// All persons have the given relation tree fetched.console.log(people[0].children[0].movies[0].actors[0].pets[0].name);

Relation expressions can have arguments. Arguments are used to refer to modifier functions (eitherglobal orlocal. Arguments are listed in parenthesis after the relation names like this:

Person.query().withGraphFetched(`children(arg1, arg2).[movies.actors(arg3), pets]`);

You can spread relation expressions to multiple lines and add whitespace:

Person.query().withGraphFetched(`[    children.[      pets,      movies.actors.[        pets,        children      ]    ]  ]`);

Relation expressions can be aliased usingas keyword:

Person.query().withGraphFetched(`[    children as kids.[      pets(filterDogs) as dogs,      pets(filterCats) as cats,      movies.actors.[        pets,        children as kids      ]    ]  ]`);

# RelationExpression object notation

In addition to the string expressions, a more verbose object notation can also be used.

The string expression in the comment is equivalent to the object expression below it:

// `children`{children:true;}

// `children.movies`{children:{movies:true;}}

// `[children, pets]`{children:true;pets:true;}

// `[children.[movies, pets], pets]`{children:{movies:true,pets:true}pets:true}

// `parent.^`{parent:{$recursive:true;}}

// `parent.^5`{parent:{$recursive:5;}}

// `parent.*`{parent:{$allRecursive:true;}}

// `[children as kids, pets(filterDogs) as dogs]`{kids:{$relation:'children'},dogs:{$relation:'pets',$modify:['filterDogs']}}

#type TransactionObject

This is nothing more than a knex transaction object. It can be used as a knex query builder, it can bepassed to objection queries andmodels can be bound to it

See the section abouttransactions for more info and examples.

# Instance Methods

# commit()

const promise= trx.commit();

Call this method to commit the transaction. This only needs to be called if you usetransaction.start() method.

# rollback()

const promise= trx.rollback(error);

Call this method to rollback the transaction. This only needs to be called if you usetransaction.start() method. You need to pass the error to the method as the only argument.

#class ValidationError

const{ ValidationError}=require('objection');thrownewValidationError({ type, message, data});

For eachkey, a list of errors is given. Each error contains the defaultmessage (as returned by the validator), an optionalkeyword string to identify the validation rule which didn't pass and aparam object which optionally contains more details about the context of the validation error.

Iftype is anything else but"ModelValidation",data can be any object that describes the error.

Error of this class is thrown by default if validation of any input fails. By input we mean any data that can come from the outside world, like model instances (or POJOs), relation expressions object graphs etc.

You can replace this error by overridingModel.createValidationError() method.

See theerror handling recipe for more info.

Iftype is"ModelValidation" thendata object should follow this pattern:

{key1:[{message:'...',keyword:'required',params:null},{message:'...',keyword:'...',params:{...}},...],key2:[{message:'...',keyword:'minLength',params:{limit:1,...}},...],...}

#class NotFoundError

const{ NotFoundError}=require('objection');thrownewNotFoundError(data);

Error of this class is thrown by default bythrowIfNotFound()

You can replace this error by overridingModel.createNotFoundError() method.

See theerror handling recipe for more info.

#class Relation

Relation is a parsed and normalized instance of aRelationMapping.Relations can be accessed using thegetRelations method.

Relation holds aRelationProperty instance for each property that is used to create the relationship between two tables.

Relation is actually a base class for all relation typesBelongsToOneRelation,HasManyRelation etc. You can useinstanceof to determine the type of the relations (see the example on the right). Note thatHasOneRelation is a subclass ofHasManyRelation andHasOneThroughRelation is a subclass ofManyToManyRelation. Arrange yourinstanceof checks accordingly.

Note thatRelation instances are actually instances of the relation classes used inrelationMappings. For example:

classPersonextendsModel{staticgetrelationMappings(){return{pets:{relation: Model.HasManyRelation,modelClass: Animal,join:{from:'persons.id',to:'animals.ownerId',},},};}}const relations= Person.getRelations();console.log(relations.petsinstanceofModel.HasManyRelation);// --> trueconsole.log(relations.pets.name);// --> petsconsole.log(relations.pets.ownerProp.cols);// --> ['id']console.log(relations.pets.relatedProp.cols);// --> ['ownerId']

#class RelationProperty

Represents a property that is used to create relationship between two tables. A singleRelationProperty instance can representcomposite key. In addition to a table column, ARelationProperty can represent a nested field inside a column (for example a jsonb column).

# Properties

# Methods

# getProp()

const value= property.getProp(obj, index);

Gets this property's index:th value from an object. For example if the property represents a composite key[a, b.d.e, c]and obj is{a: 1, b: {d: {e: 2}}, c: 3} thengetProp(obj, 1) would return2.

# setProp()

property.setProp(obj, index, value);

Sets this property's index:th value in an object. For example if the property represents a composite key[a, b.d.e, c]and obj is{a: 1, b: {d: {e: 2}}, c: 3} thensetProp(obj, 1, 'foo') would mutateobj into{a: 1, b: {d: {e: 'foo'}}, c: 3}.

# fullCol()

const col= property.fullCol(builder, index);

Returns the property's index:th column name with the correct table reference. Something like"Table.column".The first argument must be an objectionQueryBuilder instance.

# ref()

const ref= property.ref(builder, index);

Allows you to do things like this:

const builder= Person.query();const ref= property.ref(builder,0);builder.where(ref,'>',10);

Returns aReferenceBuilder instance that points to the index:th column.

# patch()

property.patch(patchObj, index, value);

Allows you to do things like this:

const builder= Person.query();const patch={};property.patch(patch,0,'foo');builder.patch(patch);

Appends an update operation for the index:th column intopatchObj object.

#class ReferenceBuilder

An instance of this is returned from theref helper function.

# Instance Methods

# castText()

Cast reference to sql typetext.

# castInt()

Cast reference to sql typeinteger.

# castBigInt()

Cast reference to sql typebigint.

# castFloat()

Cast reference to sql typefloat.

# castDecimal()

Cast reference to sql typedecimal.

# castReal()

Cast reference to sql typereal.

# castBool()

Cast reference to sql typeboolean.

# castTo()

Give custom type to which referenced value is cast to.

.castTo('mytype') --> CAST(?? as mytype)

# castJson()

In addition to other casts wrap reference to_jsonb() function so that final valuereference will be json type.

# as()

Gives an alias for the reference.select(ref('age').as('yougness'))

# from()

Specifies that table of the reference.

Seethis for some examples.

#class ValueBuilder

An instance of this is returned from theval helper function. If an objectis given as a value, it is cast to json by default.

# Instance Methods

# castText()

Cast to sql typetext.

# castInt()

Cast to sql typeinteger.

# castBigInt()

Cast to sql typebigint.

# castFloat()

Cast to sql typefloat.

# castDecimal()

Cast to sql typedecimal.

# castReal()

Cast to sql typereal.

# castBool()

Cast to sql typeboolean.

# castTo()

Give custom type to which referenced value is cast to.

.castTo('mytype') --> CAST(?? as mytype)

# castJson()

Converts the value to json (jsonb in case of postgresql). The defaultcast type for object values.

# asArray()

Converts the value to an array.

val([1, 2, 3]).asArray() --> ARRAY[?, ?, ?]

Can be used in conjuction withcastTo.

val([1, 2, 3]).asArray().castTo('real[]') -> CAST(ARRAY[?, ?, ?] AS real[])

# as()

Gives an alias for the reference.select(ref('age').as('yougness'))

#class RawBuilder

An instance of this is returned from theraw helper function.

# Instance Methods

# as()

Gives an alias for the raw expression.select(raw('concat(foo, bar)').as('fooBar')).

You should use this instead of inserting the alias to the SQL to give objection more information about the query. Some edge cases, like usingraw inselect inside awithGraphJoined modifier won't work unless you use this method.

#class FunctionBuilder

An instance of this is returned from thefn helper function.

# Instance Methods

# as()

Gives an alias for the raw expression.select(fn('concat', 'foo', 'bar').as('fooBar')).

You should use this instead of inserting the alias to the SQL to give objection more information about the query. Some edge cases, like usingfn inselect inside awithGraphJoined modifier won't work unless you use this method.

#class Validator

const{ Validator}=require('objection');

Abstract class from which model validators must be inherited. See the example for explanation. Also check out thecreateValidator method.

# Examples

const{ Validator}=require('objection');classMyCustomValidatorextendsValidator{validate(args){// The model instance. May be empty at this point.const model= args.model;// The properties to validate. After validation these values will// be merged into `model` by objection.const json= args.json;// `ModelOptions` object. If your custom validator sets default// values, you need to check the `opt.patch` boolean. If it is true// we are validating a patch object and the defaults should not be set.const opt= args.options;// A context object shared between the validation methods. A new// object is created for each validation operation. You can store// any data here.const ctx= args.ctx;// Do your validation here and throw any exception if the// validation fails.doSomeValidationAndThrowIfFails(json);// You need to return the (possibly modified) json.return json;}beforeValidate(args){// Takes the same arguments as `validate`. Usually there is no need// to override this.returnsuper.beforeValidate(args);}afterValidate(args){// Takes the same arguments as `validate`. Usually there is no need// to override this.returnsuper.afterValidate(args);}}const{ Model}=require('objection');// Override the `createValidator` method of a `Model` to use the// custom validator.classBaseModelextendsModel{staticcreateValidator(){returnnewMyCustomValidator();}}

#class AjvValidator

const{ AjvValidator}=require('objection');

The defaultAjv(opens new window) based json schemavalidator. You can override thecreateValidatormethod ofModel like in the example to modify the validator.

# Examples

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