Update

In this section, we will explore how to update data in NimbusDB. We’ll use this schema and the items model as an example to demonstrate how to update data in a model:

GML

var schema = {
    id: {
        type: NIMBUSDB_DATA_TYPE.INTEGER,
        const: NIMBUSDB_CONSTRAINT.PRIMARY_KEY
    },
    name: NIMBUSDB_DATA_TYPE.STRING,
    price: {
        type: NIMBUSDB_DATA_TYPE.NUMBER,
        validator: function(data, value) {
            return value >= 0;
        },
        default_value: 0
    },
    is_locked: {
        type: NIMBUSDB_DATA_TYPE.BOOLEAN,
        const: NIMBUSDB_CONSTRAINT.OPTIONAL,
        default_value: false
    }
};

items = new NimbusDBModel("global", "items", schema, [
    { id: 1, name: "Apple", price: 5 },
    { id: 2, name: "Banana", price: 7.2 },
    { id: 3, name: "Cherry", price: 15 },
    { id: 4, name: "Date", price: 12.5 },
    { id: 5, name: "Elderberry", price: 8 },
    { id: 6, name: "Fig", price: 10 },
    { id: 7, name: "Grape", price: 6 },
    { id: 8, name: "Honeydew", price: 9 },
    { id: 9, name: "Kiwi", price: 4 },
    { id: 10, name: "Lemon", price: 3 }
]);

Updating Data

To update data in the items model, you can use the .update() master method, or its derived methods .update_by_index(), .update_by_primary(), .update_by_value(), and .update_by_function(). These methods allow you to update data based on specific criteria defined in your queries.

By Index

If you already have the index of the record(s) you want to update (e.g. from a .find_index() method), you can use the .update_by_index() method to update the data. This method will update all records with the same index.

GML

// using object
items.update_by_index(0, {      // update the first record
    name: "Green Apple",        // update the name column
    price: 6.5                  // update the price column
});

items.update_by_index([2, 5], [
    { name: "Blueberry" },              // only update the name column for the third record
    { name: "Raspberry", price: 10 }    // update the name and price column for the sixth record
]);

// using columns
items.update_by_index(1, "name", "Yellow Banana");  // update the name column for the second record

items.update_by_index([3, 4], "name", ["Golden Date", "Black Elderberry"]);  // update the name column for the fourth and fifth record

items.update_by_index(6, ["name", "price"], ["Purple Grape", 7.5]);  // update the name and price column for the seventh record

items.update_by_index([7, 8], ["name", "price"], [    // update the name and price column for the eighth and ninth record
    ["Sweet Honeydew", 9.5],
    ["Sour Kiwi", 4.5]
]);

By Primary Key

If you want to update data based on the primary key, you can use the .update_by_primary() method. This method will update all records with the same primary key.

GML

// using object
items.update_by_primary(1, {      // update the record with primary key 1
    name: "Green Apple",          // update the name column
    price: 6.5                    // update the price column
});

items.update_by_primary([3, 6], [
    { name: "Blueberry" },              // only update the name column for the third record
    { name: "Raspberry", price: 10 }    // update the name and price column for the sixth record
]);

// using columns
items.update_by_primary(2, "name", "Yellow Banana");  // update the name column for the second record

items.update_by_primary([4, 5], "name", ["Golden Date", "Black Elderberry"]);  // update the name column for the fourth and fifth record

items.update_by_primary(7, ["name", "price"], ["Purple Grape", 7.5]);  // update the name and price column for the seventh record

items.update_by_primary([8, 9], ["name", "price"], [    // update the name and price column for the eighth and ninth record
    ["Sweet Honeydew", 9.5],
    ["Sour Kiwi", 4.5]
]);

By Column Value

If you aren’t sure which record(s) you want to update, but you know the value of a specific column, you can use the .update_by_value() method to update the data. This method will update record(s) that match the specified column value.

GML

