space_object:upsert() | Tarantool

space_object:upsert()

object space_object
space_object:upsert({tuple}, {{operator, field_identifier, 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_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 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_identifier (number) – what field the operation will apply to
  • 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.
  • 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.

Found what you were looking for?
Feedback