space_object:upsert()

space_object

Update or insert a tuple.

If there is an existing tuple which matches the key fields of tuple, then the request has the same effect as /reference/reference_lua/box_space/update and the {{operator, field_identifier, value}, ...} parameter is used. If there is no existing tuple which matches the key fields of tuple, then the request has the same effect as /reference/reference_lua/box_space/insert and the {tuple} parameter is used. However, unlike insert or update, upsert will not read a tuple and perform error checks before returning – this is a design feature which enhances throughput but requires more caution on the part of the user.

Parameters:

• space_object (space_object) — an object reference

• tuple (table/tuple) — default tuple to be inserted, if analogue isn't found

• operator (string) — operation type represented in string

• field_identifier (number) — what field the operation will apply to

• value (lua_value) — what value will be applied

Returns

null

Possible errors:

• It is illegal to modify a primary-key field.
• It is illegal to use upsert with a space that has a unique secondary index.
• ER_TRANSACTION_CONFLICT if a transaction conflict is detected in the MVCC transaction mode.

Complexity factors: Index size, Index type, number of indexes accessed, WAL settings.

Example:

 
box.space.tester:upsert({12,'c'}, {{'=', 3, 'a'}, {'=', 4, 'b'}})

For more usage scenarios and typical errors see Example: using data operations further in this section.