Module: loopback

Class: PersistedModel

PersistedModel

Extends Model with basic query and CRUD support.

Change Event

Listen for model changes using the change event.

MyPersistedModel.on('changed', function(obj) {
   console.log(obj) // => the changed model
});

PersistedModel.bulkUpdate(updates, callback)

Apply an update list.

Note: this is not atomic

Arguments
Name Type Description
updates Array

An updates list, usually from createUpdates().

callback Function

Callback function.

PersistedModel.changes(since, filter, callback)

Get the changes to a model since the specified checkpoint. Provide a filter object to reduce the number of results returned.

Arguments
Name Type Description
since Number

Return only changes since this checkpoint.

filter Object

Include only changes that match this filter, the same as for #persistedmodel-find).

callback Function

Callback function called with (err, changes) arguments. Required.

Callback
Name Type Description
err Error

Error object; see Error object.

changes Array

An array of Change objects.

PersistedModel.checkpoint(callback)

Create a checkpoint.

Arguments
Name Type Description
callback Function

PersistedModel.count([where], callback)

Return the number of records that match the optional "where" filter.

Arguments
Name Type Description
[where] Object

Optional where filter, like { key: val, key2: {gt: 'val2'}, ...}
See Where filter.

callback Function

Callback function called with (err, count) arguments. Required.

Callback
Name Type Description
err Error

Error object; see Error object.

count Number

Number of instances updated.

PersistedModel.create({Object}|[{Object}], callback)

Create new instance of Model, and save to database.

Arguments
Name Type Description
{Object}|[{Object}]

data Optional data argument. Can be either a single model instance or an array of instances.

callback Function

Callback function called with cb(err, obj) signature.

Callback
Name Type Description
err Error

Error object; see Error object.

models Object

Model instances or null.

PersistedModel.createChangeStream(options, callback)

Create a change stream. See here for more info

Arguments
Name Type Description
options Object
options.where Object

Only changes to models matching this where filter will be included in the ChangeStream.

callback Function
Callback
Name Type Description
err Error
changes ChangeStream

PersistedModel.createUpdates(deltas, callback)

Create an update list (for Model.bulkUpdate()) from a delta list (result of Change.diff()).

Arguments
Name Type Description
deltas Array
callback Function

PersistedModel.currentCheckpoint(callback)

Get the current checkpoint ID.

Arguments
Name Type Description
callback Function

Callback function called with (err, currentCheckpointId) arguments. Required.

Callback
Name Type Description
err Error

Error object; see Error object.

currentCheckpointId Number

Current checkpoint ID.

persistedModel.destroy(callback)

Deletes the model from persistence. Triggers destroy hook (async) before and after destroying object.

Arguments
Name Type Description
callback Function

Callback function.

PersistedModel.destroyAll([where], callback)

Destroy all model instances that match the optional where specification.

Arguments
Name Type Description
[where] Object

Optional where filter, like: {key: val, key2: {gt: 'val2'}, ...}
See Where filter.

callback Function

Optional callback function called with (err, info) arguments.

Callback
Name Type Description
err Error

Error object; see Error object.

info Object

Additional information about the command outcome.

info.count Number

Number of instances (rows, documents) destroyed.

PersistedModel.destroyById(id, callback)

Destroy model instance with the specified ID.

Arguments
Name Type Description
id

The ID value of model instance to delete.

callback Function

Callback function called with (err) arguments. Required.

Callback
Name Type Description
err Error

Error object; see Error object.

PersistedModel.diff(since, remoteChanges, callback)

Get a set of deltas and conflicts since the given checkpoint.

See Change.diff() for details.

Arguments
Name Type Description
since Number

Find deltas since this checkpoint.

remoteChanges Array

An array of change objects.

callback Function

Callback function called with (err, result) arguments. Required.

Callback
Name Type Description
err Error

Error object; see Error object.

result Object

Object with deltas and conflicts properties; see Change.diff() for details.

PersistedModel.enableChangeTracking()

Enable the tracking of changes made to the model. Usually for replication.

PersistedModel.exists(id, callback)

Check whether a model instance exists in database.

Arguments
Name Type Description
id id

Identifier of object (primary key value).

callback Function

Callback function called with (err, exists) arguments. Required.

Callback
Name Type Description
err Error

Error object; see Error object.

exists Boolean

True if the instance with the specified ID exists; false otherwise.

PersistedModel.find([filter], callback)

Find all model instances that match filter specification. See Querying models.

Arguments
Name Type Description
[filter] Object

Optional Filter JSON object; see below.

callback Function

Callback function called with (err, returned-instances) arguments. Required.

