Tutorial

Inserting Data

Unlike a relational database management system (RDBMS), upscaledb does not know about the “schema” or the layout of your records, but it is aware of the type of your keys!

To insert a key/record pair, the caller has to create two structures - one for the key and one for the record, initialize them and then call ups_db_insert. (You can also use Database Cursors to insert keys; Database Cursors are explained in a later chapter.)

The second parameter of ups_db_insert is a Transaction handle; if you do not use Transactions, then set the argument to NULL. Transactions are also covered in a later chapter.

The fourth parameter, flags, can be set to 0. There are two optional (exclusive) flags: UPS_DUPLICATE inserts a duplicate of this key, if the key already exists. Duplicate keys are covered in a later chapter. UPS_OVERWRITE will overwrite the key with the new record if the key already exists. If none of these flags is specified, ups_insert will fail with error UPS_DUPLICATE_KEY if you insert a key which already exists.

ups_status_t
ups_db_insert (ups_db_t *db, ups_txn_t *txn, ups_key_t *key,
                ups_record_t *record, uint32_t flags);

API reference for ups_db_insert

It is important that you initialize the ups_key_t and ups_record_t structures with zeroes before setting the values, or with ups_make_key and ups_make_record. The following code initializes a key/record pair with the strings “color”/“green” and inserts them.

ups_key_t key = ups_make_key((void *)"color", strlen("color") + 1);
ups_record_t record = ups_make_record((void *)"green", strlen("green") + 1);

if ((st = ups_db_insert (db, NULL, &key, &record, 0)) != UPS_SUCCESS) {
  printf ("error %d (%s)\n", st, ups_strerror (st));
  exit (–1);
}