Pages Navigation Menu

Creating a database

Creating a KitaroDB database

In this section… Creating a key-value pair database
Creating an intrusive-keyed database
Intrusive key and segment types
Duplicate intrusive keys

The first step when creating a KitaroDB database is to decide which type of database you want: a key-value pair database or an intrusive-keyed database with records. Key-value pair databases are the most common type for NoSQL, but if you want multiple-key access to structure-based records, or if you want to be able to use one or more parts (segments) of a record as a key, create an intrusive-keyed database.

Creating a key-value pair database

To create a key-value pair database, use the DB.Create[Async] method, passing the filename for the new database. This creates a DB object for the database, and it creates KitaroDB files on disk. The filename you supply to DB.Create[Async] is used for the index file and for the database as a whole (see Understanding KitaroDB files for more information). Note the following:

  • If a database exists with the name you specify, the existing database is either opened or overwritten depending on the DBCreateFlags value passed to DB.Create[Async].
  • Internally a key-value pair is a record with the following fields: an 8-byte hash, an 8-byte datetime, an int32 key length, a key, and a value.

Creating an intrusive-keyed database

The first step in creating an intrusive-keyed database is to define the keys. The first is automatically defined when you define the database (with DB.Create). Subsequent keys (there can be up to 255 total keys) are passed in an array to DB.Create when you define the database. (See step 3 below.) Note the following:

  • There must be at least one intrusive key (a primary key).
  • The primary key cannot be modifiable.
  • Numeric keys (including AutoSequence and AutoTime) cannot overlap.
  • If you want to sort on non-contiguous parts of a record or sort using a different type than the type defined for a record, create segmented keys (see step 1 below), which consist of several parts (segments) of a record, each with its own type, sort order, etc.

To create an intrusive-keyed database,

  1. If you want to create a segmented key, define each segment for the key with the DBKeySegment constructor. (In the next step, you’ll pass the DBKeySegment objects in an array{vector} to the DBKey constructor.) With the DBKeySegment constructor, you’ll specify the segment’s size, position (starting point in the record), and type (see Intrusive key and segment types below), as well as sort order. The order of the segments in the array determines the order of the segments in the resulting key.
  2. Create each key (one or more) using the DBKey constructor. Specify the length of the key, the key position, the key type (see Intrusive key and segment types below), whether duplicates are allowed (see Duplicate intrusive keys below), and so forth. If you defined segments for a key, pass the DBKey segment objects in an array{vector}.
  3. Create the database by calling DB.Create[Async]. If you have more than one key, pass an array{vector} of subsequent keys. You can also specify a maximum record length, which can be up to 2 GB, which is the default setting. (Note that this maximum includes from 32 bytes to 64K for overhead.) And you can use the DBCreateFlags enumeration to specify whether an existing KitaroDB database with the same name will be overwritten or opened. DB.Create[Async] creates a DB object for the database, and it creates KitaroDB files on disk. The filename you supply is used for the index file and for the database as a whole (see Understanding KitaroDB files for more information).

Intrusive key and segment types

You can specify the type of an intrusive key or key segment by using the DBKeyFlags enumeration with DB.Keys or DBKeySegment:

Alpha Case-sensitive alphanumeric. Standard 8-bit ISO characters are valid (although the entire binary range, 0 to 255 is allowed). This is the default.
AutoSequence An i8 key that creates an automatically incrementing number (starting with 1) that is guaranteed to generate a unique key within the file. The key’s value is generated on the initial DB.Insert[Async] and remains for the life of the record until deleted. Values range from 1 to 9,223,372,036,854,775,807.
AutoTime An i8 key that represents the time in microseconds of the last modification. An AutoTime key is automatically set to the current time (or that of the server) on every insert and update. (AutoTime numbers can be translated into datetime values with the format yyyymmddhhmissuuuu by using DBKey.ConvertBytesToDateTime.)
Binary Binary.
Integer Native integer (i1, i2, i4, i8). The valid range of values is the maximum negative value to the maximum positive value for the size of the key—for example, -128 to 127 for i1, or -32,768 to 32,767 for i2.
KeyValue Key-value pair.
NoCase Case-insensitive alphanumeric. Standard 8-bit ISO characters are valid (although the entire binary range, 0 to 255 is allowed).
Unsigned Native unsigned integer. The valid range of values is 0 to the maximum positive value for the size of the key—for example 0 to 255 for an unsigned i1, or 0 to 65,535 for an unsigned i2.

Duplicate intrusive keys

A duplicate key is a key value found in more than one record of a database. If you don’t allow duplicate values for a key, each record in the database is uniquely identified by its key value. If do you allow duplicate key values, many different records can contain the same value. For example, if you allow duplicates for a ZIP code key, multiple records can have the same ZIP code. If you define a key for a customer number field, though, you’ll probably want to prevent duplicate keys so that there is only one record for each customer number.