// using object
items.update_by_value("name", "Apple", {    // update the first record with `name` = "Apple"
    name: "Green Apple",
    price: 6.5
});

items.update_by_value("price", [6, 9], {    // update the first record with `price` = 6 or 9
    price: some_value
});

items.update_by_value("name", "Banana", {   // update all records with `name` = "Banana"
    name: "Golden Banana",
    price: 12.6,
    is_locked: true
}, {
    match_all: true
});

// using columns
items.update_by_value("name", "Cherry", "price", 14);   // update the `price` column for the first record with `name` = "Cherry"

items.update_by_value("price", 4, ["name", "price"], ["Sour Kiwi", 4.5]);   // update the `name` and `price` column for the first record with `price` = 4
// the new values (parameter 4) based on the column order (parameter 3),
// so in this case, `name` will be updated to "Sour Kiwi" and `price` will be updated to 4.5 for the first record with `price` = 4

items.update_by_value("price", [5, 10, 15], ["name", "price"], ["Fruit of 5", 4.99]);   // update the `name` and `price` column for the first record with `price` = 5, 10, or 15

items.update_by_value("name", ["Date", "Fig", "Lemon"],
    ["name", "price", "is_locked"],     // the columns to be updated
    [
        ["Golden Date", 12.5, true],    // the first matching record will be updated to this values
        ["Fresh Fig", 9.99],            // the second matching record will be updated to this values
        ["Sour Lemon", 2.5, true]       // and the rest of the matching records will be updated to this values
    ],
    {
        match_all: true                 // update all records with `name` = "Date", "Fig", or "Lemon"
    }
);

Note

The operation of this method is based on the:

• = operator if the value is a single value, or
• in operator if the value is an array.

So, if you want to use other operators (e.g. >, <, !=, etc.) or more complex data-finding processes, please use the .update_by_function() method instead.

Caution

Wildcards aren’t supported in this method.

By Custom Function

If you want to update data based on more complex criteria, you can use the .update_by_function() method. This method allows you to define a custom function that will be used to find the record(s) to be updated.

GML

// using object
items.update_by_function(function(data) {    // update the first record with `price` <= 4
    return data.price <= 4;
}, {
    price: 3.99
});

items.update_by_function(function(data) {    // update all records with `price` > 8 and `is_locked` = false
    return data.price > 8 && !data.is_locked;
}, {
    name: "Expensive Fruit",
    is_locked: true
}, {
    match_all: true
});

// using columns
items.update_by_function(function(data) {    // update the `name` column for the first record with `price` >= 10
    return data.price >= 10;
}, "name", "Premium Fruit");

items.update_by_function(function(data) {    // update the `name` and `is_locked` column for all records with `price` < 5 or `name` = "Lemon"
    return data.price < 5 || data.name == "Lemon";
}, ["name", "is_locked"], ["Cheap Fruit", true], {
    match_all: true
});

Dynamic Values

In the update methods above, the new value(s) to be applied during the update operation can also be dynamic values that are determined based on the current data. To use dynamic values, you can pass a function as the new value instead of a static value.

The function will receive the current data and index as parameters, and should return the new value to be applied.

Note

If the column in the schema has METHOD data type, the method won’t be called during the update operation. Instead, it will replace the old method with the new one.

GML

items.update_by_index(0, {
    name: "Green Apple",
    price: function(data) { return data.price + 2.3; }  // add 2.3 to the current price
});

items.update_by_primary(3, "price", function(data) {
    return data.price * 0.9;        // decrease the price by 10%
});

items.update_by_value("price", [5, 10, 15],
    ["price", "is_locked"],
    [
        function(data) { return data.price - 0.3; },  // decrease the price by 30%
        function(data) { return data.price > 10; }    // set the `is_locked` column to true if the price is greater than 10
    ],
    { match_all: true }
);

