Expressions

Expressions are path or formulas to access and modify your document data. Based on JSON path article (http://goessner.net/articles/JsonPath/), LiteDB support a near syntax to navigate in a single document. Path always returns an IEnumerable<BsonValue> in any case.

BsonExpression are the class that parse a string expression (or path) and compile into a LINQ Expression to be fast evaluate by LiteDB. Parser uses

Path starts with $: $.Address.Street
Int values starts with [0-9]*: 123
Double values starts with [0-9].[0-9]: 123.45
Strings are represented with a single ': 'Hello World'
Null are just null
Bool are represented using true or false keyword.
Functions are represented with FUNCTION_NAME(par1, par2, ...): LOWER($.Name)

Examples:

$.Price
$.Price + 100
SUM($.Items[*].Price)

var expr = new BsonExpression("SUM($.Items[*].Unity * $.Items[*].Price)");
var total = expr.Execute(doc, true).First().AsDecimal;

Expressions also can be used in:

Create an index based on an expression:
- collection.EnsureIndex("Name", true, "LOWER($.Name)")
- collection.EnsureIndex(x => x.Name, true, "LOWER($.Name)")
Query documents inside a collection based on expression (full scan search)
- Query.EQ("SUBSTRING($.Name, 0, 1)", "T")
Update shell command
- db.customers.update $.Name = LOWER($.Name) where _id = 1
Create new document result in SELECT shell command
- db.customers.select $._id, ARRAY(UPPER($.Books[*].Title)) AS titles where $.Name startswith "John"

Path

$ - Root
$.Name - Name field
$.Name.First - First field from a Name subdocument
$.Books - Returns book array value
$.Books[0] - Return first book inside books array
$.Books[*] - Return all books inside books array
$.Books[*].Title Return all titles from all books
$.Books[-1] - Return last book inside books array

Path also support expression to filter child node

$.Books[@.Title = 'John Doe'] - Return all books where title is John Doe
$.Books[@.Price > 100].Title - Return all titles where book price are greater than 100

Inside array, @ represent current sub document. It's possible use functions inside expressions too:

$.Books[SUBSTRING(LOWER(@.Title), 0, 1) = 'j'] - Return all books with title starts with T or t.

Functions

Functions are always works in IEnumerable<BsonValue> as input/output parameters.

LOWER($.Name) - Returns IEnumerable with a single element
LOWER($.Books[*].Title) - Returns IEnumerable with all values in lower case

Operators

Operators are function to implement same math syntax. Support

ADD(<left>, <right>): <left> + <right> (If any side are string, concat values and return as string.)
MINUS(<left>, <right>): <left> - <right>
MULTIPLY(<left>, <right>): <left> * <right>
DIVIDE(<left>, <right>): <left> / <right>
MOD(<left>, <right>): <left> % <right>
EQ(<left>, <right>): <left> = <right>
NEQ(<left>, <right>): <left> != <right>
GT(<left>, <right>): <left> != <right>
GTE(<left>, <right>): <left> >= <right>
LT(<left>, <right>): <left> < <right>
LTE(<left>, <right>): <left> <= <right>
AND(<left>, <right>): <left> && <right> (Left and right must be a boolean)
OR(<left>, <right>): <left> || <right>: Left and right must be a boolean)
IIF(<condition>, <ifTrue>, <ifFalse>): (Condition must be a boolean value)

Examples

db.dummy.select ((2 + 11 % 7)-2)/3 => 1.33333
db.dummy.select 'My Id is ' + $._id => "My Id is 1"`
db.customers.select $._id, IIF($._id < 20, 'Less', 'Greater') + ' than twenty' as Info
- => { _id: 1, Info: "Less than twenty" }

String

String function will work only if your <values> are string. Any other data type will skip results

Function	Description
`LOWER(<values>)`	Same `ToLower()` from `String`. Returns a string
`UPPER(<values>)`	Same `ToUpper()` from `String`. Returns a string
`SUBSTRING(<values>, <index>, <length>)`	Same `Substring()` from `String`. Returns a string
`LPAD(<values>, <totalWidth>, <paddingChar>)`	Same `PadLeft()` from `String`. Returns a string
`RPAD(<values>, <totalWidth>, <paddingChar>)`	Same `PadRight()` from `String`. Returns a string
`FORMAT(<values>, <format>)`	Same `Format()` from `String`. Works if any data type (use `RawValue`). Returns a string

Aggregates

Function	Description
`SUM(<values>)`	Sum all number values and returns a number
`COUNT(<values>)`	Count all values and returns a integer
`MIN(<values>)`	Get min value in value list
`MAX(<values>)`	Get max value in value list
`AVG(<values>)`	Calculate average in list of values

All aggregates functions works in a single document and always with an IEnumerable selector of an array: (SUM($.Items[*].Price))

DataType

Function	Description
`ARRAY(<values>)`	Convert all values into a single array
`IS_DATE(<values>)`	Return true for each value that are date
`IS_NUMBER(<values>)`	Return true for each value that are a number
`IS_STRING(<values>)`	Return true for each value that are string