Module merger | Tarantool
Check out the new release policy

Module merger

The merger module takes a stream of tuples and provides access to them as tables.

The four functions for creating a merger object instance are:

The methods for using a merger object are:

merger.new_tuple_source(gen, param, state)

Create a new merger instance from a tuple source.

A tuple source just returns one tuple.

The generator function gen() allows creation of multiple tuples via an iterator.

The gen() function should return:

  • state, tuple each time it is called and a new tuple is available,
  • nil when no more tuples are available.
  • gen – function for iteratively returning tuples
  • param – parameter for the gen function

merger-object a merger object

Example: see merger_object:pairs() method.

merger.new_buffer_source(gen, param, state)

Create a new merger instance from a buffer source.

Parameters and return: same as for merger.new_tuple_source.

To set up a buffer, or a series of buffers, use the buffer module.

merger.new_table_source(gen, param, state)

Create a new merger instance from a table source.

Parameters and return: same as for merger.new_tuple_source.

Example: see merger_object:select() method., sources, options)

Create a new merger instance from a merger source.

A merger source is created from a key_def object and a set of (tuple or buffer or table or merger) sources. It performs a kind of merge sort. It chooses a source with a minimal / maximal tuple on each step, consumes a tuple from this source, and repeats.

  • key_def – object created with key_def
  • source – parameter for the gen() function
  • optionsreverse=true if descending, false or nil if ascending

merger-object a merger object

A key_def can be cached across requests with the same ordering rules (typically these would be requests accessing the same space).

Example: see merger_object:pairs() method.

object merger_object

A merger object is an object returned by:

It has methods:

merger_object:select([buffer[, limit]])

Access the contents of a merger object with familiar select syntax.


a table of tuples, similar to what select would return

Example with new_table_source():

-- Source via new_table_source, simple generator function
-- tarantool> s:select()
-- ---
-- - - [100]
--   - [200]
-- ...
function merger_function(param)
  k = k + 1
  if param[k] == nil then return nil end
  return box.NULL, param[k]
chunks[1] = {{100}} chunks[2] = {{200}} chunks[3] = nil
s = merger.new_table_source(merger_function, chunks)

The pairs() method (or the equivalent ipairs() alias method) returns a luafun iterator. It is a Lua iterator, but also provides a set of handy methods to operate in functional style.

  • tuple (table) – tuple or Lua table with field contents

the tuples that can be found with a standard pairs() function

Example with new_tuple_source():

-- Source via new_tuple_source, from a space of tables
-- The result will look like this:
-- tarantool> so:pairs():totable()
-- ---
-- - - [100]
--   - [200]
-- ...
merger = require('merger')'s')'i'){100}){200})
so = merger.new_tuple_source(

Example with two mergers:

-- Source via key_def, and table data

-- Create the key_def object
merger = require('merger')
key_def_lib = require('key_def')
key_def ={{
    fieldno = 1,
    type = 'string',
-- Create the table source
data = {{'a'}, {'b'}, {'c'}}
source = merger.new_source_fromtable(data)
i1 =, {source}):pairs()
i2 =, {source}):pairs()
-- t1 will be 'a' (tuple 1 from merger 1)
t1 = i1:head():totable()
-- t3 will be 'c' (tuple 3 from merger 2)
t3 = i2:head():totable()
-- t2 will be 'b' (tuple 2 from merger 1)
t2 = i1:head():totable()
-- i1:is_null() will be true (merger 1 ends)
-- i2:is_null() will be true (merger 2 ends)

More examples:

See which, in addition to discussing the merger API in detail, shows Lua code for handling many more situations than are in this manual’s brief examples.

Found what you were looking for?