items.update_by_function(function(data) { return data.price > 10; }, {
    name: function(data) { return data.name + " (discounted)"; }   // append " (discounted)" to the name
    discount_price: function(data) { return data.price * 0.7; }    // discount the price by 30%
}, {
    match_all: true
});

Tip

All .update method variants support dynamic values for the update data. It also support both object and column formats for the update data.

Danger

You must treat the data parameter as read-only. Do not modify the data object directly, because the passed data has DIRECT access type. So, it will affect the original data.

GML

items.update_by_primary(3, "price", function(data) {
    // DO NOT DO THIS
   data.price = data.price * 0.9;
   data.is_locked = true;
   data.price++;
    return data.price * 0.9;        // return the updated value immediately
});

Which Method to Use?

The choice between the .update() variants depends on the use case:

1. For the precise update of one or more records, and you already know which record(s) to be updated:
   • For future-proof code, use .update_by_primary() method. It always works, even if the data order changes in the future.
   • For performance, as long as you know the index of the record(s) you want to update, use .update_by_index() method. But be aware that the index may change in the runtime/future (e.g. when you add, remove, or sort the records).
2. If you don’t know which record(s) to be updated, or you want to bulk-update the data:
   • For simplicity, use .update_by_value() method. It’s easier to use and understand.
   • For complex data-finding processes, use .update_by_function() method.

Upsert

Upsert is a special type of update operation that allows you to insert or update data in the model based on the matching criteria. It is useful when you want to ensure that the data exists in the model, and if not, insert it.

GML

items.upsert({      // will be inserted due no data has `id` = 11
    id: 11,
    name: "Melon",
    price: 8.5,
});

items.upsert([
    { id: 12, name: "Nectarine", price: 10 },    // will be inserted due no data has `id` = 12
    { id: 3, price: 11.7 },                      // will be updated due `id` = 3 already exists, `price` will be updated to 11.7
    { name: "Orange", price: 7.5 }               // will be skipped due the matching column (`id`) is missing, and `insert_if_missing` option is set to `false`
]);

items.upsert([
    { name: "Orange", price: 7.5 }               // will be inserted due `insert_if_missing` option is set to `true`
], {
    insert_if_missing: true
});

items.upsert([
    { id: 14, name: "Peach", price: 12.5 },         // will be inserted due no data has "Peach" in the `name` column
    { name: "Apple", price: 6.5, is_locked: true }  // will be updated due `Apple` already exists, `price` will be updated to 6.5, and `is_locked` will be set to `true`
], {
    match_column: "name"
});

---

References

Model.update() Master

Updates data in the model.

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static update(
        _selector:
            | NimbusDBUpdateByIndex
            | NimbusDBUpdateByPrimary
            | NimbusDBUpdateByValue
            | NimbusDBUpdateByFunction,
        _update_data: any
    ): NimbusDBUpdateResult;
}

Parameters

_selector

• Type: NimbusDBUpdateByIndex | NimbusDBUpdateByPrimary | NimbusDBUpdateByColumn | NimbusDBUpdateByFunction
• The selector object to use for the operation.

_update_data

• Type: any
• The data to apply during the update.

Returns

• Type: NimbusDBUpdateResult
• The update result metadata.

Model.update_by_index()

Updates data in the model by index.

Overload 1

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static update_by_index(
        _index: int | int[],
        _update_data: Struct,
        _options?: NimbusDBUpdateOptions
    ): NimbusDBUpdateResult;
}

Parameters

_index

• Type: int | int[]
• The index(es) of the record(s) to be updated.

_update_data

• Type: Struct
• The data to apply during the update.

_options

• Type: NimbusDBUpdateOptions
• Default: undefined
• An optional object that allows you to customize the behavior of the update operation. See the NimbusDBUpdateOptions type for the available options.

Returns

• Type: NimbusDBUpdateResult
• The update result metadata.

Overload 2

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static update_by_index(
        _index: int | int[],
        _column: string | string[],
        _value: any | any[],
        _options?: NimbusDBUpdateOptions
    ): NimbusDBUpdateResult;
}

