Data Structure

LiteDB works store data as documents in collections. Documents in LiteDB are multiples key-value pairs. See below a JSON document example:

{
    _id: 1,
    name: { first: "John", last: "Doe" },
    age: 37,
    salary: 3000.0,
    createdDate: { $date: "2014-10-30T00:00:00.00Z" },
    phones: ["8000-0000", "9000-0000"]
}

• _id contains document primary key - an unique value in collection
• name containts an embedded document with first and last fields
• age contains a Int32 value
• salary contains a Double value
• createDate contains a DateTime value
• phones contains an array of String

BSON

LiteDB store documents in BSON data format (BSON are Binary JSON). BSON is data file format to store complex data in a fast and simple way. It's used to write data in binary format. BSON supports more data types than JSON.

LiteDB use a subset of BSON data types. See all supported LiteDB BSON data types and .NET equivalent.

BSON Type	.NET type
MinValue	-
Null	Any .NET object with null value
Int32	System.Int32
Int64	System.Int64
Double	System.Double
String	System.String
Document	System.Collection.Generic.Dictionary<string, BsonValue>
Array	System.Collection.Generic.List<BsonValue>
Binary	System.Byte[]
ObjectId	LiteDB.ObjectId
Guid	System.Guid
Boolean	System.Boolean
DateTime	System.DateTime
MaxValue	-

JSON Extended

To serialize a document to JSON, LiteDB use a extended version of JSON to not loose any BSON data type that not exists in JSON. Extended data type is represent as an embedded document, using inital $ key and value as string.

BSON data type	JSON representation	Description
ObjectId	{ "$oid" : "507f1f55bcf96cd799438110" }	12 bytes in hex format
Date	{ "$date": "2015-01-01T00:00:00Z" }	UTC and ISO-8601 format
Guid	{ "$guid": "ebe8f677-9f27-4303-8699-5081651beb11" }
Binary	{ "$binary": "VHlwZSAob3IgcGFzdGUpIGhlcmUuLi4=" }	Byte array in base64 string format
Int64	{ "$numberLong": "12200000" }
MinValue	{ "$minValue": "1" }
MaxValue	{ "$maxValue": "1" }

LiteDB implements JSON in JsonSerializer static class. Serialize and deserialize used only BsonValue as input/output. If you want convert your object type, you need use BsonMapper before.

var customer = new Customer { Id = 1, Name = "John Doe" };

var doc = BsonMapper.Global.ToDocument(customer);

var jsonString = JsonSerialize.Serialize(doc, pretty, includeBinaryData);

JsonSerialize also supports TextReader and TextWriter to read/write direct from a file or Stream.

ObjectId

ObjectId is a 12 bytes BSON type:

• Timestamp: Value representing the seconds since the Unix epoch (4 bytes)
• Machine: Machine identifier (3 bytes)
• Pid: Process id (2 bytes)
• Increment: A counter, starting with a random value (3 bytes)

In LiteDB, documents stored in a collection require a unique _id field that acts as a primary key. Because ObjectIds are small, most likely unique, and fast to generate, LiteDB uses ObjectIds as the default value for the _id field if the _id field is not specified.

Unlike Guid data type, ObjectId are a sequencial number, so it's a better solution on indexing. ObjectId use hexa numbers to be represented in string

var id = ObjectId.NewObjectId();

// You can get creation datetime from an ObjectId
var date = id.CreationTime;

// ObjectId is represented in hex value
Debug.Print(id);
"507h096e210a18719ea877a2"