Skip to content
Mauricio David edited this page Mar 15, 2015 · 18 revisions

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.

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");