Parameters

_index

• Type: int | int[]
• The index(es) of the record(s) to be updated.

_column

• Type: string | string[]
• The name(s) of the column(s) to be updated.

_value

• Type: any | any[]
• The value(s) to apply during the update.

_options

• Type: NimbusDBUpdateOptions
• Default: undefined
• An optional object that allows you to customize the behavior of the update operation. See the NimbusDBUpdateOptions type for the available options.

Returns

• Type: NimbusDBUpdateResult
• The update result metadata.

Model.update_by_primary()

Updates data in the model by primary key.

Overload 1

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static update_by_primary(
        _primary: int | int[],
        _update_data: Struct | Struct[],
        _options?: NimbusDBUpdateOptions
    ): NimbusDBUpdateResult;
}

Parameters

_primary

• Type: int | int[]
• The primary key(s) of the record(s) to be updated.

_update_data

• Type: Struct | Struct[]
• The data to apply during the update.

_options

• Type: NimbusDBUpdateOptions
• Default: undefined
• An optional object that allows you to customize the behavior of the update operation. See the NimbusDBUpdateOptions type for the available options.

Returns

• Type: NimbusDBUpdateResult
• The update result metadata.

Overload 2

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static update_by_primary(
        _primary: int | int[],
        _column: string | string[],
        _value: any | any[],
        _options?: NimbusDBUpdateOptions
    ): NimbusDBUpdateResult;
}

Parameters

_primary

• Type: int | int[]
• The primary key(s) of the record(s) to be updated.

_column

• Type: string | string[]
• The name(s) of the column(s) to be updated.

_value

• Type: any | any[]
• The value(s) to apply during the update.

_options

• Type: NimbusDBUpdateOptions
• Default: undefined
• An optional object that allows you to customize the behavior of the update operation. See the NimbusDBUpdateOptions type for the available options.

Returns

• Type: NimbusDBUpdateResult
• The update result metadata.

Model.update_by_value()

Updates data in the model by matching a column value.

Note

This method only accepts = and in operators for the data-finding process. For other operators or other complex data-finding processes, please use the .update_by_function() method instead.

Overload 1

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static update_by_value(
        _column: string,
        _value: any,
        _update_data: Struct | Struct[],
        _options?: NimbusDBUpdateOptions
    ): NimbusDBUpdateResult;
}

Parameters

_column

• Type: string
• The name of the column to be found.

_value

• Type: any
• The value to match for the update.

_update_data

• Type: Struct | Struct[]
• The data to apply during the update.

_options

• Type: NimbusDBUpdateOptions
• Default: undefined
• An optional object that allows you to customize the behavior of the update operation. See the NimbusDBUpdateOptions type for the available options.

Returns

• Type: NimbusDBUpdateResult
• The update result metadata.

Overload 2

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static update_by_value(
        _column: string,
        _value: any,
        _update_column: string | string[],
        _new_value: any | any[],
        _options?: NimbusDBUpdateOptions
    ): NimbusDBUpdateResult;
}

Parameters

_column

• Type: string
• The name of the column to be found.

_value

• Type: any
• The value to match for the update.

_update_column

• Type: string | string[]
• The name(s) of the column(s) to update.

_new_value

• Type: any | any[]
• The updated value(s) to apply during the update.

_options

• Type: NimbusDBUpdateOptions
• Default: undefined
• An optional object that allows you to customize the behavior of the update operation. See the NimbusDBUpdateOptions type for the available options.

Returns

• Type: NimbusDBUpdateResult
• The update result metadata.

Model.update_by_function()

Updates data in the model by matching a custom function.

Overload 1

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static update_by_function(
        _func: (data: Struct, index: int) => boolean,
        _update_data: Struct | Struct[],
        _options?: NimbusDBUpdateOptions
    ): NimbusDBUpdateResult;
}

Parameters

