Insert data

Insertions are handled through table mutators which provide the ability to mutate a table in the form of adding, updating and deleting rows and cells.

 

In order to insert new cells into a table you have to obtain a ITableMutator from a ITable interface, for example:

Func<IEnumerable<Cell>> provider = ...;

var connectionString = "Provider=Hyper;Uri=net.tcp://localhost";
using (var context = Context.Create(connectionString))
using (var client = context.CreateClient())
using (var ns = client.OpenNamepace("example"))
using (var table = ns.OpenTable("users"))
using (var mutator = table.CreateMutator())
   mutator.Set(provider());
}

 

Cells passed to the ITableMutator are not immediately send to the database server; the Flush method causes any buffered data to be comitted to the database server:

mutator.Flush();

 

The MutatorSpec class defines the different behavior of the table mutator and provides some convenient default mutator specifications. We can distinguish between three main table mutator behaviors:

  • regular - default table mutator behavior
  • chunked - accumulates inserts and flushes them condinionally if a certain number of cells and/or chunk size in bytes have been reached
  • queued - establishes a producer/consumer semantic, where the client produces cells and another task performs the actual inserts. The queue blocks if a certain number of outstanding inserts have been reached

Combinations of the mutator behaviors are supported as well. For example creating a chunked and queued table mutator:

Func<IEnumerable<Cell>> provider = ...;

var mutatorSpec = MutatorSpec.CreateChunkedQueued();
mutatorSpec.FlushEachChunk = true; // yes, flush each chunk
mutatorSpec.MaxChunkSize = 128 * 1024; // 128kib
mutatorSpec.Capacity = 10000; // 10k cells

using (var mutator = table.CreateMutator(mutatorSpec))
   mutator.Set(provider());
}

 

The table mutator may be generate a unique, base85 encoded GUID, row key on demand. For example:

byte[] value = ...;

using (var mutator = table.CreateMutator())
   var key = new Key { ColumnFamily = "name" }; // w'out row key   
   mutator.Set(key, value, true); // generate and assign the row key
   var newlyGeneratedRowKey = key.Row;
}

 

If timestamps are not supplied on inserts, then they will be automatically assigned by the range server for non-indexed column families, and will be automatically assigned by the client library for indexed column families. It is therefore important that the system clock of the application servers be synchronized with the clocks of the range server machines.