Data Structure

LiteDB store data as documents, which are JSON-like field and value pairs. Documents are a schemaless data structure. Each document has your data and structure together.

{
    _id: 1,
    name: { first: "John", last: "Doe" },
    age: 37,
    salary: 3456.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

LiteDB stores documents in collections. A collection is a group of related documents that have a set of shared common indexes. Collections are analogous to a table in relational databases.

Data Model

LiteDB, as a document database, has no JOIN operation between collections. In a document database you have 2 ways to reference your data structures.

Denormalized Data Model

In this option you will embedded child document in parent document. This will produce a single document with hole information. It's great to read performance and require a single query to return all information you need.

For write operations, this solution is not too good. You always need write all document information (with all embedded documents) and this big document can fragment data pages. Too big document are slow and consume too many memory.

{
    _id: 1,
    name: "John Doe",
    address: {
        street: "Av. Protasio Alves, 1331",
        city: "Porto Alegre",
        contry: "Brazil"
    }
}

• Address is an embedded document in Customer document.

Normalized Data Model

In this way you create a reference in your document do another document. This solution produce less duplicate data, but also more queries to run to get all data information. This is better solution when you need update child document.

To implement normalized data model, you can use two techniques:

• Manual reference: Is when you just add a new field in your document that refer to another document id.
• DbRef<T> reference: This class produce a reference to another document and can be used in Include operation. See Collections.

{
    _id: 1,
    orderDate: { $date: "2015-01-01" },
    customerId: 123,
}

• customerId is a manual reference to customer document

BSON

LiteDB store documents in BSON data format (BSON are Binary JSON). BSON is a binary representation of JSON with additional type information. In the documents, the value of a field can be any of the BSON data types, including other documents, arrays, and arrays of documents. BSON is a fast and simple way to serialize documents in binary format.

LiteDB use a subset only 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 type information 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": "VHlwZSgaFc3sdcGFzUpcmUuLi4=" }	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"

// Create a instance based on hex representation
var nid = new ObjectId("507h096e210a18719ea877a2");