Object Mapping

LiteDB supports POCO classes as strong types documents. When you get LiteCollection instance from LiteDatabase.GetCollection<T> you can set <T> type. This type will be your document type. If this <T> was different than BsonDocument, LiteDB internally maps your class to BsonDocument. To do this, LiteDB uses the BsonMapper class:

// Simple strongly-typed document
public class Customer
{
    public ObjectId CustomerId { get; set; }
    public string Name { get; set; }
    public DateTime CreateDate { get; set; }
    public List<Phone> Phones { get; set; }
    public bool IsActive { get; set; }
}

var typedCustomerCollection = db.GetCollection<Customer>("customer");

var schemelessCollection = db.GetCollection("customer"); // <T> is BsonDocument

Mapper conventions

BsonMapper.ToDocument() auto converts each property of a class to a document field following these conventions:

• Classes must be public with a public default constructor (a constructor which takes no arguments)
• Properties must be public
• Properties can be read-only or read/write
• Class must have an Id property, <ClassName>Id property or any property with [BsonId] attribute
• A property can be decorated with [BsonIgnore] to not be mapped to a document field
• A property can be decorated with [BsonField] to customize the name of the document field
• No circular references allowed
• Max depth of 20 inner classes
• Class fields are not converted to document
• BsonMapper use a global instance that caches mapping information for better performance. This instance is on LiteDatabase.Mapper property too.

In addition to basic BSON types, BsonMapper maps others .NET types to BSON data type:

.NET type	BSON type
Int16, UInt16, Byte	Int32
UInt32 , UInt64	Int64
Single, Decimal	Double
Char, Enum	String
IList<T>	Array
T[]	Array
NameValueCollection	Document
IDictionary<K,T>	Document
Any other .NET type	Document

• Nullable<T> are accepted. If value is null, BSON type is Null, otherwise, mapper will use .NET underlying type.
• For IDictionary<K, T>, K key must be String or simple type (convertible using Convert.ToString(..)).

Register a custom type

You can register your own map function, using RegisterType<T> instance method. To register, you need create serialize/deserialize functions.

BsonMapper.Global.RegisterType<Uri>
(
    serialize: (uri) => uri.AbsoluteUri,
    deserialize: (bson) => new Uri(bson.AsString)
);

• serialize functions pass a <T> object instance as input parameter and expect return a BsonValue
• deserialize function pass a BsonValue object as input parameter and except return a <T> value
• RegisterType supports complex objects by using BsonDocument or BsonArray

Mapping options

BsonMapper class settings:

Name	Default	Description
SerializeNullValues	false	Serialize field if value is null
TrimWhitespace	true	Trim strings properties before map to document
EmptyStringToNull	true	Empty string convert to null
ResolvePropertyName	(s) => s	A function to map property name to document field name

BsonMapper offers 2 predefined functions to resolve property name: UseCamelCase() and UseLowerCaseDelimiter('_').

BsonMapper.Global.UseLowerCaseDelimiter('_');

public class Customer
{
    public int CustomerId { get; set; }

    public string FirstName { get; set; }

    [BsonField("customerLastName")]
    public string LastName { get; set; }
}

var doc = BsonMapper.Global.ToDocument(new Customer { FirstName = "John", LastName = "Doe" });

var id = doc["_id"].AsInt;
var john = doc["first_name"].AsString;
var doe = doc["customerLastName"].AsString;

AutoId

By default, typed documents will receive an auto Id value on insert. LiteDB support auto-id for this data types:

.NET data type	New Value
ObjectId	ObjectId.NewObjectId()
Guid	Guid.NewGuid()
Int32	Auto-increment, per collection, starting in 1

But if you don't want to use any of the built-in methods, or want another data type for Id, you can set it yourself:

var customer = new Customer { Id = "john-doe", Name = "John Doe" };

You also can create your own auto-id function, using RegisterAutoId<T>:

BsonMapper.Global.RegisterAutoId<long>
(
    isEmpty: (value) => value == 0,
    newId: (collection) => DateTime.UtcNow.Ticks
);

public class Calendar
{
    public long CalendarId { get; set; }
}

• isEmpty returns true to indicate when this type is considerate empty. In this example, zero will be empty value.
• newId returns new id value. Gets LiteCollection<BsonDocument> instance as input parameter that you may use to determine the new Id. In this example, the collection is ignored and the current Ticks value is returned.

Index definition

BsonMapper supports index definition direct on a property using the [BsonIndex] attribute. You can define index options like, Unique or IgnoreCase. This is useful to avoid always needing to call col.EnsureIndex("field") before running a query.

public class Customer
{
    public int Id { get; set; }
    
    [BsonIndex]
    public string Name { get; set; }
    
    [BsonIndex(new IndexOptions { Unique = true, EmptyStringToNull = false, RemoveAccents = false })]
    public string Email { get; set; }
}

IndexOptions class settings:

Name	Default	Description
Unique	false	Do not allow duplicates values in index
IgnoreCase	true	Store string on index in lowercase
RemoveAccents	true	Store string on index removing accents
TrimWhitespace	true	Store string on index removing trimming spaces
EmptyStringToNull	true	If string is empty, convert to Null

To get better performance, [BsonIndex] checks only if the index exists, but does not check if you are changing options. To change an index option in a existing index you must run EnsureIndex with the new index options. This method drops the current index and creates a new one with the new options.

Do not use [BsonIndex] attribute on your Id primary key property. This property already has an unique index with the default options.