space_object:upsert()

object space_object

space_object:upsert(tuple, {{operator, field_no, value}, ...})

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 space_object:update() and the {{operator, field_no, 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 space_object: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_no (number) – what field the operation will apply to. The field number can be negative, meaning the position from the end of tuple. (#tuple + negative field number + 1) value (lua_value) – what value will be applied

Return:

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.

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.