_func

• Type: (data: Struct, index: int) => boolean
• The function/method to be used for the update.

_update_data

• Type: Struct | Struct[]
• The data to apply during the update.

_options

• Type: NimbusDBUpdateOptions
• Default: undefined
• An optional object that allows you to customize the behavior of the update operation. See the NimbusDBUpdateOptions type for the available options.

Returns

• Type: NimbusDBUpdateResult
• The update result metadata.

Overload 2

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static update_by_function(
        _func: (data: Struct, index: int) => boolean,
        _update_column: string | string[],
        _new_value: any | any[],
        _options?: NimbusDBUpdateOptions
    ): NimbusDBUpdateResult;
}

Parameters

_func

• Type: (data: Struct, index: int) => boolean
• The function/method to be used for the update.

_update_column

• Type: string | string[]
• The name(s) of the column(s) to update.

_new_value

• Type: any | any[]
• The updated value(s) to apply during the update.

_options

• Type: NimbusDBUpdateOptions
• Default: undefined
• An optional object that allows you to customize the behavior of the update operation. See the NimbusDBUpdateOptions type for the available options.

Returns

• Type: NimbusDBUpdateResult
• The update result metadata.

Model.upsert()

Inserts or updates data in the model based on the matching criteria.

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static upsert(
        _data: Struct | Struct[],
        _options?: NimbusDBUpsertOptions
    ): NimbusDBUpsertResult;
}

Parameters

_data

• Type: Struct | Struct[]
• The data to be inserted or updated.

_options

• Type: NimbusDBUpsertOptions
• Default: undefined
• An optional object that allows you to customize the behavior of the upsert operation. See the NimbusDBUpsertOptions type for the available options.

Returns

• Type: NimbusDBUpsertResult
• The upsert result metadata.

NimbusDBUpdateByIndex

A selector object for .update() method that allows you to update data by index.

query-update.d.ts

type NimbusDBUpdateByIndex = {
    index: int | int[];
} & NimbusDBUpdateOptions;

NimbusDBUpdateByPrimary

A selector object for .update() method that allows you to update data by primary key.

query-update.d.ts

type NimbusDBUpdateByPrimary = {
    primary: int | int[];
    id?: int | int[];        // alias for `primary`
} & NimbusDBUpdateOptions;

NimbusDBUpdateByValue

A selector object for .update() method that allows you to update data by matching a column value.

query-update.d.ts

type NimbusDBUpdateByColumn = {
  match_column: string;
  value: any | any[];
} & NimbusDBUpdateOptions;

NimbusDBUpdateByFunction

A selector object for .update() method that allows you to update data by matching a custom function.

query-update.d.ts

type NimbusDBUpdateByFunction = {
    func: (data: Struct, index: int) => boolean;
    where?: (data: Struct, index: int) => boolean;    // alias for `func`
} & NimbusDBUpdateOptions;

NimbusDBUpdateOptions

A type for the options parameter of the .update() method.

query-update.d.ts

type NimbusDBUpdateOptions = Partial<{
  force: boolean;             // bypass column rules, type check, and validator (default = false)
  keep_temp: boolean;         // keep temp data after the operation (default = false)
  length: int;                // length for search (default = data.length)
  match_all: boolean;         // get all matching data (default = false)
  start_index: int;           // start index for search (default = 0)
  use_validator: boolean;     // use `validator` in the schema (default = true)
  use_default: boolean;       // use `default` in the schema if `validator` failed (default = false)
}>;

force

• Type: boolean
• Default: false
• Whether to bypass column rules, type check, and validator for the update operation. This can be useful for cases where you want to update data without enforcing any rules or validation.

keep_temp

• Type: boolean
• Default: false
• Whether to keep the user-defined temporary data after the update operation.

length

• Type: int
• Default: data.length
• The maximum number of entries to process for the update operation. Only works for updating data by values or functions.

match_all