[filter]
Name Type Description
fields String or Object or Array

Identify fields to include in return result.
See Fields filter.

include String or Object or Array

See PersistedModel.include documentation.
See Include filter.

limit Number

Maximum number of instances to return.
See Limit filter.

order String

Sort order: either "ASC" for ascending or "DESC" for descending.
See Order filter.

skip Number

Number of results to skip.
See Skip filter.

where Object

Where clause, like { where: { key: val, key2: {gt: 'val2'}, ...} }
See Where filter.

Callback
Name Type Description
err Error

Error object; see Error object.

models Array

Model instances matching the filter, or null if none found.

PersistedModel.findById(id, [filter], callback)

Find object by ID with an optional filter for include/fields.

Arguments
Name Type Description
id

Primary key value

[filter] Object

Optional Filter JSON object; see below.

callback Function

Callback function called with (err, instance) arguments. Required.

[filter]
Name Type Description
fields String or Object or Array

Identify fields to include in return result.
See Fields filter.

include String or Object or Array

See PersistedModel.include documentation.
See Include filter.

Callback
Name Type Description
err Error

Error object; see Error object.

instance Object

Model instance matching the specified ID or null if no instance matches.

PersistedModel.findOne([filter], callback)

Find one model instance that matches filter specification. Same as find, but limited to one result; Returns object, not collection.

Arguments
Name Type Description
[filter] Object

Optional Filter JSON object; see below.

callback Function

Callback function called with (err, returned-instance) arguments. Required.

[filter]
Name Type Description
fields String or Object or Array

Identify fields to include in return result.
See Fields filter.

include String or Object or Array

See PersistedModel.include documentation.
See Include filter.

order String

Sort order: either "ASC" for ascending or "DESC" for descending.
See Order filter.

skip Number

Number of results to skip.
See Skip filter.

where Object

Where clause, like {where: { key: val, key2: {gt: 'val2'}, ...} }
See Where filter.

Callback
Name Type Description
err Error

Error object; see Error object.

model Array

First model instance that matches the filter or null if none found.

PersistedModel.findOrCreate([filter], data, callback)

Finds one record matching the optional filter object. If not found, creates the object using the data provided as second argument. In this sense it is the same as find, but limited to one object. Returns an object, not collection. If you don't provide the filter object argument, it tries to locate an existing object that matches the data argument.

Arguments
Name Type Description
[filter] Object

Optional Filter object; see below.

data Object

Data to insert if object matching the where filter is not found.

callback Function

Callback function called with cb(err, instance, created) arguments. Required.

[filter]
Name Type Description
fields String or Object or Array

Identify fields to include in return result.
See Fields filter.

include String or Object or Array

See PersistedModel.include documentation.
See Include filter.

limit Number

Maximum number of instances to return.
See Limit filter.

order String

Sort order: either "ASC" for ascending or "DESC" for descending.
See Order filter.

skip Number

Number of results to skip.
See Skip filter.

where Object

Where clause, like {where: {key: val, key2: {gt: val2}, ...}}
See Where filter.

Callback
Name Type Description
err Error

Error object; see Error object.

instance Object

Model instance matching the where filter, if found.

created Boolean

True if the instance matching the where filter was created.

PersistedModel.getChangeModel()

Get the Change model. Throws an error if the change model is not correctly setup.

persistedModel.getId()

Get the id value for the PersistedModel.

Returns
Name Type Description
result

The id value

persistedModel.getIdName()

Get the id property name of the constructor.

Returns
Name Type Description
result String

The id property name

PersistedModel.getIdName()

Get the id property name of the constructor.

Returns
Name Type Description
result String

The id property name

PersistedModel.getSourceId(callback)

Get the source identifier for this model or dataSource.

Arguments
Name Type Description
callback Function

Callback function called with (err, id) arguments.

Callback
Name Type Description
err Error

Error object; see Error object.

sourceId String

Source identifier for the model or dataSource.

PersistedModel.handleChangeError(err)

Handle a change error. Override this method in a subclassing model to customize change error handling.

Arguments
Name Type Description
err Error

Error object; see Error object.

persistedModel.isNewRecord()

Determine if the data model is new.

Returns
Name Type Description
result Boolean

Returns true if the data model is new; false otherwise.

PersistedModel.rectifyChange(id, callback)

Specify that a change to the model with the given ID has occurred.

Arguments
Name Type Description
id

The ID of the model that has changed.

callback Function
Callback
Name Type Description
err Error

persistedModel.reload(callback)

Reload object from persistence. Requires id member of object to be able to call find.

Arguments
Name Type Description
callback Function

Callback function called with (err, instance) arguments. Required.

