Operations

Data operations

The basic data operations supported in Tarantool are:

• five data-manipulation operations (INSERT, UPDATE, UPSERT, DELETE, REPLACE), and
• one data-retrieval operation (SELECT).

All of them are implemented as functions in box.space submodule.

Examples:

• INSERT: Add a new tuple to space ‘tester’.

  The first field, field[1], will be 999 (MsgPack type is integer).

  The second field, field[2], will be ‘Taranto’ (MsgPack type is string).

  tarantool> box.space.tester:insert{999, 'Taranto'}
  

• UPDATE: Update the tuple, changing field field[2].

  The clause “{999}”, which has the value to look up in the index of the tuple’s primary-key field, is mandatory, because update() requests must always have a clause that specifies a unique key, which in this case is field[1].

  The clause “{{‘=’, 2, ‘Tarantino’}}” specifies that assignment will happen to field[2] with the new value.

  tarantool> box.space.tester:update({999}, {{'=', 2, 'Tarantino'}})
  

• UPSERT: Upsert the tuple, changing field field[2] again.

  The syntax of upsert() is similar to the syntax of update(). However, the execution logic of these two requests is different. UPSERT is either UPDATE or INSERT, depending on the database’s state. Also, UPSERT execution is postponed until after transaction commit, so, unlike update(), upsert() doesn’t return data back.

  tarantool> box.space.tester:upsert({999, 'Taranted'}, {{'=', 2, 'Tarantism'}})
  

• REPLACE: Replace the tuple, adding a new field.

  This is also possible with the update() request, but the update() request is usually more complicated.

  tarantool> box.space.tester:replace{999, 'Tarantella', 'Tarantula'}
  

• SELECT: Retrieve the tuple.

  The clause “{999}” is still mandatory, although it does not have to mention the primary key.

  tarantool> box.space.tester:select{999}
  

• DELETE: Delete the tuple.

  In this example, we identify the primary-key field.

  tarantool> box.space.tester:delete{999}
  

Summarizing the examples:

• Functions insert and replace accept a tuple (where a primary key comes as part of the tuple).
• Function upsert accepts a tuple (where a primary key comes as part of the tuple), and also the update operations to execute.
• Function delete accepts a full key of any unique index (primary or secondary).
• Function update accepts a full key of any unique index (primary or secondary), and also the operations to execute.
• Function select accepts any key: primary/secondary, unique/non-unique, full/partial.

See reference on box.space for more details on using data operations.

Complexity factors

In reference for box.space and Submodule box.index submodules, there are notes about which complexity factors might affect the resource usage of each function.