Query¶

Query is a class which could be only instancied with the query static method of model.

Query is a query builder used to run operation on your database. Like find an instance or update multiple instances.

Query work directly in function of your schema. Every field declared on your schema are defined as attribute of the Query. You can split your query into two things : - The query building part : You choose what your query will do. - The query run part : You choose the operation to do and execute the query.

Query building¶

Query building are in function of the field of your schema. All method are children of attribute defined in your schema.

Little example

With this kind of schema :

const invoice = new Schema({
    date: Schema.date().required(),
    amount: Schema.number().required(),
})

You could use this kind of query :

const invoice = await Invoices.query()
    .amount.greaterThan(100) // amount is here in function of your schema
    .findOne();

new Query({ transaction, })¶

Create a transaction, transaction can not be created directly. You need to use Model.query().

Parameter	Type	Description
transaction	Transaction	Bind a transaction to the query, you could use Query.transaction for doing the same

Query.transaction(transaction)¶

Bind a transaction to the query.

Parameter	Type	Description
transaction	Transaction	Bind a transaction to the query, you could use Query.transaction for doing the same

Query.[field].is()¶

Check if the [field] is equal of the specified value.

Query.field.is(value);

Returns a query to chain call.

Parameter	Type	Description
value	Mixing	The field need to be equal of this value.

Query.[field].isNot()¶

Check if the [field] is not equal of the specified value.

Query.field.isNot(value);

Returns a query to chain call.

Parameter	Type	Description
value	Mixing	The field need to be different of this value.

Query.[field].isIn()¶

Check if the [field] is a member of the parameter array

Query.field.isIn(arrayOfValue);

Returns a query to chain call.

Parameter	Type	Description
arrayOfValue	Array.<Mixing>	The field need to be equal at one array element.

Query.[field].isNotIn()¶

Check if the [field] is not one of the array value.

Query.field.isNotIn(arrayOfValue);

Returns a query to chain call.

Parameter	Type	Description
arrayOfValue	Array.<Mixing>	The field need to be different of each array element.

Query.[field].greaterThan()¶

Check if the [field] is greater than the specified value.

Query.field.greaterThan(value);

Returns a query to chain call.

Parameter	Type	Description
value	Mixing	The field need to be greater than value.

Info

Only work with SchemaField/Number or SchemaField/Date (or with some plugin SchemaField).

Query.[field].lowerThan()¶

Check if the [field] is lower than the specified value.

Query.field.lowerThan(value);

Returns a query to chain call.

Parameter	Type	Description
value	Mixing	The field need to be lower than value.

Info

Only work with SchemaField/Number or SchemaField/Date (or with some plugin SchemaField).

Query.[field].greaterOrEqualThan()¶

Check if the [field] is equal or greater than the specified value.

Query.field.greaterOrEqualThan(value);

Returns a query to chain call.

Parameter	Type	Description
value	Mixing	The field need to be equal or grater than value.

Info

Only work with SchemaField/Number or SchemaField/Date (or with some plugin SchemaField).

Query.[field].lowerOrEqualThan()¶

Check if the [field] is equal or lower than specified value.

Query.field.lowerOrEqualThan(value);

Returns a query to chain call.

Parameter	Type	Description
value	Mixing	The field need to be equal or lower than value.

Info

Only work with SchemaField/Number or SchemaField/Date (or with some plugin SchemaField).

Query.[field].between()¶

Check if the [field] is between min and max.

Query.field.between(min, max);

Returns a query to chain call.

Parameter	Type	Description
min	Mixing	The field need to be greater than min.
max	Mixing	The field need to be lower than max.

Info

Only work with SchemaField/Number or SchemaField/Date (or with some plugin SchemaField).

Select specific fields¶

Query.[field].select()¶

Use to target specific field to be returned by the query. The [field] will be part of the output result.

Query.field.select();

Info

The json object resulting of the query will not be an instance anymore!
If you want to select only one field, you could use selectOnly

Query.[field].selectOnly()¶

Use to target specific field to be returned by the query. Only the [field] will be part of the output result.

Query.field.selectOnly();

Example of selectOnly

const email = await User.query()
    ._id.is(TARGET_ID)
    .email.selectOnly()
    .findOne();

query.linkedWith()¶

LinkedWith allow smart query. Ilorm will know the relation between the value and the current Model. value could be a Query, a model instance or a model Id.

Query.linkedWith(value)

Parameter	Type	Description
value	Model, Query or Model_ID	the value linked with the given query

Example of linkedWith

// Select first unpaid invoice linked with a user with balance > 0
const QUERY_USER_WITH_POSITIVE_BALANCE = User.query()
    .balance.greaterThan(0);

const invoice = await Invoices.query()
    .isPaid.is(false)
    .linkedWith(QUERY_USER_WITH_POSITIVE_BALANCE)
    .findOne();

query.or()¶

Creating branch.

Query.or(orHandler)

Parameter	Type	Description
orHandler	Function	Take a function in parameter used to build subquery

Example of or

const email = await User.query()
    .or(orBranch => {
      orBranch().email.is('email');
      orBranch().email.is('alternativeEmail');
    })
    .findOne();

Query sorting¶

Query.[field].useAsSortAsc()¶

Sorting the result ascending of the query by the given field.

Query.field.useAsSortAsc();

Query.[field].useAsSortDesc()¶

Sorting the result descending of the query by the given field.

Query.field.useAsSortDesc();

Query pagination¶

Query.skip()¶

Skip a number of element before getting the result.

Query.skip(nbToSkip);

Parameter	Type	Description
nbToSkip	Number	The amount of element to skip before starting gathering result.

Query.limit()¶

Limit the number of element impacted by the query.

Query.limit(nbToImpact);

Parameter	Type	Description
nbToImpact	Number	The amount of element to fetch or update or remove.

Query running¶

(async) Query.findOne()¶

Execute the query, and returns one element which match it.

const instance = await query.findOne();

Return one instance which match the query.

(async) Query.find()¶

Execute the query, and returns one array containing all elements which match the query.

const arrayOfInstances = await query.find();

Return all instance which match the query.

(async) Query.stream()¶

Execute the query, and returns the stream of all elements matching the query

const streamOfInstances = await query.stream();

Return a stream containing all elements matching the query.

(async) Query.count()¶

Execute the query, and return how many item match the query.

const numberOfInstance = await query.count();

Return the number of instance which match the query.

(async) Query.updateOne()¶

Update the first element matching the query.

// Set isPaid flag to true on the invoice with id INVOICE_ID;
await Invoices.query()
    .id.is(INVOICE_ID)
    .isPaid.set(true)
    .updateOne();

(async) Query.update()¶

Execute an update targeting all element matching the query.

// Change invoices owner
await Invoices.query()
    .ownerId.is(OLD_OWNER)
    .ownerId.set(NEW_OWNER)
    .update();

(async) Query.removeOne()¶

Remove the first element matching the query.

// Remove randomly one invoice;
await Invoices.query()
    .removeOne();

(async) Query.remove()¶

Remove all elements matching the query

// Remove all paid invoices;
await Invoices.query()
    .isPaid.is(true)
    .remove();