Callback
Name Type Description
err Error

Error object; see Error object.

instance Object

Model instance.

persistedModel.replaceAttributes(data, [options], callback)

Replace attributes for a model instance and persist it into the datasource. Performs validation before replacing.

Arguments
Name Type Description
data Object

Data to replace.

[options] Object

Options for replace

callback Function

Callback function called with (err, instance) arguments.

[options]
Name Type Description
validate Boolean

Perform validation before saving. Default is true.

Callback
Name Type Description
err Error

Error object; see Error object.

instance Object

Replaced instance.

PersistedModel.replaceById(id, data, [options], callback)

Replace attributes for a model instance whose id is the first input argument and persist it into the datasource. Performs validation before replacing.

Arguments
Name Type Description
id

The ID value of model instance to replace.

data Object

Data to replace.

[options] Object

Options for replace

callback Function

Callback function called with (err, instance) arguments.

[options]
Name Type Description
validate Boolean

Perform validation before saving. Default is true.

Callback
Name Type Description
err Error

Error object; see Error object.

instance Object

Replaced instance.

PersistedModel.replaceOrCreate(data, [options], callback)

Replace or insert a model instance; replace existing record if one is found, such that parameter data.id matches id of model instance; otherwise, insert a new record.

Arguments
Name Type Description
data Object

The model instance data.

[options] Object

Options for replaceOrCreate

callback Function

Callback function called with cb(err, obj) signature.

[options]
Name Type Description
validate Boolean

Perform validation before saving. Default is true.

Callback
Name Type Description
err Error

Error object; see Error object.

model Object

Replaced model instance.

PersistedModel.replicate([since], targetModel, [options], [callback])

Replicate changes since the given checkpoint to the given target model.

Arguments
Name Type Description
[since] Number

Since this checkpoint

targetModel Model

Target this model class

[options] Object
[options.filter] Object

Replicate models that match this filter

[callback] Function

Callback function called with (err, conflicts) arguments.

Callback
Name Type Description
err Error

Error object; see Error object.

conflicts Array.<Conflict>

A list of changes that could not be replicated due to conflicts.

{Object] checkpoints The new checkpoints to use as the "since"

argument for the next replication.

persistedModel.save([options], callback)

Save model instance. If the instance doesn't have an ID, then calls create instead. Triggers: validate, save, update, or create.

Arguments
Name Type Description
[options] Object

See below.

callback Function

Optional callback function called with (err, obj) arguments.

[options]
Name Type Description
validate Boolean

Perform validation before saving. Default is true.

throws Boolean

If true, throw a validation error; WARNING: This can crash Node. If false, report the error via callback. Default is false.

Callback
Name Type Description
err Error

Error object; see Error object.

instance Object

Model instance saved or created.

persistedModel.setId(val)

Set the correct id property for the PersistedModel. Uses the setId method if the model is attached to connector that defines it. Otherwise, uses the default lookup. Override this method to handle complex IDs.

Arguments
Name Type Description
val

The id value. Will be converted to the type that the id property specifies.

PersistedModel.updateAll([where], data, callback)

Update multiple instances that match the where clause.

Example:

Employee.updateAll({managerId: 'x001'}, {managerId: 'x002'}, function(err, info) {
    ...
});
Arguments
Name Type Description
[where] Object

Optional where filter, like { key: val, key2: {gt: 'val2'}, ...}
see Where filter.

data Object

Object containing data to replace matching instances, if any.

callback Function

Callback function called with (err, info) arguments. Required.

Callback
Name Type Description
err Error

Error object; see Error object.

info Object

Additional information about the command outcome.

info.count Number

Number of instances (rows, documents) updated.

persistedModel.updateAttribute(name, value, callback)

Update a single attribute. Equivalent to updateAttributes({name: 'value'}, cb)

Arguments
Name Type Description
name String

Name of property.

value Mixed

Value of property.

callback Function

Callback function called with (err, instance) arguments. Required.

Callback
Name Type Description
err Error

Error object; see Error object.

instance Object

Updated instance.

persistedModel.updateAttributes(data, callback)

Update set of attributes. Performs validation before updating.

Triggers: validation, save and update hooks

Arguments
Name Type Description
data Object

Data to update.

callback Function

Callback function called with (err, instance) arguments. Required.

Callback
Name Type Description
err Error

Error object; see Error object.

instance Object

Updated instance.

PersistedModel.upsert(data, callback)

Update or insert a model instance

Arguments
Name Type Description
data Object

The model instance data to insert.

callback Function

Callback function called with cb(err, obj) signature.

Callback
Name Type Description
err Error

Error object; see Error object.

model Object

Updated model instance.