• Type: boolean
• Default: false
• Whether to use all matching data for the update operation. If false, only the first matching data will be updated.

start_index

• Type: int
• Default: 0
• The starting index for the search for the update operation. Only works for updating data by values or functions.

use_validator

• Type: boolean
• Default: true
• Whether to use the validator in the schema for the update operation. If false, the validator will be skipped.

use_default

• Type: boolean
• Default: false
• Whether to use the default value in the schema if the validator fails for the update operation. If false, the default value will be skipped.

NimbusDBUpdateResult

A type for the result of the .update() method and its variants.

query-update.d.ts

type NimbusDBUpdateResult = {
  changes: {
    [primary: int]: {
      [prop: string]: [before: any, after: any];
    }
  }[];
  modified_count: int;
  invalid: (number | string)[];
  invalid_count: int;
  invalid_modified_count: int;
  updated: NimbusDBData[];  // isolated copy of the updated data
  updated_count: int;
}

NimbusDBUpsertOptions

A type for the options parameter of the .upsert() method.

query-upsert.d.ts

type NimbusDBUpsertOptions = Partial<{
  match_column: string;       // column to match (default = primary_col)
  force_insert: boolean;      // bypass column rules, type check, and validator for insert (default = false)
  force_update: boolean;      // bypass column rules, type check, and validator for update (default = false)
  start_index: int;           // start index for match (default = 0)
  length: int;                // length for match (default = data.length)
  keep_temp: boolean;         // keep temp data after insert (default = false)
  no_cache: boolean;          // don't cache the found data (default = false)

  // insert options
  sort: -1 | boolean | ((     // sort data after insert (default = -1). method = custom sort
    current: Struct,
    next: Struct
  ) => -1 | 0 | 1);
  sort_descending: boolean;   // sort descending (default = false). depend on `sort`
  sort_column: string;        // sort by column (default = primary_col). depend on `sort`

  // update options
  use_validator: boolean;     // use `validator` in the schema (default = true)
  use_default: boolean;       // use `default` in the schema if `validator` failed (default = false)
  insert_if_missing: boolean; // insert data if the `match_column` is missing (default = false, skip 'this' data)
}>;

match_column

• Type: string
• Default: primary_col
• The column used for determining the uniqueness of the data.

force_insert

• Type: boolean
• Default: false
• Whether to bypass column rules, type check, and validator for the insert operation.

force_update

• Type: boolean
• Default: false
• Whether to bypass column rules, type check, and validator for the update operation.

start_index

• Type: int
• Default: 0
• The starting index for the data search during the data-matching process.

length

• Type: int
• Default: data.length
• The maximum number of entries to process during the data-matching process.

keep_temp

• Type: boolean
• Default: false
• Whether to keep the user-defined temporary data after the operation.

no_cache

• Type: boolean
• Default: false
• Whether to disable the cache for the data-matching process.

sort

• Type: -1 | boolean | (current: Struct, next: Struct) => -1 | 0 | 1
• Default: -1
• Whether to sort the data after the insert operation.

sort_descending

• Type: boolean
• Default: false
• Whether to sort the data in descending order. Only works if the sort option is set to true.

sort_column

• Type: string
• Default: primary_col
• The column to sort the data by. Only works if the sort option is set to true.

use_validator

• Type: boolean
• Default: true
• Whether to use the validator in the schema for the update operation.

use_default

• Type: boolean
• Default: false
• Whether to use the default value in the schema if the validator fails for the update operation.

insert_if_missing

• Type: boolean
• Default: false
• Whether to insert data if the match_column is missing for the update operation. If false, the data will be skipped.

NimbusDBUpsertResult

A type for the result of the .upsert() method.

query-upsert.d.ts

type NimbusDBUpsertResult = {
  inserted: NimbusDBInsertResult;
  updated: NimbusDBUpdateResult;
  inserted_count: int;
  updated_count: int;
  invalid_count: int;      // missing match column
}