Saving a Model

An instance of a Model can be saved to the database. This save operation can either be the insertion of a new record into the database or the update to an existing record.

save Method

The save method inserts or updates an existing record into the database with the contents of the Model instance. Prior to saving, the Model is validated to ensure that required values are specified, data can be properly cast into the corresponding database value, and foreign key constraints have been satisfied.

Syntax

save(options?: ModelSaveOptions): Promise<Model>

Parameters

Parameter	Type	Description
options	object	Options object (see below)

Options Object Properties

Property	Type	Description
maxReturnPayloadSize	number	The maximum allowed return payload size in bytes. If this size is exceeded a DbServerError will be thrown. If omitted the value specified during connection creation is used.
requestId	string	A request/trace ID to be passed to MVIS as a request header with the key X-MVIS-Trace-Id
userDefined	object	The user defined options to pass to the database subroutines

Example (Inserting a Record)

const schema = new Schema({
  description: { type: 'string', path: 1 },
  price: { type: 'number', path: 2, dbDecimals: 2 },
});

const Item = connection.model(schema, 'ITEM');

const item = new Item({ _id: '0001', data: { description: 'Racecar Bed', price: 999.99 } });

const savedItem = await item.save();

Example (Updating a Record)

const schema = new Schema({
  description: { type: 'string', path: 1 },
  price: { type: 'number', path: 2, dbDecimals: 2 },
});

const Item = connection.model(schema, 'ITEM');

const item = await Item.findById('0001');

item.price = 899.99;
const updatedItem = await item.save();
console.log(updatedItem.price); // outputs 899.99

Record Insertion Notes

Record Locks

MVOM will reject any database insertions for a record that is currently locked (e.g. a READU statement). In this scenario, save will reject with a RecordLockedError.

Record Existence

If a save operation is performed with a Model instance that was created via the new operator, the record with the ID corresponding to the _id property of the Model must not exist. If the record already exists, save will reject with a DocumentVersionMismatchError.

Record Update Notes

Handling of attributes which are not defined in the schema

MVOM does not require that the entirety of a record structure be defined in the schema. This ability allows you to only invest in defining the schema for those properties which are important for the current use case. When updating an existing record, MVOM will only modify properties which are defined by the schema. That is, any attributes which are not defined in the schema will be left unchanged when updating an existing record.

Record Locks

MVOM will reject any database updates for a record that is currently locked (e.g. a READU statement). In this scenario, save will reject with a RecordLockedError.

In scenarios where locks are intended to be transient, we suggest that you implement retry logic to attempt to save the record again.

Record Changes

When a record is read, a version string is generated by hashing the contents of the record. This version is stored with the Model instance in the __v property. When saving a record, this version is compared against the current state of the database record on disk. If the version has changed since the record was read, MVOM will not write the record. When the versions are mismatched, save will reject with a DocumentVersionMismatchError.

For records which change often, you should try to read and write the record with as little time between the operations as possible. Similar to handling record locks, implementing retry logic to read, update, and save the record may be beneficial.